ntlink

Cliente de línea de comandos en Node.js y TypeScript para la API REST de NTLink Proxy CFDI. Conserva el comando público ntlink y el alias heredado proxy-cli.

Requisitos

• Node.js 22.12 o posterior.
• npm 10 o posterior.
• Acceso a la API de NTLink para las operaciones autenticadas.

Instalación desde npm

El paquete publicado es @ntlinkmx/ntlink-cli, en el registro público de npm dentro de la organización ntlinkmx. No requiere token de acceso:

npm install --global @ntlinkmx/ntlink-cli
ntlink --version

Para liberar una versión, actualiza version en package.json y package-lock.json, crea un commit y publica un Release de GitHub. El workflow .github/workflows/publish-cli.yml ejecutará las validaciones y publicará esa versión en https://www.npmjs.com/package/@ntlinkmx/ntlink-cli. Requiere el secret NPM_TOKEN: un granular access token de npm con permiso de escritura y bypass 2FA.

Instalación y construcción

npm install
npm run typecheck
npm test
npm run build
npm link

Después de npm link, ambos ejecutables quedan disponibles:

ntlink --version
proxy-cli --version

Para instalar un paquete generado localmente:

npm pack
npm install --global ./ntlink-ntlink-cli-1.1.0.tgz

Configuración y autenticación

ntlink auth login
ntlink config set --base-url http://dev-cfdi4.ntlink.com.mx --timeout 30
ntlink config show
ntlink auth logout

auth login solicita correo y contraseña —la contraseña se oculta cuando la terminal lo permite— y guarda los tokens de acceso y renovación. Si una petición autenticada devuelve HTTP 401, el cliente renueva el token y repite esa petición una sola vez.

La configuración se guarda en ~/.ntlink/config.json. Estas variables de entorno y opciones globales sobrescriben la configuración durante una ejecución:

| Configuración | Variable | Opción global | | --- | --- | --- | | URL de API | NTLINK_BASE_URL | --base-url | | Token de acceso | NTLINK_TOKEN | --token | | Tiempo límite | NTLINK_TIMEOUT | --timeout |

Por compatibilidad se siguen leyendo PROXY_CLI_BASE_URL, PROXY_CLI_TOKEN, PROXY_CLI_TIMEOUT y ~/.proxy-cli/config.json. config show enmascara los tokens; --reveal-token permite mostrarlos completos.

Uso

CFDI

ntlink cfdi stamp invoice.json
ntlink cfdi cancel UUID --reason 02
ntlink cfdi cancel UUID --reason 01 --replacement REPLACEMENT_UUID
ntlink cfdi validate invoice.xml
ntlink cfdi status UUID
ntlink cfdi download UUID --format xml
ntlink cfdi download UUID --format pdf --output invoice.pdf
ntlink cfdi download UUID --format pdf --output invoice.pdf --force
ntlink cfdi email UUID --to [email protected] --to [email protected]
ntlink cfdi list --page 0 --size 20 --receiver XAXX010101000
ntlink cfdi list --from 2026-01-01 --to 2026-01-31 --type I
ntlink cfdi list --filter "uuid=eq:00000000-0000-0000-0000-000000000000"

La descarga no sobrescribe archivos existentes salvo que se indique --force.

Cuenta del cliente

ntlink client info
ntlink client balance
ntlink client companies
ntlink client blacklist ABC010203XYZ

Dashboard

ntlink dashboard daily --range LAST_MONTH
ntlink dashboard types
ntlink dashboard status
ntlink dashboard top-receivers
ntlink dashboard top-transmitters

Los rangos aceptados son LAST_WEEK, LAST_MONTH, LAST_3_MONTHS y LAST_YEAR.

Catálogos SAT

ntlink catalogs list
ntlink catalogs get moneda
ntlink catalogs get moneda --id MXN
ntlink catalogs get moneda --description "Peso mexicano"

Salida y diagnóstico

Los resultados se escriben como JSON para que sean legibles y puedan consumirse desde scripts. --json se conserva para compatibilidad con automatizaciones existentes.

ntlink --json cfdi list --size 100
ntlink --json client info
ntlink --verbose dashboard daily

--verbose imprime el método, la URL, encabezados, estado y reintentos en stderr; contraseñas, tokens, cookies y API keys siempre se redactan. Para evitar duplicar operaciones cuyo resultado pudo ser incierto, sólo las peticiones GET se reintentan automáticamente ante fallos de red o HTTP 5xx. Las peticiones autenticadas sí pueden repetirse una vez después de recibir 401 y renovar el token.

Autocompletado

# Bash
ntlink completion bash > ~/.ntlink-complete.bash
source ~/.ntlink-complete.bash

# Zsh
ntlink completion zsh > ~/.ntlink-complete.zsh
source ~/.ntlink-complete.zsh

# Fish
ntlink completion fish > ~/.config/fish/completions/ntlink.fish

Desarrollo y pruebas

npm run dev               # recompilación continua
npm run typecheck         # TypeScript estricto
npm test                  # pruebas unitarias, sin red
npm run test:watch        # pruebas unitarias en modo watch
npm run test:integration  # API real; requiere NTLINK_TEST_TOKEN
npm run build             # genera dist/cli.js

Consulta tests/README.md para configurar las pruebas de integración.

Estructura

src/
├── cli.ts
├── commands/             # auth, config, CFDI, cliente, dashboard y catálogos
└── core/                 # configuración, HTTP, archivos y salida
tests/
├── *.test.ts             # pruebas unitarias
└── integration/          # pruebas opcionales contra la API

Licencia

MIT. Consulta LICENSE.