Argumentos de la línea de órdenes en Node.js

Un programa de Node puede recibir datos desde la terminal, como cualquier orden del sistema. Para lo básico está process.argv, y para opciones con nombre, parseArgs, que viene incluido en Node desde la versión 18.

Lo mínimo: process.argv

console.log("node:", process.argv[0]);
console.log("guion:", process.argv[1]);
console.log("argumentos:", process.argv.slice(2));

node args.mjs uno dos "tres cuatro"

salidanode: /usr/local/bin/node
guion: /w/args.mjs
argumentos: [ 'uno', 'dos', 'tres cuatro' ]

process.argv es un array de cadenas. Las dos primeras posiciones son la ruta de Node y la del guion, así que lo que escribió el usuario empieza en la posición 2: de ahí el slice(2). Las comillas agrupan: "tres cuatro" llega como un solo argumento.

Opciones con nombre: parseArgs

import { parseArgs } from "node:util";

const { values, positionals } = parseArgs({
  options: {
    nombre: { type: "string", short: "n", default: "mundo" },
    veces: { type: "string", short: "v", default: "1" },
    mayus: { type: "boolean", short: "m", default: false },
    ayuda: { type: "boolean", short: "h" },
  },
  allowPositionals: true,
});

if (values.ayuda) {
  console.log(`Uso: node saludo.mjs [opciones] [archivos...]

  -n, --nombre <texto>  a quién saludar (por omisión: mundo)
  -v, --veces <número>  cuántas veces (por omisión: 1)
  -m, --mayus           en mayúsculas
  -h, --ayuda           muestra esta ayuda`);
  process.exit(0);
}

const veces = Number.parseInt(values.veces, 10);
if (Number.isNaN(veces) || veces < 1) {
  console.error(`--veces tiene que ser un número mayor que 0, no «${values.veces}»`);
  process.exit(2);
}

let saludo = `Hola, ${values.nombre}`;
if (values.mayus) saludo = saludo.toUpperCase();
for (let i = 0; i < veces; i++) console.log(saludo);

if (positionals.length > 0) console.log("argumentos sueltos:", positionals);

Se declara cada opción con su tipo ("string" o "boolean"), una letra corta opcional y un valor por omisión. parseArgs devuelve values, con las opciones, y positionals, con lo que sobra: normalmente nombres de archivo.

node saludo.mjs
node saludo.mjs --nombre Ana -v 2
node saludo.mjs -n Ana -m informe.txt datos.csv
node saludo.mjs --nombre=Luis -mv 2

salidaHola, mundo
Hola, Ana
Hola, Ana
HOLA, ANA
argumentos sueltos: [ 'informe.txt', 'datos.csv' ]
HOLA, LUIS
HOLA, LUIS

Admite las tres formas habituales: --nombre Ana, --nombre=Ana y -n Ana. Y también agrupar letras cortas al estilo de Unix: -mv 2 equivale a -m -v 2.

node saludo.mjs -v tres--veces tiene que ser un número mayor que 0, no «tres»

La ayuda la escribes tú

A diferencia de otras bibliotecas, parseArgs no genera la ayuda. Por eso el ejemplo declara la opción --ayuda y la imprime él mismo:

node saludo.mjs -hUso: node saludo.mjs [opciones] [archivos...]

  -n, --nombre <texto>  a quién saludar (por omisión: mundo)
  -v, --veces <número>  cuántas veces (por omisión: 1)
  -m, --mayus           en mayúsculas
  -h, --ayuda           muestra esta ayuda

El error frecuente: una opción que no existe

Por omisión, parseArgs es estricto: una opción no declarada lanza una excepción, y sin capturar sale con toda la traza, que asusta a cualquiera:

node saludo.mjs --color rojoTypeError [ERR_PARSE_ARGS_UNKNOWN_OPTION]: Unknown option '--color'. To specify a positional argument starting with a '-', place it at the end of the command after '--', as in '-- "--color"
    at checkOptionUsage (node:internal/util/parse_args/parse_args:102:13)
    ...

Lo correcto es capturarla, mostrar solo el mensaje y salir con un código distinto de cero, que es como las órdenes del sistema avisan de que algo fue mal:

import { parseArgs } from "node:util";

let opciones;
try {
  opciones = parseArgs({
    options: { nombre: { type: "string", short: "n", default: "mundo" } },
  });
} catch (err) {
  console.error(`Error: ${err.message}`);
  console.error("Prueba con --ayuda");
  process.exit(2);
}
console.log(`Hola, ${opciones.values.nombre}`);

node saludo2.mjs --color rojoError: Unknown option '--color'
Prueba con --ayuda

Cuál usar

Todo el código de esta página se ejecutó con Node.js 24.22 en un contenedor limpio antes de publicarla; las salidas, incluidos los errores, están copiadas de esa ejecución. Documentación oficial: util.parseArgs en la documentación de Node.js.