@br-validators/cli 1.3.0 → 1.5.0

package/README.md

@@ -88,6 +88,50 @@ br-validators generate placa --format mercosul --seed 3
 
 ---
 
+## Reference data lookup
+
+Offline embedded datasets — delegates to `@br-validators/core/*`.
+
+### Bacen banks
+
+```bash
+br-validators bancos lookup 001 --json
+br-validators bancos lookup 18236120 --verbose
+br-validators bancos list --limit 20 --json
+```
+
+### Fiscal (26c)
+
+```bash
+br-validators natureza-juridica lookup 2062 --json
+br-validators nbs lookup 1.1502.50.00 --verbose
+br-validators cest lookup 0302100 --json
+```
+
+### Trade (26d)
+
+```bash
+br-validators moedas lookup BRL --json
+br-validators paises-bacen lookup 1058 --verbose
+br-validators incoterms lookup FOB --json
+```
+
+### Logistics (26e)
+
+```bash
+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 |
@@ -97,6 +141,8 @@ br-validators generate placa --format mercosul --seed 3
 | `--file` / `-f` | Read value from file |
 | `--source` | Print official source URL (per-type) |
 | `--uf` | Required for IE / detect / sanitize IE |
+| `--verbose` | Include dataset capture date (`bancos`, reference `lookup` commands) |
+| `--limit` | Max rows for `bancos list` |
 
 ### CI
 

package/dist/index.js

@@ -9,12 +9,8 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 // src/program.ts
 import { Command } from "commander";
 
-// src/commands/brcode.ts
-import {
-  BRCODE_OFFICIAL_SOURCE_URL,
-  parseBrCode,
-  validateBrCode
-} from "@br-validators/core";
+// src/commands/bancos/list.ts
+import { BANCOS_DATA_VERSION as BANCOS_DATA_VERSION2, getBancos } from "@br-validators/core/bancos";
 
 // src/constants.ts
 var SUPPORTED_TYPES = ["cnpj", "cpf", "cep", "telefone", "cnh", "renavam", "titulo-eleitor", "nfe-chave", "brcode", "placa", "pis-pasep", "pix", "boleto", "cartao", "ie"];
@@ -24,7 +20,289 @@ var EXIT = {
   USAGE: 2
 };
 
+// src/commands/bancos/lookup.ts
+import {
+  BANCOS_DATA_VERSION,
+  getBancoPorCodigo,
+  getBancoPorIspb
+} from "@br-validators/core/bancos";
+function normalizeBancosLookupInput(raw) {
+  const digits = raw.replace(/\D/g, "");
+  if (digits.length === 8) {
+    return { kind: "ispb", value: digits.padStart(8, "0") };
+  }
+  if (digits.length >= 1 && digits.length <= 3) {
+    return { kind: "codigo", value: digits.padStart(3, "0").slice(-3) };
+  }
+  return null;
+}
+function lookupBanco(raw) {
+  const normalized = normalizeBancosLookupInput(raw);
+  if (!normalized) {
+    return void 0;
+  }
+  return normalized.kind === "ispb" ? getBancoPorIspb(normalized.value) : getBancoPorCodigo(normalized.value);
+}
+function formatBancoHuman(banco) {
+  return `${banco.codigo} \u2014 ${banco.nome} (ISPB ${banco.ispb})`;
+}
+function runBancosLookupCommand(input, options, io = { stdout: [], stderr: [] }) {
+  const normalized = normalizeBancosLookupInput(input);
+  if (!normalized) {
+    io.stderr.push("Invalid bank code or ISPB. Use 3-digit COMPE (e.g. 001) or 8-digit ISPB.");
+    return EXIT.USAGE;
+  }
+  const banco = lookupBanco(input);
+  if (!banco) {
+    io.stderr.push(`Bank not found: ${input}`);
+    return EXIT.INVALID;
+  }
+  if (options.json) {
+    const payload = { ok: true, banco };
+    if (options.verbose) {
+      payload.capturadoEm = BANCOS_DATA_VERSION.capturadoEm;
+    }
+    io.stdout.push(JSON.stringify(payload, null, 2));
+    return EXIT.OK;
+  }
+  io.stdout.push(formatBancoHuman(banco));
+  if (options.verbose) {
+    io.stdout.push(`capturadoEm: ${BANCOS_DATA_VERSION.capturadoEm}`);
+  }
+  return EXIT.OK;
+}
+function runBancosLookup(value, options, io = { stdout: [], stderr: [] }) {
+  if (!value?.trim()) {
+    io.stderr.push("Missing bank code or ISPB. Pass COMPE (001) or ISPB (8 digits).");
+    return EXIT.USAGE;
+  }
+  return runBancosLookupCommand(value.trim(), options, io);
+}
+
+// src/commands/bancos/list.ts
+function sliceBancos(limit) {
+  const all = getBancos();
+  if (limit === void 0 || !Number.isFinite(limit) || limit <= 0) {
+    return all;
+  }
+  return all.slice(0, limit);
+}
+function runBancosListCommand(options, io = { stdout: [], stderr: [] }) {
+  const bancos = sliceBancos(options.limit);
+  if (options.json) {
+    const payload = {
+      ok: true,
+      total: bancos.length,
+      bancos
+    };
+    if (options.verbose) {
+      payload.capturadoEm = BANCOS_DATA_VERSION2.capturadoEm;
+    }
+    io.stdout.push(JSON.stringify(payload, null, 2));
+    return EXIT.OK;
+  }
+  for (const banco of bancos) {
+    io.stdout.push(formatBancoHuman(banco));
+  }
+  if (options.verbose) {
+    io.stdout.push(`capturadoEm: ${BANCOS_DATA_VERSION2.capturadoEm}`);
+  }
+  return EXIT.OK;
+}
+function runBancosList(options, io = { stdout: [], stderr: [] }) {
+  return runBancosListCommand(options, io);
+}
+
+// src/commands/reference-lookup/registry.ts
+import {
+  CEST_DATA_VERSION,
+  getCestPorCodigo
+} from "@br-validators/core/cest";
+import {
+  INCOTERMS_DATA_VERSION,
+  getIncotermPorCodigo
+} from "@br-validators/core/incoterms";
+import {
+  MOEDAS_DATA_VERSION,
+  getMoedaPorCodigo
+} from "@br-validators/core/moedas";
+import {
+  NATUREZA_JURIDICA_DATA_VERSION,
+  getNaturezaJuridicaPorCodigo
+} from "@br-validators/core/natureza-juridica";
+import { NBS_DATA_VERSION, getNbsPorCodigo } from "@br-validators/core/nbs";
+import {
+  PAISES_BACEN_DATA_VERSION,
+  getPaisPorCodigoBacen
+} from "@br-validators/core/paises-bacen";
+import {
+  AEROPORTOS_DATA_VERSION,
+  getAeroportoPorIata,
+  getAeroportoPorIcao
+} from "@br-validators/core/aeroportos";
+import { PORTOS_DATA_VERSION, getPortoPorCodigo } from "@br-validators/core/portos";
+var REFERENCE_LOOKUP_COMMANDS = [
+  "natureza-juridica",
+  "nbs",
+  "cest",
+  "moedas",
+  "paises-bacen",
+  "incoterms",
+  "portos",
+  "aeroportos"
+];
+function lookupAeroporto(input) {
+  const normalized = input.trim().toUpperCase();
+  if (/^[A-Z0-9]{3}$/.test(normalized)) {
+    return getAeroportoPorIata(normalized);
+  }
+  if (/^[A-Z]{4}$/.test(normalized)) {
+    return getAeroportoPorIcao(normalized);
+  }
+  return void 0;
+}
+var REFERENCE_LOOKUP_MODULES = {
+  "natureza-juridica": {
+    command: "natureza-juridica",
+    description: "RFB legal nature codes \u2014 offline lookup",
+    resultKey: "naturezaJuridica",
+    capturadoEm: NATUREZA_JURIDICA_DATA_VERSION.capturadoEm,
+    lookup: (input) => getNaturezaJuridicaPorCodigo(input),
+    formatHuman: (result) => {
+      const row = result;
+      return `${row.codigo} \u2014 ${row.descricao}`;
+    }
+  },
+  nbs: {
+    command: "nbs",
+    description: "NFSe NBS service codes \u2014 offline lookup",
+    resultKey: "nbs",
+    capturadoEm: NBS_DATA_VERSION.capturadoEm,
+    lookup: (input) => getNbsPorCodigo(input),
+    formatHuman: (result) => {
+      const row = result;
+      return `${row.codigo} \u2014 ${row.descricao}`;
+    }
+  },
+  cest: {
+    command: "cest",
+    description: "CONFAZ CEST ST codes \u2014 offline lookup",
+    resultKey: "cest",
+    capturadoEm: CEST_DATA_VERSION.capturadoEm,
+    lookup: (input) => getCestPorCodigo(input),
+    formatHuman: (result) => {
+      const row = result;
+      return `${row.codigo} \u2014 ${row.descricao}`;
+    }
+  },
+  moedas: {
+    command: "moedas",
+    description: "ISO 4217 + Bacen PTAX currencies \u2014 offline lookup",
+    resultKey: "moeda",
+    capturadoEm: MOEDAS_DATA_VERSION.capturadoEm,
+    lookup: (input) => getMoedaPorCodigo(input),
+    formatHuman: (result) => {
+      const row = result;
+      const symbol = row.simbolo ?? "\u2014";
+      return `${row.codigo} \u2014 ${row.nome} (${symbol})`;
+    }
+  },
+  "paises-bacen": {
+    command: "paises-bacen",
+    description: "NF-e Bacen country codes \u2014 offline lookup",
+    resultKey: "pais",
+    capturadoEm: PAISES_BACEN_DATA_VERSION.capturadoEm,
+    lookup: (input) => getPaisPorCodigoBacen(input),
+    formatHuman: (result) => {
+      const row = result;
+      return `${row.codigo} \u2014 ${row.nome}`;
+    }
+  },
+  incoterms: {
+    command: "incoterms",
+    description: "ICC Incoterms 2020 \u2014 offline lookup",
+    resultKey: "incoterm",
+    capturadoEm: INCOTERMS_DATA_VERSION.capturadoEm,
+    lookup: (input) => getIncotermPorCodigo(input),
+    formatHuman: (result) => {
+      const row = result;
+      return `${row.codigo} \u2014 ${row.nome} (${row.edicao})`;
+    }
+  },
+  portos: {
+    command: "portos",
+    description: "ANTAQ port installations \u2014 offline lookup",
+    resultKey: "porto",
+    capturadoEm: PORTOS_DATA_VERSION.capturadoEm,
+    lookup: (input) => getPortoPorCodigo(input),
+    formatHuman: (result) => {
+      const row = result;
+      return `${row.codigo} \u2014 ${row.nome} (${row.uf})`;
+    }
+  },
+  aeroportos: {
+    command: "aeroportos",
+    description: "ANAC public aerodromos \u2014 offline lookup by IATA or ICAO",
+    resultKey: "aeroporto",
+    capturadoEm: AEROPORTOS_DATA_VERSION.capturadoEm,
+    lookup: lookupAeroporto,
+    formatHuman: (result) => {
+      const row = result;
+      const iata = row.iata ?? "\u2014";
+      return `${iata}/${row.icao} \u2014 ${row.nome} (${row.uf})`;
+    }
+  }
+};
+function isReferenceLookupCommand(value) {
+  return REFERENCE_LOOKUP_COMMANDS.includes(value);
+}
+
+// src/commands/reference-lookup/lookup.ts
+function runReferenceLookupCommand(command, input, options, io = { stdout: [], stderr: [] }) {
+  const module = REFERENCE_LOOKUP_MODULES[command];
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    io.stderr.push(`Missing code. Pass a lookup value for ${command}.`);
+    return EXIT.USAGE;
+  }
+  const result = module.lookup(trimmed);
+  if (!result) {
+    io.stderr.push(`Not found: ${trimmed}`);
+    return EXIT.INVALID;
+  }
+  if (options.json) {
+    const payload = {
+      ok: true,
+      [module.resultKey]: result,
+      ...options.verbose ? { capturadoEm: module.capturadoEm } : {}
+    };
+    io.stdout.push(JSON.stringify(payload, null, 2));
+    return EXIT.OK;
+  }
+  io.stdout.push(module.formatHuman(result));
+  if (options.verbose) {
+    io.stdout.push(`capturadoEm: ${module.capturadoEm}`);
+  }
+  return EXIT.OK;
+}
+function runReferenceLookup(command, value, options, io = { stdout: [], stderr: [] }) {
+  if (!isReferenceLookupCommand(command)) {
+    io.stderr.push(`Unknown reference lookup command: ${command}`);
+    return EXIT.USAGE;
+  }
+  if (!value?.trim()) {
+    io.stderr.push(`Missing code. Usage: br-validators ${command} lookup <codigo>`);
+    return EXIT.USAGE;
+  }
+  return runReferenceLookupCommand(command, value.trim(), options, io);
+}
+
 // src/commands/brcode.ts
+import {
+  BRCODE_OFFICIAL_SOURCE_URL,
+  parseBrCode,
+  validateBrCode
+} from "@br-validators/core";
 function resolveInput(value, fileContent) {
   const input = value ?? fileContent?.trim();
   if (!input) {
@@ -1670,11 +1948,55 @@ function handleGenerateCli(type, opts, io = { stdout: [], stderr: [] }) {
     io
   );
 }
+function handleBancosLookupCli(value, opts, io = { stdout: [], stderr: [] }) {
+  return runBancosLookup(
+    value,
+    {
+      json: Boolean(opts.json),
+      verbose: Boolean(opts.verbose)
+    },
+    io
+  );
+}
+function handleBancosListCli(opts, io = { stdout: [], stderr: [] }) {
+  return runBancosList(
+    {
+      json: Boolean(opts.json),
+      verbose: Boolean(opts.verbose),
+      limit: opts.limit
+    },
+    io
+  );
+}
+function handleReferenceLookupCli(command, value, opts, io = { stdout: [], stderr: [] }) {
+  return runReferenceLookup(
+    command,
+    value,
+    {
+      json: Boolean(opts.json),
+      verbose: Boolean(opts.verbose)
+    },
+    io
+  );
+}
 function writeCliIo(io) {
   for (const line of io.stdout) console.log(line);
   for (const line of io.stderr) console.error(line);
 }
 
+// src/commands/reference-lookup/register-program.ts
+function registerReferenceLookupCommands(program) {
+  for (const command of REFERENCE_LOOKUP_COMMANDS) {
+    const module = REFERENCE_LOOKUP_MODULES[command];
+    const root = program.command(command).description(module.description);
+    root.command("lookup").description(`Resolve ${command} by official code`).argument("<codigo>", "Lookup code").option("--json", "JSON output").option("--verbose", "Include dataset capture date").action((codigo, opts) => {
+      const io = { stdout: [], stderr: [] };
+      process.exitCode = handleReferenceLookupCli(command, codigo, opts, io);
+      writeCliIo(io);
+    });
+  }
+}
+
 // src/program.ts
 function createProgram() {
   const program = new Command();
@@ -1843,6 +2165,18 @@ function createProgram() {
       writeCliIo(io);
     });
   }
+  const bancos = program.command("bancos").description("Bacen STR participants \u2014 offline lookup");
+  bancos.command("lookup").description("Resolve bank by COMPE (3 digits) or ISPB (8 digits)").argument("<codigoOuIspb>", "COMPE or ISPB").option("--json", "JSON output").option("--verbose", "Include dataset capture date (BANCOS_DATA_VERSION)").action((codigoOuIspb, opts) => {
+    const io = { stdout: [], stderr: [] };
+    process.exitCode = handleBancosLookupCli(codigoOuIspb, opts, io);
+    writeCliIo(io);
+  });
+  bancos.command("list").description("List STR participants (optional --limit)").option("--json", "JSON output").option("--verbose", "Include dataset capture date (BANCOS_DATA_VERSION)").option("--limit <n>", "Maximum rows to print", (v) => Number(v)).action((opts) => {
+    const io = { stdout: [], stderr: [] };
+    process.exitCode = handleBancosListCli(opts, io);
+    writeCliIo(io);
+  });
+  registerReferenceLookupCommands(program);
   program.command("detect").description("Detect document type from raw input").argument("[value]", "Raw value to classify").option("--uf <uf>", "State code for Inscri\xE7\xE3o Estadual detection").option("--json", "JSON output").option("-q, --quiet", "Exit code only").option("-f, --file <path>", "Read value from file").action((value, opts) => {
     const io = { stdout: [], stderr: [] };
     process.exitCode = handleDetectCli(value, opts, io);

package/dist/run-captured.js

@@ -13,6 +13,286 @@ var EXIT = {
   USAGE: 2
 };
 
+// src/commands/reference-lookup/registry.ts
+import {
+  CEST_DATA_VERSION,
+  getCestPorCodigo
+} from "@br-validators/core/cest";
+import {
+  INCOTERMS_DATA_VERSION,
+  getIncotermPorCodigo
+} from "@br-validators/core/incoterms";
+import {
+  MOEDAS_DATA_VERSION,
+  getMoedaPorCodigo
+} from "@br-validators/core/moedas";
+import {
+  NATUREZA_JURIDICA_DATA_VERSION,
+  getNaturezaJuridicaPorCodigo
+} from "@br-validators/core/natureza-juridica";
+import { NBS_DATA_VERSION, getNbsPorCodigo } from "@br-validators/core/nbs";
+import {
+  PAISES_BACEN_DATA_VERSION,
+  getPaisPorCodigoBacen
+} from "@br-validators/core/paises-bacen";
+import {
+  AEROPORTOS_DATA_VERSION,
+  getAeroportoPorIata,
+  getAeroportoPorIcao
+} from "@br-validators/core/aeroportos";
+import { PORTOS_DATA_VERSION, getPortoPorCodigo } from "@br-validators/core/portos";
+var REFERENCE_LOOKUP_COMMANDS = [
+  "natureza-juridica",
+  "nbs",
+  "cest",
+  "moedas",
+  "paises-bacen",
+  "incoterms",
+  "portos",
+  "aeroportos"
+];
+function lookupAeroporto(input) {
+  const normalized = input.trim().toUpperCase();
+  if (/^[A-Z0-9]{3}$/.test(normalized)) {
+    return getAeroportoPorIata(normalized);
+  }
+  if (/^[A-Z]{4}$/.test(normalized)) {
+    return getAeroportoPorIcao(normalized);
+  }
+  return void 0;
+}
+var REFERENCE_LOOKUP_MODULES = {
+  "natureza-juridica": {
+    command: "natureza-juridica",
+    description: "RFB legal nature codes \u2014 offline lookup",
+    resultKey: "naturezaJuridica",
+    capturadoEm: NATUREZA_JURIDICA_DATA_VERSION.capturadoEm,
+    lookup: (input) => getNaturezaJuridicaPorCodigo(input),
+    formatHuman: (result) => {
+      const row = result;
+      return `${row.codigo} \u2014 ${row.descricao}`;
+    }
+  },
+  nbs: {
+    command: "nbs",
+    description: "NFSe NBS service codes \u2014 offline lookup",
+    resultKey: "nbs",
+    capturadoEm: NBS_DATA_VERSION.capturadoEm,
+    lookup: (input) => getNbsPorCodigo(input),
+    formatHuman: (result) => {
+      const row = result;
+      return `${row.codigo} \u2014 ${row.descricao}`;
+    }
+  },
+  cest: {
+    command: "cest",
+    description: "CONFAZ CEST ST codes \u2014 offline lookup",
+    resultKey: "cest",
+    capturadoEm: CEST_DATA_VERSION.capturadoEm,
+    lookup: (input) => getCestPorCodigo(input),
+    formatHuman: (result) => {
+      const row = result;
+      return `${row.codigo} \u2014 ${row.descricao}`;
+    }
+  },
+  moedas: {
+    command: "moedas",
+    description: "ISO 4217 + Bacen PTAX currencies \u2014 offline lookup",
+    resultKey: "moeda",
+    capturadoEm: MOEDAS_DATA_VERSION.capturadoEm,
+    lookup: (input) => getMoedaPorCodigo(input),
+    formatHuman: (result) => {
+      const row = result;
+      const symbol = row.simbolo ?? "\u2014";
+      return `${row.codigo} \u2014 ${row.nome} (${symbol})`;
+    }
+  },
+  "paises-bacen": {
+    command: "paises-bacen",
+    description: "NF-e Bacen country codes \u2014 offline lookup",
+    resultKey: "pais",
+    capturadoEm: PAISES_BACEN_DATA_VERSION.capturadoEm,
+    lookup: (input) => getPaisPorCodigoBacen(input),
+    formatHuman: (result) => {
+      const row = result;
+      return `${row.codigo} \u2014 ${row.nome}`;
+    }
+  },
+  incoterms: {
+    command: "incoterms",
+    description: "ICC Incoterms 2020 \u2014 offline lookup",
+    resultKey: "incoterm",
+    capturadoEm: INCOTERMS_DATA_VERSION.capturadoEm,
+    lookup: (input) => getIncotermPorCodigo(input),
+    formatHuman: (result) => {
+      const row = result;
+      return `${row.codigo} \u2014 ${row.nome} (${row.edicao})`;
+    }
+  },
+  portos: {
+    command: "portos",
+    description: "ANTAQ port installations \u2014 offline lookup",
+    resultKey: "porto",
+    capturadoEm: PORTOS_DATA_VERSION.capturadoEm,
+    lookup: (input) => getPortoPorCodigo(input),
+    formatHuman: (result) => {
+      const row = result;
+      return `${row.codigo} \u2014 ${row.nome} (${row.uf})`;
+    }
+  },
+  aeroportos: {
+    command: "aeroportos",
+    description: "ANAC public aerodromos \u2014 offline lookup by IATA or ICAO",
+    resultKey: "aeroporto",
+    capturadoEm: AEROPORTOS_DATA_VERSION.capturadoEm,
+    lookup: lookupAeroporto,
+    formatHuman: (result) => {
+      const row = result;
+      const iata = row.iata ?? "\u2014";
+      return `${iata}/${row.icao} \u2014 ${row.nome} (${row.uf})`;
+    }
+  }
+};
+function isReferenceLookupCommand(value) {
+  return REFERENCE_LOOKUP_COMMANDS.includes(value);
+}
+
+// src/commands/bancos/list.ts
+import { BANCOS_DATA_VERSION as BANCOS_DATA_VERSION2, getBancos } from "@br-validators/core/bancos";
+
+// src/commands/bancos/lookup.ts
+import {
+  BANCOS_DATA_VERSION,
+  getBancoPorCodigo,
+  getBancoPorIspb
+} from "@br-validators/core/bancos";
+function normalizeBancosLookupInput(raw) {
+  const digits = raw.replace(/\D/g, "");
+  if (digits.length === 8) {
+    return { kind: "ispb", value: digits.padStart(8, "0") };
+  }
+  if (digits.length >= 1 && digits.length <= 3) {
+    return { kind: "codigo", value: digits.padStart(3, "0").slice(-3) };
+  }
+  return null;
+}
+function lookupBanco(raw) {
+  const normalized = normalizeBancosLookupInput(raw);
+  if (!normalized) {
+    return void 0;
+  }
+  return normalized.kind === "ispb" ? getBancoPorIspb(normalized.value) : getBancoPorCodigo(normalized.value);
+}
+function formatBancoHuman(banco) {
+  return `${banco.codigo} \u2014 ${banco.nome} (ISPB ${banco.ispb})`;
+}
+function runBancosLookupCommand(input, options, io = { stdout: [], stderr: [] }) {
+  const normalized = normalizeBancosLookupInput(input);
+  if (!normalized) {
+    io.stderr.push("Invalid bank code or ISPB. Use 3-digit COMPE (e.g. 001) or 8-digit ISPB.");
+    return EXIT.USAGE;
+  }
+  const banco = lookupBanco(input);
+  if (!banco) {
+    io.stderr.push(`Bank not found: ${input}`);
+    return EXIT.INVALID;
+  }
+  if (options.json) {
+    const payload = { ok: true, banco };
+    if (options.verbose) {
+      payload.capturadoEm = BANCOS_DATA_VERSION.capturadoEm;
+    }
+    io.stdout.push(JSON.stringify(payload, null, 2));
+    return EXIT.OK;
+  }
+  io.stdout.push(formatBancoHuman(banco));
+  if (options.verbose) {
+    io.stdout.push(`capturadoEm: ${BANCOS_DATA_VERSION.capturadoEm}`);
+  }
+  return EXIT.OK;
+}
+function runBancosLookup(value, options, io = { stdout: [], stderr: [] }) {
+  if (!value?.trim()) {
+    io.stderr.push("Missing bank code or ISPB. Pass COMPE (001) or ISPB (8 digits).");
+    return EXIT.USAGE;
+  }
+  return runBancosLookupCommand(value.trim(), options, io);
+}
+
+// src/commands/bancos/list.ts
+function sliceBancos(limit) {
+  const all = getBancos();
+  if (limit === void 0 || !Number.isFinite(limit) || limit <= 0) {
+    return all;
+  }
+  return all.slice(0, limit);
+}
+function runBancosListCommand(options, io = { stdout: [], stderr: [] }) {
+  const bancos = sliceBancos(options.limit);
+  if (options.json) {
+    const payload = {
+      ok: true,
+      total: bancos.length,
+      bancos
+    };
+    if (options.verbose) {
+      payload.capturadoEm = BANCOS_DATA_VERSION2.capturadoEm;
+    }
+    io.stdout.push(JSON.stringify(payload, null, 2));
+    return EXIT.OK;
+  }
+  for (const banco of bancos) {
+    io.stdout.push(formatBancoHuman(banco));
+  }
+  if (options.verbose) {
+    io.stdout.push(`capturadoEm: ${BANCOS_DATA_VERSION2.capturadoEm}`);
+  }
+  return EXIT.OK;
+}
+function runBancosList(options, io = { stdout: [], stderr: [] }) {
+  return runBancosListCommand(options, io);
+}
+
+// src/commands/reference-lookup/lookup.ts
+function runReferenceLookupCommand(command, input, options, io = { stdout: [], stderr: [] }) {
+  const module = REFERENCE_LOOKUP_MODULES[command];
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    io.stderr.push(`Missing code. Pass a lookup value for ${command}.`);
+    return EXIT.USAGE;
+  }
+  const result = module.lookup(trimmed);
+  if (!result) {
+    io.stderr.push(`Not found: ${trimmed}`);
+    return EXIT.INVALID;
+  }
+  if (options.json) {
+    const payload = {
+      ok: true,
+      [module.resultKey]: result,
+      ...options.verbose ? { capturadoEm: module.capturadoEm } : {}
+    };
+    io.stdout.push(JSON.stringify(payload, null, 2));
+    return EXIT.OK;
+  }
+  io.stdout.push(module.formatHuman(result));
+  if (options.verbose) {
+    io.stdout.push(`capturadoEm: ${module.capturadoEm}`);
+  }
+  return EXIT.OK;
+}
+function runReferenceLookup(command, value, options, io = { stdout: [], stderr: [] }) {
+  if (!isReferenceLookupCommand(command)) {
+    io.stderr.push(`Unknown reference lookup command: ${command}`);
+    return EXIT.USAGE;
+  }
+  if (!value?.trim()) {
+    io.stderr.push(`Missing code. Usage: br-validators ${command} lookup <codigo>`);
+    return EXIT.USAGE;
+  }
+  return runReferenceLookupCommand(command, value.trim(), options, io);
+}
+
 // src/commands/brcode.ts
 import {
   BRCODE_OFFICIAL_SOURCE_URL,
@@ -1664,6 +1944,37 @@ function handleGenerateCli(type, opts, io = { stdout: [], stderr: [] }) {
     io
   );
 }
+function handleBancosLookupCli(value, opts, io = { stdout: [], stderr: [] }) {
+  return runBancosLookup(
+    value,
+    {
+      json: Boolean(opts.json),
+      verbose: Boolean(opts.verbose)
+    },
+    io
+  );
+}
+function handleBancosListCli(opts, io = { stdout: [], stderr: [] }) {
+  return runBancosList(
+    {
+      json: Boolean(opts.json),
+      verbose: Boolean(opts.verbose),
+      limit: opts.limit
+    },
+    io
+  );
+}
+function handleReferenceLookupCli(command, value, opts, io = { stdout: [], stderr: [] }) {
+  return runReferenceLookup(
+    command,
+    value,
+    {
+      json: Boolean(opts.json),
+      verbose: Boolean(opts.verbose)
+    },
+    io
+  );
+}
 
 // src/argv-dispatch.ts
 var STANDARD_ACTIONS = ["validate", "format", "strip"];
@@ -1727,6 +2038,15 @@ function parseArgv(tokens) {
       index += 1;
       continue;
     }
+    if (token === "--verbose") {
+      opts.verbose = true;
+      continue;
+    }
+    if (token === "--limit") {
+      opts.limit = Number(tokens[index + 1]);
+      index += 1;
+      continue;
+    }
     if (token.startsWith("-")) {
       continue;
     }
@@ -1749,7 +2069,7 @@ function dispatchArgv(tokens, io) {
   if (tokens.length === 0 || tokens.includes("--help") || tokens.includes("-h")) {
     io.stdout.push("br-validators \u2014 100% open-source Brazilian document validators");
     io.stdout.push("Usage: br-validators <command> ...");
-    io.stdout.push("Commands: list \xB7 cpf \xB7 cnpj \xB7 cep \xB7 telefone \xB7 cnh \xB7 renavam \xB7 titulo-eleitor \xB7 nfe-chave \xB7 brcode \xB7 placa \xB7 pis-pasep \xB7 pix \xB7 boleto \xB7 cartao \xB7 cartao-credito \xB7 ie \xB7 detect \xB7 sanitize \xB7 generate");
+    io.stdout.push("Commands: list \xB7 cpf \xB7 cnpj \xB7 cep \xB7 telefone \xB7 cnh \xB7 renavam \xB7 titulo-eleitor \xB7 nfe-chave \xB7 brcode \xB7 placa \xB7 pis-pasep \xB7 pix \xB7 boleto \xB7 cartao \xB7 cartao-credito \xB7 ie \xB7 bancos \xB7 natureza-juridica \xB7 nbs \xB7 cest \xB7 moedas \xB7 paises-bacen \xB7 incoterms \xB7 portos \xB7 aeroportos \xB7 detect \xB7 sanitize \xB7 generate");
     return EXIT.OK;
   }
   if (tokens.includes("--version") || tokens.includes("-V")) {
@@ -1851,14 +2171,34 @@ function dispatchArgv(tokens, io) {
         io,
         (action, value, ieOpts, ioArg) => handleIeCli(action, value, ieOpts, ioArg)
       );
+    case "bancos": {
+      const action = rest[0];
+      if (action === "lookup") {
+        const value = rest.slice(1).join(" ") || void 0;
+        return handleBancosLookupCli(value, opts, io);
+      }
+      if (action === "list") {
+        return handleBancosListCli(opts, io);
+      }
+      return usage(io, "Expected: bancos lookup <codigo|ispb> | bancos list [--limit n]");
+    }
     case "detect":
       return handleDetectCli(rest.join(" ") || void 0, opts, io);
     case "sanitize":
       return handleSanitizeCli(rest[0] ?? "", rest.slice(1).join(" ") || void 0, opts, io);
     case "generate":
       return handleGenerateCli(rest[0] ?? "", opts, io);
-    default:
+    default: {
+      if (isReferenceLookupCommand(root)) {
+        const action = rest[0];
+        if (action === "lookup") {
+          const value = rest.slice(1).join(" ") || void 0;
+          return handleReferenceLookupCli(root, value, opts, io);
+        }
+        return usage(io, `Expected: ${root} lookup <codigo>`);
+      }
       return usage(io, `Unknown command: ${root}`);
+    }
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@br-validators/cli",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "CLI for @br-validators/core — CPF, CNPJ, NF-e, IE, PIX, boleto + detect/sanitize/generate",
   "license": "MIT",
   "type": "module",
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "commander": "^13.1.0",
-    "@br-validators/core": "1.3.0"
+    "@br-validators/core": "1.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.21",