Shield Base

CLI Reference

Complete reference for the shield-base command, all global flags, and the compile, types, and lm-read subcommands.

The shield-base command is the primary entry point. Running it without arguments starts the interactive wizard. You can also drive it entirely from flags for CI/CD pipelines and automated scripts.

Use --help on any command or subcommand to print available options:

pnpm dlx @riavzon/shield-base --help
pnpm dlx @riavzon/shield-base compile --help
pnpm dlx @riavzon/shield-base lm-read --help
pnpm dlx @riavzon/shield-base types --help

yarn dlx @riavzon/shield-base --help
yarn dlx @riavzon/shield-base compile --help
yarn dlx @riavzon/shield-base lm-read --help
yarn dlx @riavzon/shield-base types --help

npx @riavzon/shield-base --help
npx @riavzon/shield-base compile --help
npx @riavzon/shield-base lm-read --help
npx @riavzon/shield-base types --help

bunx @riavzon/shield-base --help
bunx @riavzon/shield-base compile --help
bunx @riavzon/shield-base lm-read --help
bunx @riavzon/shield-base types --help

Global Flags

Source Selection

Flag	Description
`--all`	Skip interactive selection and fetch all available sources.
`--bgp`	Compile BGP/ASN routing data.
`--city`	Compile IP-to-city geolocation data.
`--geo`	Compile IP-to-country geolocation data.
`--proxy`	Compile proxy and anonymizer IP lists.
`--tor`	Compile Tor relay and exit node data.
`--seo`	Compile verified search engine crawler IP ranges.
`--useragent`	Compile suspicious HTTP user-agent patterns into LMDB.
`--email`	Compile the disposable email domain blocklist into LMDB.
`--l1`	Compile FireHOL Level 1 threat intelligence.
`--l2`	Compile FireHOL Level 2 threat intelligence.
`--l3`	Compile FireHOL Level 3 threat intelligence.
`--l4`	Compile FireHOL Level 4 threat intelligence.
`--anonymous`	Compile the FireHOL anonymity network list (Tor exits, I2P, VPNs).

Control Flags

Flag	Description
`--parallel`	Run all compilation jobs concurrently.
`--refresh`	Force re-download of previously compiled sources using cached config.
`--refreshAll`	Force re-download and recompilation of all sources using cached config.
`--acceptFireholRisk`	Acknowledge the FireHOL license. Required for `--l1` through `--l4` and `--anonymous`.
`--contact <str>`	BGP.tools contact string. Required format: `<name> [url] - <email>`.
`--path <dir>`	Output directory for compiled databases. Defaults to the current working directory.
`--help`, `-h`	Show help for the main command or a subcommand.

Examples

# Compile everything in parallel, non-interactively
pnpm dlx @riavzon/shield-base --all --parallel --contact "Name https://example.com - [email protected]" --acceptFireholRisk

# Compile only Tor and proxy data
pnpm dlx @riavzon/shield-base --tor --proxy

# Compile BGP and FireHOL Level 1 to a specific directory
pnpm dlx @riavzon/shield-base --bgp --l1 --acceptFireholRisk --contact "Name - [email protected]" --path ./data/mmdb

# Refresh all previously compiled sources
pnpm dlx @riavzon/shield-base --refreshAll

# Compile LMDB sources only (no mmdbctl needed)
pnpm dlx @riavzon/shield-base --useragent --email

yarn dlx @riavzon/shield-base --all --parallel --contact "Name https://example.com - [email protected]" --acceptFireholRisk
yarn dlx @riavzon/shield-base --tor --proxy
yarn dlx @riavzon/shield-base --bgp --l1 --acceptFireholRisk --contact "Name - [email protected]" --path ./data/mmdb
yarn dlx @riavzon/shield-base --refreshAll
yarn dlx @riavzon/shield-base --useragent --email

npx @riavzon/shield-base --all --parallel --contact "Name https://example.com - [email protected]" --acceptFireholRisk
npx @riavzon/shield-base --tor --proxy
npx @riavzon/shield-base --bgp --l1 --acceptFireholRisk --contact "Name - [email protected]" --path ./data/mmdb
npx @riavzon/shield-base --refreshAll
npx @riavzon/shield-base --useragent --email

bunx @riavzon/shield-base --all --parallel --contact "Name https://example.com - [email protected]" --acceptFireholRisk
bunx @riavzon/shield-base --tor --proxy
bunx @riavzon/shield-base --bgp --l1 --acceptFireholRisk --contact "Name - [email protected]" --path ./data/mmdb
bunx @riavzon/shield-base --refreshAll
bunx @riavzon/shield-base --useragent --email

`compile` Subcommand

Generates MMDB or LMDB databases and TypeScript types from your own JSON data files.

Argument / Flag	Type	Description
`<INPUT>`	Positional	One or more paths to JSON data files, separated by spaces.
`--type`	`mmdb` \| `lmdb`	Required. Use `mmdb` for IP range data (`range` field required). Use `lmdb` for key-value data (`key` or `id` field required).
`--name`	string	Required. Base name for the output files.
`--outputDir`	string	Directory to save the compiled files. Defaults to `./`.
`--types`	boolean	Generate TypeScript type definitions. Defaults to `true`.
`--no-types`	flag	Disable TypeScript type generation.
`--help`, `-h`	flag	Show help for this subcommand.

# Compile a single MMDB database
pnpm dlx @riavzon/shield-base compile --type mmdb --name myRanges --outputDir ./out example.json

# Compile a single LMDB database
pnpm dlx @riavzon/shield-base compile --type lmdb --name myKeys --outputDir ./out example.json

# Compile multiple JSON files (batch)
pnpm dlx @riavzon/shield-base compile --type mmdb --name myRanges --outputDir ./out file1.json file2.json

# Disable type generation
pnpm dlx @riavzon/shield-base compile --type lmdb --name myKeys --no-types data.json

yarn dlx @riavzon/shield-base compile --type mmdb --name myRanges --outputDir ./out example.json
yarn dlx @riavzon/shield-base compile --type lmdb --name myKeys --outputDir ./out example.json
yarn dlx @riavzon/shield-base compile --type mmdb --name myRanges --outputDir ./out file1.json file2.json
yarn dlx @riavzon/shield-base compile --type lmdb --name myKeys --no-types data.json

npx @riavzon/shield-base compile --type mmdb --name myRanges --outputDir ./out example.json
npx @riavzon/shield-base compile --type lmdb --name myKeys --outputDir ./out example.json
npx @riavzon/shield-base compile --type mmdb --name myRanges --outputDir ./out file1.json file2.json
npx @riavzon/shield-base compile --type lmdb --name myKeys --no-types data.json

bunx @riavzon/shield-base compile --type mmdb --name myRanges --outputDir ./out example.json
bunx @riavzon/shield-base compile --type lmdb --name myKeys --outputDir ./out example.json
bunx @riavzon/shield-base compile --type mmdb --name myRanges --outputDir ./out file1.json file2.json
bunx @riavzon/shield-base compile --type lmdb --name myKeys --no-types data.json

import { compiler } from '@riavzon/shield-base';

// MMDB (IP range data)
await compiler({
  type: 'mmdb',
  input: {
    data: 'example.json',
    dataBaseName: 'myRanges',
    mmdbPath: 'mmdbctl',
    outputPath: './out',
    generateTypes: true,
  },
});

// LMDB (key-value data)
await compiler({
  type: 'lmdb',
  input: {
    data: 'example.json',
    dataBaseName: 'myKeys',
    outputPath: './out',
    generateTypes: true,
  },
});

When processing multiple input files, the first output uses your --name (for example, myRanges.mmdb), and subsequent files are indexed (myRanges-1.mmdb, myRanges-2.mmdb).

For mmdb, every record in the JSON input must contain a range field with an IPv4/IPv6 address or CIDR range. For lmdb, every record must contain a key or id field used as the lookup key.

`lm-read` Subcommand

Reads and inspects data from an LMDB .mdb database. Pass the full path to the .mdb environment directory, not its parent.

Flag	Type	Description
`--path`	string	Required. Full path to the `.mdb` database file.
`--name`	string	Required. Name of the LMDB sub-database.
`--operation`	enum	Required. One of `get`, `range`, `prefix`, `count`, `exists`, `stats`, `drop`.
`--key`	string	Exact key to look up. Required for `get` and `exists`.
`--prefix`	string	Key prefix to search. Required for `prefix`.
`--limit`	string	Maximum records to return. Used by `range` and `prefix`. Defaults to `10`.
`--help`, `-h`	flag	Show help.

Operation	Description
`get`	Retrieve a single record by exact key.
`range`	Return the first N records in B-tree order.
`prefix`	Find all keys starting with the given prefix.
`count`	Count total records in the database.
`exists`	Check whether a key exists.
`stats`	Print LMDB environment statistics (page size, depth, record count).
`drop`	Permanently delete the database. Irreversible.

# Get a record by exact key
pnpm dlx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation get --key "sqlmap"

# List the first 5 records in B-tree order
pnpm dlx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation range --limit 5

# Find all keys starting with a prefix
pnpm dlx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation prefix --prefix "curl"

# Count all records
pnpm dlx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation count

# Check if a key exists
pnpm dlx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation exists --key "nmap"

yarn dlx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation get --key "sqlmap"
yarn dlx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation range --limit 5
yarn dlx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation prefix --prefix "curl"
yarn dlx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation count
yarn dlx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation exists --key "nmap"

npx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation get --key "sqlmap"
npx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation range --limit 5
npx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation prefix --prefix "curl"
npx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation count
npx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation exists --key "nmap"

bunx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation get --key "sqlmap"
bunx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation range --limit 5
bunx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation prefix --prefix "curl"
bunx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation count
bunx @riavzon/shield-base lm-read --path ./out/useragent.mdb --name useragent --operation exists --key "nmap"

import { getByKey, getRange, getByPrefix, countRecords, doesExist } from '@riavzon/shield-base';

const dbPath = './out/useragent.mdb';
const dbName = 'useragent';

const record = getByKey(dbPath, dbName, 'sqlmap');
const first5 = getRange(dbPath, dbName, 5);
const curlMatches = getByPrefix(dbPath, dbName, 'curl', 20);
const total = countRecords(dbPath, dbName);
const exists = doesExist(dbPath, dbName, 'nmap');

The drop operation permanently deletes the database and cannot be undone.

`types` Subcommand

Generates standalone TypeScript type definitions from JSON files or raw JSON strings without compiling a database.

Argument / Flag	Type	Description
`<INPUT>`	Positional	One or more JSON file paths or raw JSON strings, separated by spaces.
`--name`	string	Required. Base name for the generated type file.
`--outputDir`	string	Directory to save the generated `.ts` file. Defaults to `./`.
`--help`, `-h`	flag	Show help.

# From a JSON file
pnpm dlx @riavzon/shield-base types --name myData --outputDir ./src/types data.json

# From a raw JSON string
pnpm dlx @riavzon/shield-base types --name myData --outputDir ./src/types '{"key": "value", "count": 1}'

# Batch: multiple inputs
pnpm dlx @riavzon/shield-base types --name batchTypes --outputDir ./src/types file1.json file2.json

yarn dlx @riavzon/shield-base types --name myData --outputDir ./src/types data.json
yarn dlx @riavzon/shield-base types --name myData --outputDir ./src/types '{"key": "value", "count": 1}'
yarn dlx @riavzon/shield-base types --name batchTypes --outputDir ./src/types file1.json file2.json

npx @riavzon/shield-base types --name myData --outputDir ./src/types data.json
npx @riavzon/shield-base types --name myData --outputDir ./src/types '{"key": "value", "count": 1}'
npx @riavzon/shield-base types --name batchTypes --outputDir ./src/types file1.json file2.json

bunx @riavzon/shield-base types --name myData --outputDir ./src/types data.json
bunx @riavzon/shield-base types --name myData --outputDir ./src/types '{"key": "value", "count": 1}'
bunx @riavzon/shield-base types --name batchTypes --outputDir ./src/types file1.json file2.json

import { generateTypeFile } from '@riavzon/shield-base';

// From a file path
generateTypeFile('./data.json', 'myData', './src/types');

// From a raw JSON string
generateTypeFile('{"id": 1, "value": "example"}', 'myData', './src/types');

// From a JavaScript object in memory
const data = { id: 1, value: 'example', tags: ['a', 'b'] };
generateTypeFile(data, 'myData', './src/types');

Output files are named <name>Types.ts. Batch inputs produce indexed files: batchTypesTypes.ts, batchTypes-1Types.ts, and so on.

Getting Started

Data Sources