@br-validators/cli 0.10.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BR Validators contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @br-validators/cli
+
+Terminal CLI for all Brazilian document validators in [@br-validators/core](https://www.npmjs.com/package/@br-validators/core).
+
+---
+
+## Install
+
+```bash
+npm install -g @br-validators/cli
+```
+
+Or run without install:
+
+```bash
+npx @br-validators/cli --help
+```
+
+---
+
+## Commands
+
+```bash
+br-validators list
+br-validators --version
+
+br-validators cnpj validate 12ABC34501DE35 --json --source
+br-validators cpf validate 12345678909
+br-validators cep format 01310100
+br-validators placa validate ABC1D23
+br-validators pis-pasep validate 10027230888
+br-validators pix validate pix@bcb.gov.br
+br-validators boleto validate <linha-ou-barcode>
+br-validators cartao validate 4111111111111111
+br-validators ie validate 110042490114 --uf SP --json
+```
+
+### Actions (all types)
+
+| Action | Description |
+|--------|-------------|
+| `validate` | Check format + check digits |
+| `format` | Apply official mask |
+| `strip` | Normalize to canonical digits/chars |
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--json` | JSON output (`ValidationResult`) |
+| `--quiet` / `-q` | Exit code only (CI) |
+| `--file` / `-f` | Read value from file |
+| `--source` | Print official source URL |
+| `--uf` | Required for IE (27 UFs) |
+
+### CI
+
+```bash
+br-validators cnpj validate "$CNPJ" --quiet || exit 1
+```
+
+---
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,1064 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+
+// src/program.ts
+import { Command } from "commander";
+
+// src/handlers.ts
+import { readFileSync } from "fs";
+
+// src/commands/cep.ts
+import {
+  CEP_OFFICIAL_SOURCE_URL,
+  formatCep,
+  stripCep,
+  validateCep
+} from "@br-validators/core";
+
+// src/constants.ts
+var SUPPORTED_TYPES = ["cnpj", "cpf", "cep", "placa", "pis-pasep", "pix", "boleto", "cartao", "ie"];
+var EXIT = {
+  OK: 0,
+  INVALID: 1,
+  USAGE: 2
+};
+
+// src/output.ts
+function printValidation(result, options, io = { stdout: [], stderr: [] }) {
+  if (options.json) {
+    io.stdout.push(
+      JSON.stringify(
+        result.ok ? {
+          ok: true,
+          value: result.value,
+          format: result.format,
+          ...options.source ? { source: options.source } : {}
+        } : { ok: false, code: result.code, message: result.message },
+        null,
+        2
+      )
+    );
+    return result.ok ? EXIT.OK : EXIT.INVALID;
+  }
+  if (options.quiet) {
+    return result.ok ? EXIT.OK : EXIT.INVALID;
+  }
+  if (result.ok) {
+    io.stdout.push(`valid: yes (${result.format})`);
+    io.stdout.push(`value: ${result.value}`);
+    if (options.source) {
+      io.stdout.push(`source: ${options.source}`);
+    }
+    return EXIT.OK;
+  }
+  io.stderr.push("valid: no");
+  io.stderr.push(`code: ${result.code}`);
+  io.stderr.push(`message: ${result.message}`);
+  return EXIT.INVALID;
+}
+function printFormat(result, options, io = { stdout: [], stderr: [] }) {
+  if (options.json) {
+    io.stdout.push(JSON.stringify(result, null, 2));
+    return result.ok ? EXIT.OK : EXIT.INVALID;
+  }
+  if (options.quiet) {
+    return result.ok ? EXIT.OK : EXIT.INVALID;
+  }
+  if (result.ok) {
+    io.stdout.push(result.formatted);
+    return EXIT.OK;
+  }
+  io.stderr.push(`code: ${result.code}`);
+  io.stderr.push(`message: ${result.message}`);
+  return EXIT.INVALID;
+}
+function printStrip(value, options, io = { stdout: [] }) {
+  if (options.json) {
+    io.stdout.push(JSON.stringify({ stripped: value }, null, 2));
+  } else {
+    io.stdout.push(value);
+  }
+  return EXIT.OK;
+}
+
+// src/commands/cep.ts
+function resolveInput(value, fileContent) {
+  const input = value ?? fileContent?.trim();
+  if (!input) {
+    return null;
+  }
+  return input;
+}
+function runCepCommand(action, input, options, io = { stdout: [], stderr: [] }) {
+  const source = options.source ? CEP_OFFICIAL_SOURCE_URL : void 0;
+  switch (action) {
+    case "validate":
+      return printValidation(validateCep(input), { json: options.json, quiet: options.quiet, source }, io);
+    case "format":
+      return printFormat(formatCep(input), { json: options.json, quiet: options.quiet }, io);
+    case "strip":
+      return printStrip(stripCep(input), { json: options.json }, io);
+    default: {
+      const _exhaustive = action;
+      io.stderr.push(`Unknown action: ${_exhaustive}`);
+      return EXIT.USAGE;
+    }
+  }
+}
+function runCep(action, value, options, io = { stdout: [], stderr: [] }) {
+  const input = resolveInput(value, options.file);
+  if (input === null) {
+    io.stderr.push("Missing CEP value. Pass an argument or use --file.");
+    return EXIT.USAGE;
+  }
+  return runCepCommand(action, input, options, io);
+}
+
+// src/commands/cnpj.ts
+import {
+  CNPJ_OFFICIAL_SOURCE_URL,
+  formatCnpj,
+  stripCnpj,
+  validateCnpj
+} from "@br-validators/core";
+function resolveInput2(value, fileContent) {
+  const input = value ?? fileContent?.trim();
+  if (!input) {
+    return null;
+  }
+  return input;
+}
+function runCnpjCommand(action, input, options, io = { stdout: [], stderr: [] }) {
+  const source = options.source ? CNPJ_OFFICIAL_SOURCE_URL : void 0;
+  switch (action) {
+    case "validate":
+      return printValidation(validateCnpj(input), { json: options.json, quiet: options.quiet, source }, io);
+    case "format":
+      return printFormat(formatCnpj(input), { json: options.json, quiet: options.quiet }, io);
+    case "strip":
+      return printStrip(stripCnpj(input), { json: options.json }, io);
+    default: {
+      const _exhaustive = action;
+      io.stderr.push(`Unknown action: ${_exhaustive}`);
+      return EXIT.USAGE;
+    }
+  }
+}
+function runCnpj(action, value, options, io = { stdout: [], stderr: [] }) {
+  const input = resolveInput2(value, options.file);
+  if (input === null) {
+    io.stderr.push("Missing CNPJ value. Pass an argument or use --file.");
+    return EXIT.USAGE;
+  }
+  return runCnpjCommand(action, input, options, io);
+}
+
+// src/commands/cpf.ts
+import {
+  CPF_OFFICIAL_SOURCE_URL,
+  formatCpf,
+  stripCpf,
+  validateCpf
+} from "@br-validators/core";
+function resolveInput3(value, fileContent) {
+  const input = value ?? fileContent?.trim();
+  if (!input) {
+    return null;
+  }
+  return input;
+}
+function runCpfCommand(action, input, options, io = { stdout: [], stderr: [] }) {
+  const source = options.source ? CPF_OFFICIAL_SOURCE_URL : void 0;
+  switch (action) {
+    case "validate":
+      return printValidation(validateCpf(input), { json: options.json, quiet: options.quiet, source }, io);
+    case "format":
+      return printFormat(formatCpf(input), { json: options.json, quiet: options.quiet }, io);
+    case "strip":
+      return printStrip(stripCpf(input), { json: options.json }, io);
+    default: {
+      const _exhaustive = action;
+      io.stderr.push(`Unknown action: ${_exhaustive}`);
+      return EXIT.USAGE;
+    }
+  }
+}
+function runCpf(action, value, options, io = { stdout: [], stderr: [] }) {
+  const input = resolveInput3(value, options.file);
+  if (input === null) {
+    io.stderr.push("Missing CPF value. Pass an argument or use --file.");
+    return EXIT.USAGE;
+  }
+  return runCpfCommand(action, input, options, io);
+}
+
+// src/commands/placa.ts
+import {
+  PLACA_OFFICIAL_SOURCE_URL,
+  convertPlacaToMercosul,
+  formatPlaca,
+  stripPlaca,
+  validatePlaca
+} from "@br-validators/core";
+function resolveInput4(value, fileContent) {
+  const input = value ?? fileContent?.trim();
+  if (!input) {
+    return null;
+  }
+  return input;
+}
+function runPlacaCommand(action, input, options, io = { stdout: [], stderr: [] }) {
+  const source = options.source ? PLACA_OFFICIAL_SOURCE_URL : void 0;
+  switch (action) {
+    case "validate":
+      return printValidation(validatePlaca(input), { json: options.json, quiet: options.quiet, source }, io);
+    case "format":
+      return printFormat(formatPlaca(input), { json: options.json, quiet: options.quiet }, io);
+    case "convert":
+      return printFormat(convertPlacaToMercosul(input), { json: options.json, quiet: options.quiet }, io);
+    case "strip":
+      return printStrip(stripPlaca(input), { json: options.json }, io);
+    default: {
+      const _exhaustive = action;
+      io.stderr.push(`Unknown action: ${_exhaustive}`);
+      return EXIT.USAGE;
+    }
+  }
+}
+function runPlaca(action, value, options, io = { stdout: [], stderr: [] }) {
+  const input = resolveInput4(value, options.file);
+  if (input === null) {
+    io.stderr.push("Missing placa value. Pass an argument or use --file.");
+    return EXIT.USAGE;
+  }
+  return runPlacaCommand(action, input, options, io);
+}
+
+// src/commands/pis-pasep.ts
+import {
+  PIS_PASEP_OFFICIAL_SOURCE_URL,
+  formatPisPasep,
+  stripPisPasep,
+  validatePisPasep
+} from "@br-validators/core";
+function resolveInput5(value, fileContent) {
+  const input = value ?? fileContent?.trim();
+  if (!input) {
+    return null;
+  }
+  return input;
+}
+function runPisPasepCommand(action, input, options, io = { stdout: [], stderr: [] }) {
+  const source = options.source ? PIS_PASEP_OFFICIAL_SOURCE_URL : void 0;
+  switch (action) {
+    case "validate":
+      return printValidation(validatePisPasep(input), { json: options.json, quiet: options.quiet, source }, io);
+    case "format":
+      return printFormat(formatPisPasep(input), { json: options.json, quiet: options.quiet }, io);
+    case "strip":
+      return printStrip(stripPisPasep(input), { json: options.json }, io);
+    default: {
+      const _exhaustive = action;
+      io.stderr.push(`Unknown action: ${_exhaustive}`);
+      return EXIT.USAGE;
+    }
+  }
+}
+function runPisPasep(action, value, options, io = { stdout: [], stderr: [] }) {
+  const input = resolveInput5(value, options.file);
+  if (input === null) {
+    io.stderr.push("Missing PIS/PASEP value. Pass an argument or use --file.");
+    return EXIT.USAGE;
+  }
+  return runPisPasepCommand(action, input, options, io);
+}
+
+// src/commands/pix.ts
+import {
+  PIX_OFFICIAL_SOURCE_URL,
+  detectPixKeyType,
+  formatPixKey,
+  validatePixKey
+} from "@br-validators/core";
+function resolveInput6(value, fileContent) {
+  const input = value ?? fileContent?.trim();
+  if (!input) {
+    return null;
+  }
+  return input;
+}
+function printPixValidation(result, options, io = { stdout: [], stderr: [] }) {
+  if (options.json) {
+    io.stdout.push(
+      JSON.stringify(
+        result.ok ? {
+          ok: true,
+          value: result.value,
+          keyType: result.keyType,
+          format: result.format,
+          ...options.source ? { source: options.source } : {}
+        } : {
+          ok: false,
+          code: result.code,
+          message: result.message,
+          ...result.keyType ? { keyType: result.keyType } : {}
+        },
+        null,
+        2
+      )
+    );
+    return result.ok ? EXIT.OK : EXIT.INVALID;
+  }
+  if (options.quiet) {
+    return result.ok ? EXIT.OK : EXIT.INVALID;
+  }
+  if (result.ok) {
+    io.stdout.push(`valid: yes (${result.keyType})`);
+    io.stdout.push(`value: ${result.value}`);
+    io.stdout.push(`format: ${result.format}`);
+    if (options.source) {
+      io.stdout.push(`source: ${options.source}`);
+    }
+    return EXIT.OK;
+  }
+  io.stderr.push("valid: no");
+  io.stderr.push(`code: ${result.code}`);
+  io.stderr.push(`message: ${result.message}`);
+  if (result.keyType) {
+    io.stderr.push(`keyType: ${result.keyType}`);
+  }
+  return EXIT.INVALID;
+}
+function printPixDetect(keyType, options, io = { stdout: [] }) {
+  if (options.json) {
+    io.stdout.push(JSON.stringify({ keyType }, null, 2));
+  } else if (!options.quiet) {
+    io.stdout.push(keyType);
+  }
+  return EXIT.OK;
+}
+function runPixCommand(action, input, options, io = { stdout: [], stderr: [] }) {
+  const source = options.source ? PIX_OFFICIAL_SOURCE_URL : void 0;
+  const validateOptions = options.type ? { type: options.type } : void 0;
+  switch (action) {
+    case "validate":
+      return printPixValidation(validatePixKey(input, validateOptions), { json: options.json, quiet: options.quiet, source }, io);
+    case "format":
+      return printFormat(formatPixKey(input, validateOptions), { json: options.json, quiet: options.quiet }, io);
+    case "detect":
+      return printPixDetect(detectPixKeyType(input), { json: options.json, quiet: options.quiet }, io);
+    default: {
+      const _exhaustive = action;
+      io.stderr.push(`Unknown action: ${_exhaustive}`);
+      return EXIT.USAGE;
+    }
+  }
+}
+function runPix(action, value, options, io = { stdout: [], stderr: [] }) {
+  const input = resolveInput6(value, options.file);
+  if (input === null) {
+    io.stderr.push("Missing PIX key value. Pass an argument or use --file.");
+    return EXIT.USAGE;
+  }
+  return runPixCommand(action, input, options, io);
+}
+
+// src/commands/boleto.ts
+import {
+  BOLETO_OFFICIAL_SOURCE_URL,
+  convertCodigoBarrasToLinhaDigitavel,
+  convertLinhaToCodigoBarras,
+  detectBoletoInputKind,
+  formatBoleto,
+  stripCodigoBarras,
+  stripLinhaDigitavel,
+  validateBoleto
+} from "@br-validators/core";
+function resolveInput7(value, fileContent) {
+  const input = value ?? fileContent?.trim();
+  if (!input) {
+    return null;
+  }
+  return input;
+}
+function printBoletoValidation(result, options, io = { stdout: [], stderr: [] }) {
+  if (options.json) {
+    io.stdout.push(
+      JSON.stringify(
+        result.ok ? {
+          ok: true,
+          value: result.value,
+          inputKind: result.inputKind,
+          format: result.format,
+          situacao: result.situacao,
+          ...options.source ? { source: options.source } : {}
+        } : {
+          ok: false,
+          code: result.code,
+          message: result.message,
+          ...result.inputKind ? { inputKind: result.inputKind } : {}
+        },
+        null,
+        2
+      )
+    );
+    return result.ok ? EXIT.OK : EXIT.INVALID;
+  }
+  if (options.quiet) {
+    return result.ok ? EXIT.OK : EXIT.INVALID;
+  }
+  if (result.ok) {
+    io.stdout.push(`valid: yes (${result.inputKind})`);
+    io.stdout.push(`value: ${result.value}`);
+    io.stdout.push(`format: ${result.format}`);
+    io.stdout.push(`situacao: ${result.situacao}`);
+    if (options.source) {
+      io.stdout.push(`source: ${options.source}`);
+    }
+    return EXIT.OK;
+  }
+  io.stderr.push("valid: no");
+  io.stderr.push(`code: ${result.code}`);
+  io.stderr.push(`message: ${result.message}`);
+  if (result.inputKind) {
+    io.stderr.push(`inputKind: ${result.inputKind}`);
+  }
+  return EXIT.INVALID;
+}
+function printBoletoDetect(inputKind, options, io = { stdout: [] }) {
+  if (options.json) {
+    io.stdout.push(JSON.stringify({ inputKind }, null, 2));
+  } else if (!options.quiet) {
+    io.stdout.push(inputKind);
+  }
+  return EXIT.OK;
+}
+function printBoletoConvert(result, options, io = { stdout: [], stderr: [] }) {
+  if (options.json) {
+    io.stdout.push(
+      JSON.stringify(
+        result.ok ? { ok: true, value: result.value, inputKind: result.inputKind, format: result.format } : { ok: false, code: result.code, message: result.message, ...result.inputKind ? { inputKind: result.inputKind } : {} },
+        null,
+        2
+      )
+    );
+    return result.ok ? EXIT.OK : EXIT.INVALID;
+  }
+  if (options.quiet) {
+    return result.ok ? EXIT.OK : EXIT.INVALID;
+  }
+  if (result.ok) {
+    io.stdout.push(result.value);
+    return EXIT.OK;
+  }
+  io.stderr.push(`code: ${result.code}`);
+  io.stderr.push(`message: ${result.message}`);
+  return EXIT.INVALID;
+}
+function printBoletoFormat(input, options, io = { stdout: [], stderr: [] }) {
+  return printFormat(formatBoleto(input), { json: options.json, quiet: options.quiet }, io);
+}
+function printBoletoStrip(input, options, io = { stdout: [] }) {
+  const kind = detectBoletoInputKind(input);
+  const stripped = kind === "codigo-barras" ? stripCodigoBarras(input) : stripLinhaDigitavel(input);
+  if (options.json) {
+    io.stdout.push(JSON.stringify({ stripped, inputKind: kind }, null, 2));
+  } else if (!options.quiet) {
+    io.stdout.push(stripped);
+  }
+  return EXIT.OK;
+}
+function runBoletoCommand(action, input, options, direction, io = { stdout: [], stderr: [] }) {
+  const source = options.source ? BOLETO_OFFICIAL_SOURCE_URL : void 0;
+  const validateOptions = options.kind ? { kind: options.kind } : void 0;
+  switch (action) {
+    case "validate":
+      return printBoletoValidation(validateBoleto(input, validateOptions), { json: options.json, quiet: options.quiet, source }, io);
+    case "detect":
+      return printBoletoDetect(detectBoletoInputKind(input), { json: options.json, quiet: options.quiet }, io);
+    case "convert": {
+      if (direction === "linha-to-barras") {
+        return printBoletoConvert(convertLinhaToCodigoBarras(input), { json: options.json, quiet: options.quiet }, io);
+      }
+      if (direction === "barras-to-linha") {
+        return printBoletoConvert(convertCodigoBarrasToLinhaDigitavel(input), { json: options.json, quiet: options.quiet }, io);
+      }
+      io.stderr.push("Missing convert direction. Use linha-to-barras or barras-to-linha.");
+      return EXIT.USAGE;
+    }
+    case "format":
+      return printBoletoFormat(input, { json: options.json, quiet: options.quiet }, io);
+    case "strip":
+      return printBoletoStrip(input, { json: options.json, quiet: options.quiet }, io);
+    default: {
+      const _exhaustive = action;
+      io.stderr.push(`Unknown action: ${_exhaustive}`);
+      return EXIT.USAGE;
+    }
+  }
+}
+function runBoleto(action, value, options, direction, io = { stdout: [], stderr: [] }) {
+  const input = resolveInput7(value, options.file);
+  if (input === null) {
+    io.stderr.push("Missing boleto value. Pass an argument or use --file.");
+    return EXIT.USAGE;
+  }
+  return runBoletoCommand(action, input, options, direction, io);
+}
+
+// src/commands/cartao.ts
+import {
+  CARTAO_OFFICIAL_SOURCE_URL,
+  detectCardBrand,
+  formatCartaoCredito,
+  stripCartaoCredito,
+  validateCartaoCredito
+} from "@br-validators/core";
+function resolveInput8(value, fileContent) {
+  const input = value ?? fileContent?.trim();
+  if (!input) {
+    return null;
+  }
+  return input;
+}
+function printCartaoValidation(result, options, io = { stdout: [], stderr: [] }) {
+  if (options.json) {
+    io.stdout.push(
+      JSON.stringify(
+        result.ok ? {
+          ok: true,
+          value: result.value,
+          brand: result.brand,
+          format: result.format,
+          ...options.source ? { source: options.source } : {}
+        } : {
+          ok: false,
+          code: result.code,
+          message: result.message,
+          ...result.brand ? { brand: result.brand } : {}
+        },
+        null,
+        2
+      )
+    );
+    return result.ok ? EXIT.OK : EXIT.INVALID;
+  }
+  if (options.quiet) {
+    return result.ok ? EXIT.OK : EXIT.INVALID;
+  }
+  if (result.ok) {
+    io.stdout.push(`valid: yes (${result.format})`);
+    io.stdout.push(`brand: ${result.brand}`);
+    io.stdout.push(`value: ${result.value}`);
+    if (options.source) {
+      io.stdout.push(`source: ${options.source}`);
+    }
+    return EXIT.OK;
+  }
+  io.stderr.push("valid: no");
+  io.stderr.push(`code: ${result.code}`);
+  io.stderr.push(`message: ${result.message}`);
+  if (result.brand) {
+    io.stderr.push(`brand: ${result.brand}`);
+  }
+  return EXIT.INVALID;
+}
+function printCartaoDetect(brand, options, io = { stdout: [] }) {
+  if (options.json) {
+    io.stdout.push(JSON.stringify({ brand }, null, 2));
+  } else if (!options.quiet) {
+    io.stdout.push(brand);
+  }
+  return EXIT.OK;
+}
+function runCartaoCommand(action, input, options, io = { stdout: [], stderr: [] }) {
+  const source = options.source ? CARTAO_OFFICIAL_SOURCE_URL : void 0;
+  switch (action) {
+    case "validate":
+      return printCartaoValidation(validateCartaoCredito(input), { json: options.json, quiet: options.quiet, source }, io);
+    case "detect":
+      return printCartaoDetect(detectCardBrand(stripCartaoCredito(input)), { json: options.json, quiet: options.quiet }, io);
+    case "format":
+      return printFormat(formatCartaoCredito(input), { json: options.json, quiet: options.quiet }, io);
+    case "strip":
+      return printStrip(stripCartaoCredito(input), { json: options.json }, io);
+    default: {
+      const _exhaustive = action;
+      io.stderr.push(`Unknown action: ${_exhaustive}`);
+      return EXIT.USAGE;
+    }
+  }
+}
+function runCartao(action, value, options, io = { stdout: [], stderr: [] }) {
+  const input = resolveInput8(value, options.file);
+  if (input === null) {
+    io.stderr.push("Missing credit card PAN value. Pass an argument or use --file.");
+    return EXIT.USAGE;
+  }
+  return runCartaoCommand(action, input, options, io);
+}
+
+// src/commands/ie.ts
+import {
+  formatInscricaoEstadual,
+  getIeOfficialSourceUrl,
+  IE_SUPPORTED_UFS,
+  stripInscricaoEstadual,
+  validateInscricaoEstadual
+} from "@br-validators/core";
+function resolveInput9(value, fileContent) {
+  const input = value ?? fileContent?.trim();
+  if (!input) {
+    return null;
+  }
+  return input;
+}
+function resolveUf(uf) {
+  if (uf === void 0) {
+    return null;
+  }
+  const normalized = uf.toUpperCase();
+  if (IE_SUPPORTED_UFS.includes(normalized)) {
+    return normalized;
+  }
+  return null;
+}
+function printIeValidation(result, options, io = { stdout: [], stderr: [] }) {
+  if (options.json) {
+    io.stdout.push(
+      JSON.stringify(
+        result.ok ? {
+          ok: true,
+          value: result.value,
+          uf: result.uf,
+          format: result.format,
+          ...options.source ? { source: options.source } : {}
+        } : {
+          ok: false,
+          code: result.code,
+          message: result.message,
+          ...result.uf ? { uf: result.uf } : {}
+        },
+        null,
+        2
+      )
+    );
+    return result.ok ? EXIT.OK : EXIT.INVALID;
+  }
+  if (options.quiet) {
+    return result.ok ? EXIT.OK : EXIT.INVALID;
+  }
+  if (result.ok) {
+    io.stdout.push(`valid: yes (${result.uf})`);
+    io.stdout.push(`value: ${result.value}`);
+    io.stdout.push(`format: ${result.format}`);
+    if (options.source) {
+      io.stdout.push(`source: ${options.source}`);
+    }
+    return EXIT.OK;
+  }
+  io.stderr.push("valid: no");
+  io.stderr.push(`code: ${result.code}`);
+  io.stderr.push(`message: ${result.message}`);
+  if (result.uf) {
+    io.stderr.push(`uf: ${result.uf}`);
+  }
+  return EXIT.INVALID;
+}
+function runIeCommand(action, input, options, io = { stdout: [], stderr: [] }) {
+  const uf = resolveUf(options.uf);
+  if (!uf) {
+    io.stderr.push(`Missing or invalid --uf. Use one of: ${IE_SUPPORTED_UFS.join(", ")}.`);
+    return EXIT.USAGE;
+  }
+  const source = options.source ? getIeOfficialSourceUrl(uf) : void 0;
+  switch (action) {
+    case "validate":
+      return printIeValidation(validateInscricaoEstadual(input, { uf }), { json: options.json, quiet: options.quiet, source }, io);
+    case "format":
+      return printFormat(formatInscricaoEstadual(input, { uf }), { json: options.json, quiet: options.quiet }, io);
+    case "strip":
+      return printStrip(stripInscricaoEstadual(input), { json: options.json }, io);
+    default: {
+      const _exhaustive = action;
+      io.stderr.push(`Unknown action: ${_exhaustive}`);
+      return EXIT.USAGE;
+    }
+  }
+}
+function runIe(action, value, options, io = { stdout: [], stderr: [] }) {
+  const input = resolveInput9(value, options.file);
+  if (input === null) {
+    io.stderr.push("Missing IE value. Pass an argument or use --file.");
+    return EXIT.USAGE;
+  }
+  return runIeCommand(action, input, options, io);
+}
+
+// src/commands/list.ts
+function listSupportedTypes(io = { stdout: [] }) {
+  for (const type of SUPPORTED_TYPES) {
+    io.stdout.push(type);
+  }
+  return 0;
+}
+
+// src/handlers.ts
+function readInputFile(path, io) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    io.stderr.push(`Cannot read file: ${path}`);
+    return null;
+  }
+}
+function handleListCli(io = { stdout: [], stderr: [] }) {
+  return listSupportedTypes(io);
+}
+function handleCnpjCli(action, value, opts, io = { stdout: [], stderr: [] }) {
+  let fileContent;
+  if (opts.file) {
+    const content = readInputFile(opts.file, io);
+    if (content === null) {
+      return EXIT.USAGE;
+    }
+    fileContent = content;
+  }
+  return runCnpj(
+    action,
+    value,
+    {
+      json: Boolean(opts.json),
+      quiet: Boolean(opts.quiet),
+      source: Boolean(opts.source),
+      file: fileContent
+    },
+    io
+  );
+}
+function handleCpfCli(action, value, opts, io = { stdout: [], stderr: [] }) {
+  let fileContent;
+  if (opts.file) {
+    const content = readInputFile(opts.file, io);
+    if (content === null) {
+      return EXIT.USAGE;
+    }
+    fileContent = content;
+  }
+  return runCpf(
+    action,
+    value,
+    {
+      json: Boolean(opts.json),
+      quiet: Boolean(opts.quiet),
+      source: Boolean(opts.source),
+      file: fileContent
+    },
+    io
+  );
+}
+function handleCepCli(action, value, opts, io = { stdout: [], stderr: [] }) {
+  let fileContent;
+  if (opts.file) {
+    const content = readInputFile(opts.file, io);
+    if (content === null) {
+      return EXIT.USAGE;
+    }
+    fileContent = content;
+  }
+  return runCep(
+    action,
+    value,
+    {
+      json: Boolean(opts.json),
+      quiet: Boolean(opts.quiet),
+      source: Boolean(opts.source),
+      file: fileContent
+    },
+    io
+  );
+}
+function handlePlacaCli(action, value, opts, io = { stdout: [], stderr: [] }) {
+  let fileContent;
+  if (opts.file) {
+    const content = readInputFile(opts.file, io);
+    if (content === null) {
+      return EXIT.USAGE;
+    }
+    fileContent = content;
+  }
+  return runPlaca(
+    action,
+    value,
+    {
+      json: Boolean(opts.json),
+      quiet: Boolean(opts.quiet),
+      source: Boolean(opts.source),
+      file: fileContent
+    },
+    io
+  );
+}
+function handlePisPasepCli(action, value, opts, io = { stdout: [], stderr: [] }) {
+  let fileContent;
+  if (opts.file) {
+    const content = readInputFile(opts.file, io);
+    if (content === null) {
+      return EXIT.USAGE;
+    }
+    fileContent = content;
+  }
+  return runPisPasep(
+    action,
+    value,
+    {
+      json: Boolean(opts.json),
+      quiet: Boolean(opts.quiet),
+      source: Boolean(opts.source),
+      file: fileContent
+    },
+    io
+  );
+}
+function handlePixCli(action, value, opts, io = { stdout: [], stderr: [] }) {
+  let fileContent;
+  if (opts.file) {
+    const content = readInputFile(opts.file, io);
+    if (content === null) {
+      return EXIT.USAGE;
+    }
+    fileContent = content;
+  }
+  return runPix(
+    action,
+    value,
+    {
+      json: Boolean(opts.json),
+      quiet: Boolean(opts.quiet),
+      source: Boolean(opts.source),
+      type: opts.type,
+      file: fileContent
+    },
+    io
+  );
+}
+function handleBoletoCli(action, value, opts, direction, io = { stdout: [], stderr: [] }) {
+  let fileContent;
+  if (opts.file) {
+    const content = readInputFile(opts.file, io);
+    if (content === null) {
+      return EXIT.USAGE;
+    }
+    fileContent = content;
+  }
+  return runBoleto(
+    action,
+    value,
+    {
+      json: Boolean(opts.json),
+      quiet: Boolean(opts.quiet),
+      source: Boolean(opts.source),
+      kind: opts.kind,
+      file: fileContent
+    },
+    direction,
+    io
+  );
+}
+function handleCartaoCli(action, value, opts, io = { stdout: [], stderr: [] }) {
+  let fileContent;
+  if (opts.file) {
+    const content = readInputFile(opts.file, io);
+    if (content === null) {
+      return EXIT.USAGE;
+    }
+    fileContent = content;
+  }
+  return runCartao(
+    action,
+    value,
+    {
+      json: Boolean(opts.json),
+      quiet: Boolean(opts.quiet),
+      source: Boolean(opts.source),
+      file: fileContent
+    },
+    io
+  );
+}
+function handleCartaoCreditoCli(action, value, opts, io = { stdout: [], stderr: [] }) {
+  let fileContent;
+  if (opts.file) {
+    const content = readInputFile(opts.file, io);
+    if (content === null) {
+      return EXIT.USAGE;
+    }
+    fileContent = content;
+  }
+  return runCartao(
+    action,
+    value,
+    {
+      json: Boolean(opts.json),
+      quiet: Boolean(opts.quiet),
+      source: Boolean(opts.source),
+      file: fileContent
+    },
+    io
+  );
+}
+function handleIeCli(action, value, opts, io = { stdout: [], stderr: [] }) {
+  let fileContent;
+  if (opts.file) {
+    const content = readInputFile(opts.file, io);
+    if (content === null) {
+      return EXIT.USAGE;
+    }
+    fileContent = content;
+  }
+  return runIe(
+    action,
+    value,
+    {
+      json: Boolean(opts.json),
+      quiet: Boolean(opts.quiet),
+      source: Boolean(opts.source),
+      uf: opts.uf,
+      file: fileContent
+    },
+    io
+  );
+}
+function writeCliIo(io) {
+  for (const line of io.stdout) console.log(line);
+  for (const line of io.stderr) console.error(line);
+}
+
+// src/program.ts
+function createProgram() {
+  const program = new Command();
+  program.name("br-validators").description("100% open-source Brazilian document validators").version("0.10.0-alpha.0");
+  program.command("list").description("List supported document types").action(() => {
+    const io = { stdout: [], stderr: [] };
+    process.exitCode = handleListCli(io);
+    writeCliIo(io);
+  });
+  const cnpj = program.command("cnpj").description("CNPJ \u2014 numeric and alphanumeric (RFB Q14)");
+  for (const action of ["validate", "format", "strip"]) {
+    cnpj.command(action).description(`${action} a CNPJ`).argument("[value]", "CNPJ value (raw or masked)").option("--json", "JSON output").option("-q, --quiet", "Exit code only").option("--source", "Include official source URL (validate only)").option("-f, --file <path>", "Read value from file").action((value, opts) => {
+      const io = { stdout: [], stderr: [] };
+      process.exitCode = handleCnpjCli(action, value, opts, io);
+      writeCliIo(io);
+    });
+  }
+  const cpf = program.command("cpf").description("CPF \u2014 numeric modulo 11 (RFB)");
+  for (const action of ["validate", "format", "strip"]) {
+    cpf.command(action).description(`${action} a CPF`).argument("[value]", "CPF value (raw or masked)").option("--json", "JSON output").option("-q, --quiet", "Exit code only").option("--source", "Include official source URL (validate only)").option("-f, --file <path>", "Read value from file").action((value, opts) => {
+      const io = { stdout: [], stderr: [] };
+      process.exitCode = handleCpfCli(action, value, opts, io);
+      writeCliIo(io);
+    });
+  }
+  const cep = program.command("cep").description("CEP \u2014 8-digit postal code (Correios)");
+  for (const action of ["validate", "format", "strip"]) {
+    cep.command(action).description(`${action} a CEP`).argument("[value]", "CEP value (raw or masked)").option("--json", "JSON output").option("-q, --quiet", "Exit code only").option("--source", "Include official source URL (validate only)").option("-f, --file <path>", "Read value from file").action((value, opts) => {
+      const io = { stdout: [], stderr: [] };
+      process.exitCode = handleCepCli(action, value, opts, io);
+      writeCliIo(io);
+    });
+  }
+  const placa = program.command("placa").description("Placa \u2014 legacy + Mercosul (CONTRAN)");
+  for (const action of ["validate", "format", "strip", "convert"]) {
+    placa.command(action).description(`${action} a license plate`).argument("[value]", "Placa value (raw or masked)").option("--json", "JSON output").option("-q, --quiet", "Exit code only").option("--source", "Include official source URL (validate only)").option("-f, --file <path>", "Read value from file").action((value, opts) => {
+      const io = { stdout: [], stderr: [] };
+      process.exitCode = handlePlacaCli(action, value, opts, io);
+      writeCliIo(io);
+    });
+  }
+  const pisPasep = program.command("pis-pasep").description("PIS/PASEP \u2014 numeric modulo 11 (Caixa/INSS)");
+  for (const action of ["validate", "format", "strip"]) {
+    pisPasep.command(action).description(`${action} a PIS/PASEP number`).argument("[value]", "PIS/PASEP value (raw or masked)").option("--json", "JSON output").option("-q, --quiet", "Exit code only").option("--source", "Include official source URL (validate only)").option("-f, --file <path>", "Read value from file").action((value, opts) => {
+      const io = { stdout: [], stderr: [] };
+      process.exitCode = handlePisPasepCli(action, value, opts, io);
+      writeCliIo(io);
+    });
+  }
+  const pix = program.command("pix").description("PIX key \u2014 CPF, CNPJ, email, phone, EVP (Bacen)");
+  pix.command("detect").description("detect PIX key type").argument("[value]", "PIX key value").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 = handlePixCli("detect", value, opts, io);
+    writeCliIo(io);
+  });
+  pix.command("validate").description("validate a PIX key").argument("[value]", "PIX key value").option("--json", "JSON output").option("-q, --quiet", "Exit code only").option("--source", "Include official source URL").option("--type <type>", "Force key type: cpf, cnpj, email, phone, evp").option("-f, --file <path>", "Read value from file").action((value, opts) => {
+    const io = { stdout: [], stderr: [] };
+    process.exitCode = handlePixCli("validate", value, opts, io);
+    writeCliIo(io);
+  });
+  pix.command("format").description("format a PIX key").argument("[value]", "PIX key value").option("--json", "JSON output").option("-q, --quiet", "Exit code only").option("--type <type>", "Force key type: cpf, cnpj, email, phone, evp").option("-f, --file <path>", "Read value from file").action((value, opts) => {
+    const io = { stdout: [], stderr: [] };
+    process.exitCode = handlePixCli("format", value, opts, io);
+    writeCliIo(io);
+  });
+  const boleto = program.command("boleto").description("Boleto \u2014 linha digit\xE1vel + c\xF3digo de barras (FEBRABAN)");
+  boleto.command("detect").description("detect boleto input kind").argument("[value]", "Linha digit\xE1vel or c\xF3digo de barras").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 = handleBoletoCli("detect", value, opts, void 0, io);
+    writeCliIo(io);
+  });
+  boleto.command("validate").description("validate a boleto").argument("[value]", "Linha digit\xE1vel or c\xF3digo de barras").option("--json", "JSON output").option("-q, --quiet", "Exit code only").option("--source", "Include official source URL").option("--kind <kind>", "Force input kind: linha-digitavel, codigo-barras").option("-f, --file <path>", "Read value from file").action((value, opts) => {
+    const io = { stdout: [], stderr: [] };
+    process.exitCode = handleBoletoCli("validate", value, opts, void 0, io);
+    writeCliIo(io);
+  });
+  const convert = boleto.command("convert").description("convert between linha digit\xE1vel and c\xF3digo de barras");
+  for (const direction of ["linha-to-barras", "barras-to-linha"]) {
+    convert.command(direction).description(`convert boleto ${direction.replace(/-/g, " ")}`).argument("[value]", "Linha digit\xE1vel or c\xF3digo de barras").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 = handleBoletoCli("convert", value, opts, direction, io);
+      writeCliIo(io);
+    });
+  }
+  for (const action of ["format", "strip"]) {
+    boleto.command(action).description(`${action} a boleto linha digit\xE1vel`).argument("[value]", "Linha digit\xE1vel or c\xF3digo de barras").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 = handleBoletoCli(action, value, opts, void 0, io);
+      writeCliIo(io);
+    });
+  }
+  const cartao = program.command("cartao").description("Credit card PAN \u2014 Luhn / ISO/IEC 7812-1");
+  cartao.command("detect").description("detect card brand (best-effort)").argument("[value]", "Credit card PAN (raw or masked)").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 = handleCartaoCli("detect", value, opts, io);
+    writeCliIo(io);
+  });
+  for (const action of ["validate", "format", "strip"]) {
+    cartao.command(action).description(`${action} a credit card PAN`).argument("[value]", "Credit card PAN (raw or masked)").option("--json", "JSON output").option("-q, --quiet", "Exit code only").option("--source", "Include official source URL (validate only)").option("-f, --file <path>", "Read value from file").action((value, opts) => {
+      const io = { stdout: [], stderr: [] };
+      process.exitCode = handleCartaoCli(action, value, opts, io);
+      writeCliIo(io);
+    });
+  }
+  const cartaoCredito = program.command("cartao-credito").description("Credit card PAN \u2014 Luhn / ISO/IEC 7812-1 (library subpath alias)");
+  for (const action of ["validate", "format", "strip"]) {
+    cartaoCredito.command(action).description(`${action} a credit card PAN`).argument("[value]", "Credit card PAN (raw or masked)").option("--json", "JSON output").option("-q, --quiet", "Exit code only").option("--source", "Include official source URL (validate only)").option("-f, --file <path>", "Read value from file").action((value, opts) => {
+      const io = { stdout: [], stderr: [] };
+      process.exitCode = handleCartaoCreditoCli(action, value, opts, io);
+      writeCliIo(io);
+    });
+  }
+  const ie = program.command("ie").description("Inscri\xE7\xE3o Estadual \u2014 SP, MT, DF (SEFAZ/SINTEGRA check digits)");
+  for (const action of ["validate", "format", "strip"]) {
+    ie.command(action).description(`${action} an Inscri\xE7\xE3o Estadual`).argument("[value]", "IE value (raw or masked)").requiredOption("--uf <uf>", "State code (27 UFs, e.g. SP, RJ, MG)").option("--json", "JSON output").option("-q, --quiet", "Exit code only").option("--source", "Include official source URL (validate only)").option("-f, --file <path>", "Read value from file").action((value, opts) => {
+      const io = { stdout: [], stderr: [] };
+      process.exitCode = handleIeCli(action, value, opts, io);
+      writeCliIo(io);
+    });
+  }
+  return program;
+}
+function run(argv) {
+  createProgram().parse(argv);
+}
+
+// src/index.ts
+run(process.argv);

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@br-validators/cli",
+  "version": "0.10.0-alpha.0",
+  "description": "Terminal CLI for Brazilian document validation — CPF, CNPJ, CEP, IE, PIX, boleto, and more",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexandreZanata/doc-raiz.git",
+    "directory": "apps/cli"
+  },
+  "homepage": "https://github.com/AlexandreZanata/doc-raiz#readme",
+  "bugs": {
+    "url": "https://github.com/AlexandreZanata/doc-raiz/issues"
+  },
+  "keywords": [
+    "brazil",
+    "cli",
+    "validator",
+    "cpf",
+    "cnpj"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "br-validators": "./dist/index.js"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "@br-validators/core": "0.10.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "pretypecheck": "pnpm --filter @br-validators/core build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests --max-warnings 0"
+  }
+}