Línea de comandos

El paquete tiene una interfaz de línea de comandos para scripts de shell, flujos de datos, trabajos de CI y llamadas a herramientas de agentes de IA. Aplica las mismas reglas que la librería, con los mismos identificadores de regla, y no tiene dependencias. Ejecútala con npx, que descarga el paquete la primera vez, o instala el paquete y ejecuta nif-dni-nie-cif-validation desde los scripts de tu proyecto. Necesita Node.js 20 o posterior.

npx nif-dni-nie-cif-validation --help
npx nif-dni-nie-cif-validation validate --help

Comando	Qué hace
`validate <value...>`	Valida cada valor, como `validate()`
`type <value>`	Detecta el tipo solo por el formato, como `getNifType()`
`normalize <value>`	Muestra la forma canónica, como `normalize()`
`generate <type>`	Genera valores de prueba: `dni`, `nie`, `cif` o `nif`
`check --file <csv> --column <name>`	Valida una columna de un archivo CSV

Validar valores

npx nif-dni-nie-cif-validation validate 12345678Z " x-0123456-7l " b-1234567-4 12345678A
# 12345678Z: valid DNI 12345678Z
# " x-0123456-7l ": valid NIE X1234567L
# b-1234567-4: valid CIF B12345674 (Limited liability company)
# 12345678A: invalid [DNI-2 INVALID_CONTROL_CHARACTER] The control character is not correct: for this DNI it should be "Z".

Cada valor ocupa una línea: valid, con su tipo y la forma canónica que hay que guardar, o invalid, con la regla de SPEC.md que ha fallado, el código de error y el mensaje. Un valor con espacios se muestra entre comillas. Aquí el código de salida es 1, porque un valor no es válido.

Las opciones de validate() son flags de validate y check. Sin ellas, el comando sigue SPEC.md, igual que la librería:

Flag	Qué hace	Opción de `validate()`
`--types DNI,NIE`	Solo acepta estos tipos, separados por comas: `DNI`, `NIF_KLM`, `NIE`, `CIF`. Otro tipo da `UNSUPPORTED_TYPE`	`types`
`--cif-control lenient`	C D F G J U V también admiten una letra como carácter de control, como en la v1. No tiene base oficial: úsalo solo con datos heredados	`cifControl`
`--reject-placeholders`	Rechaza los números de ejemplo `00000000T`, `00000001R`, `99999999R` y `X0000000T`	`rejectPlaceholders`
`--allow-vat-prefix`	También acepta un NIF-IVA español: `ES` y un NIF	`allowVatPrefix`
`--locale es`	El idioma de los mensajes y de los nombres de las organizaciones: `en` (por defecto), `es`, `ca`, `eu` o `gl`	`locale`

npx nif-dni-nie-cif-validation validate 12345678A B12345674 --locale es
# 12345678A: invalid [DNI-2 INVALID_CONTROL_CHARACTER] El carácter de control no es correcto: para este DNI debería ser «Z».
# B12345674: valid CIF B12345674 (Sociedad de responsabilidad limitada)
npx nif-dni-nie-cif-validation validate B12345674 --types DNI,NIE
# B12345674: invalid [POLICY-2 UNSUPPORTED_TYPE] This NIF of a legal person or entity (CIF) is not accepted here.

Los códigos de error y los idiomas se explican en Códigos de error y mensajes traducidos.

JSON para scripts y agentes

--json imprime un único documento JSON en la salida estándar. En validate es un array con un objeto por valor, en orden: el valor tal como se ha pasado (input) y el resultado de validate(). Es un array incluso con un solo valor, así que un script lee todas las llamadas de la misma forma.

npx nif-dni-nie-cif-validation validate 12345678A --json
# [
#   {
#     "input": "12345678A",
#     "valid": false,
#     "type": "DNI",
#     "normalized": "12345678A",
#     "error": {
#       "code": "INVALID_CONTROL_CHARACTER",
#       "message": "The control character is not correct: for this DNI it should be \"Z\".",
#       "rule": "DNI-2",
#       "expected": "Z"
#     }
#   }
# ]

Comando	Documento JSON
`validate`	`[{ input, valid, type, normalized, error?, meta? }]`: el valor y su resultado, para cada valor
`type`	`{ input, type }`, donde `type` es `null` si no se reconoce el formato
`normalize`	`{ input, normalized }`
`generate`	`{ seed, values }`
`check`	`{ file, column, rows, valid, invalid, errors }`, donde `errors` tiene `{ row, input, ...result }` para cada fila no válida

Las versiones futuras pueden añadir campos, pero nunca quitar ni renombrar ninguno.

Códigos de salida

Código de salida	Cuándo
`0`	Todo es válido. `normalize`, `generate`, `--help` y `--version` también terminan con 0
`1`	Algo no es válido: un valor, una fila del archivo CSV o un formato que `type` no reconoce
`2`	El comando está mal: un comando o una opción desconocidos, un valor de opción incorrecto, un archivo que no se puede leer o una columna que no existe. El mensaje va a la salida de error, y nada a la salida estándar

Así, un script puede comprobar un valor sin leer la salida:

if npx nif-dni-nie-cif-validation validate "$NIF" > /dev/null; then echo "valid"; fi

Tipo y forma canónica

npx nif-dni-nie-cif-validation type 12345678A
# DNI
npx nif-dni-nie-cif-validation normalize " x-0123456-7l "
# X1234567L

type da el tipo que muestra el formato: DNI, NIF_KLM, NIE o CIF. No comprueba el carácter de control, así que aquí 12345678A es un DNI, y uno no válido para validate. Si el formato no es ninguno de ellos, termina con 1. normalize quita espacios, puntos, guiones y barras y da la forma en mayúsculas, pero no valida: para guardar un valor, valídalo y quédate con su forma canónica. Consulta Normalizar y formatear la entrada.

Datos de prueba

npx nif-dni-nie-cif-validation generate dni --count 3 --seed 42
# 60110375J
# 44829056D
# 85246578E
npx nif-dni-nie-cif-validation generate cif --seed 1 --format
# P-0027357-C

generate imprime valores válidos de un tipo: dni, nie, cif, o nif para cualquiera de ellos. --count indica cuántos (hasta 1 000 000). Con --seed, los valores son los mismos en cada ejecución y en cada máquina; sin ella, la semilla es aleatoria y --json la muestra, así que puedes volver a generar los mismos valores. --format da la forma de presentación, con guiones.

Revisar un archivo CSV

Para un archivo customers.csv con los nombres de las columnas en su primera fila:

id,nif,name
1,12345678Z,Ana
2,"B-1234567-4","Acme, S.L."
3,12345678A,Luis

npx nif-dni-nie-cif-validation check --file customers.csv --column nif
# row 4: 12345678A: invalid [DNI-2 INVALID_CONTROL_CHARACTER] The control character is not correct: for this DNI it should be "Z".
# 3 rows checked in customers.csv, column "nif": 2 valid, 1 invalid

check valida la columna que indica --column e imprime una línea por cada fila no válida y, al final, un resumen. Las filas se numeran como en una hoja de cálculo: la primera fila después de los nombres es la fila 2. Las líneas en blanco se omiten, y una celda vacía no es válida (EMPTY). Acepta los mismos flags que validate, y --json da los recuentos y el resultado de cada fila no válida.

El archivo se lee como CSV en UTF-8 (RFC 4180): un campo entre comillas dobles puede contener comas, saltos de línea y comillas dobladas, los saltos de línea pueden ser CRLF o LF, y se ignora la marca de orden de bytes (BOM). Las hojas de cálculo en español suelen guardar los CSV con punto y coma: léelos con --delimiter ";". El archivo se lee entero en memoria; para archivos muy grandes, usa la librería con un stream, como en el ejemplo de CSV.