@br-validators/cli

@br-validators/cli

Terminal CLI for all Brazilian document validators in @br-validators/core v1.10.0.

Repo: github.com/open-data-brazil/br-validators

Install

npm install -g @br-validators/cli

Or run without install:

npx @br-validators/cli --help

Global commands

br-validators list
br-validators --version
br-validators --help

Per-type commands

br-validators cnpj validate 12ABC34501DE35 --json --source
br-validators cpf validate 12345678909
br-validators cep format 01310100
br-validators telefone validate 11999999999
br-validators cnh validate 62472927637
br-validators renavam validate 63977791104
br-validators titulo-eleitor validate 004356870906
br-validators nfe-chave validate 52060433009911002506550120000007800267301615 --json
br-validators nfe-chave parse 52060433009911002506550120000007800267301615 --json
br-validators brcode validate '<emv-payload>' --json
br-validators placa validate ABC1D23
br-validators pis-pasep validate 10027230888
br-validators pix validate [e-mail]
br-validators boleto validate '03399.02579 08991.834006 71742.301014 6 14500000099668'
br-validators cartao validate 4111111111111111
br-validators cartao-credito validate 4111111111111111
br-validators ie validate 110042490114 --uf SP --json
br-validators ie validate P-01100424.3/002 --uf SP   # SP produtor rural (auto-detect)

Actions (per-type)

Action	Description
validate	Check format + check digits
format	Apply official mask
strip	Normalize to canonical digits/chars
parse	NF-e chave, BR Code
convert	Boleto linha ↔ barcode; placa legacy → Mercosul
detect	PIX key type; boleto input kind; cartão brand

Platform commands

Command	Description
detect [value]	Classify raw input; --uf for IE
sanitize <type> [value]	ETL fixes + validate; --uf for inscricao-estadual
mask <type> [value]	Unified display mask; --uf for IE / RG
compare <type> <valueA> <valueB>	Normalized equality; --uf for IE / RG / título
batch <type>	Bulk validate (stdin or --file, or CSV with --col); --delimiter, --skip-header; --uf, --limit
diff <type> <valueA> <valueB>	Field-level diff; --uf for IE / RG / título
generate <type>	Synthetic test document; --seed, --masked, --format

br-validators detect '123.456.789-09' --json
br-validators detect '110042490114' --uf SP --json
br-validators sanitize cpf ' 123.456.789-09 ' --json
br-validators sanitize inscricao-estadual '110.042.490.114' --uf SP --json
br-validators mask cpf 12345678909 --json
br-validators mask inscricao-estadual 110042490114 --uf SP --json
br-validators compare cpf '123.456.789-09' 12345678909 --json
br-validators batch cpf --file values.txt --json
br-validators batch cpf --file payroll.csv --col cpf --json
br-validators sanitize pix ' [e-mail] ' --json
br-validators csosn lookup 102 --json
br-validators diff cpf 12345678909 12345678901 --json
br-validators generate cpf --seed 42 --masked --json
br-validators generate cnpj --format alphanumeric --seed 7 --json
br-validators generate placa --format mercosul --seed 3

Reference data lookup

Offline embedded datasets — delegates to @br-validators/core/*.

Bacen banks

br-validators bancos lookup 001 --json
br-validators bancos lookup 18236120 --verbose
br-validators bancos list --limit 20 --json

Fiscal (26c)

br-validators natureza-juridica lookup 2062 --json
br-validators nbs lookup 1.1502.50.00 --verbose
br-validators cest lookup 0302100 --json
br-validators cnae lookup 6201501 --json
br-validators cnae search "web design" --limit 5
br-validators cfop lookup 1102 --json
br-validators cfop search compra --limit 5
br-validators ncm lookup 12011000 --json
br-validators ncm search soja --limit 5
br-validators cbo lookup 212405 --json
br-validators cbo search analista --limit 5

Fiscal reference (33o–34)

br-validators iss-municipal lookup 3550308 --json
br-validators iss-municipal list --uf SP --limit 10 --json
br-validators iss-municipal search campinas --uf SP --limit 5 --json
br-validators iss-municipal resolve SP "São Paulo" --verbose

Partial embed (~500 municipalities). Estimation / quoting only — not NFSe emission.

Geography & calendar (27d)

br-validators ibge lookup 3550308 --json
br-validators ibge list estados --limit 5
br-validators ibge list municipios --uf SP --limit 10 --json
br-validators tse-municipios lookup 71072 --verbose
br-validators feriados list --year 2026 --json
br-validators cep faixa 01310 --json
br-validators ddd lookup 11 --verbose

Trade (26d)

br-validators moedas lookup BRL --json
br-validators paises-bacen lookup 1058 --verbose
br-validators incoterms lookup FOB --json
br-validators ptax lookup USD --verbose
br-validators ptax lookup USD 2026-06-20 --json --verbose
br-validators ptax historico USD 2026-06-01 2026-06-26 --json --verbose

PTAX: offline embed — last 90 business days (janelaDiasUteis: 90; not live Bacen). --verbose prints dataReferencia, isStale, and warning when stale. ptax historico lists all embedded rows in a date range.

Finance (SELIC)

br-validators selic --verbose
br-validators selic --date 2026-06-18 --json --verbose

--verbose includes dataReferencia, isStale, and dataset capturadoEm (same pattern as PTAX).

Logistics (26e)

br-validators portos lookup BRSSZ --json
br-validators aeroportos lookup GRU --verbose
br-validators aeroportos lookup SBGR --json

Exit code	Meaning
0	Record found
1	Not found
2	Usage error

Flags

Flag	Description
--json	JSON output
--quiet / -q	Exit code only (CI)
--verbose	PTAX / SELIC: dataReferencia, isStale, warning; other lookups: dataset metadata
--file / -f	Read value from file
--source	Print official source URL (per-type)
--uf	Required for IE / detect / sanitize IE; filter for ibge list municipios, iss-municipal list, and iss-municipal search

CI

br-validators cnpj validate "$CNPJ" --quiet || exit 1
br-validators detect "$RAW_INPUT" --json --quiet || exit 1

License

MIT