CLI
@openfactura/cli (MIT) talks to Open Factura only through its REST API: it doesn’t sign or transmit
on its own and doesn’t need the Hacienda certificate on your machine. It requires Node.js 20 or later
(it also works with Bun).
npm i -g @openfactura/cliopenfactura --version
# or without installingnpx @openfactura/cli --helpLog in
Section titled “Log in”openfactura login --url https://app.openfactura.co# Clave de API (of_test_… u of_live_…): ← typed without being echoedlogin verifies the key and saves it to ~/.config/openfactura/config.json with 0600 permissions.
Other ways:
echo "$CLAVE" | openfactura login --url https://app.openfactura.co # from a pipeopenfactura login --profile produccion # another profileopenfactura logoutOn your own server (no dashboard), the operator creates the organization and a test key with the
server’s ADMIN_TOKEN; the key is saved as with login, and the token is not stored:
OPENFACTURA_ADMIN_TOKEN=… openfactura alta "Mi Empresa" --url https://YOUR-DOMAINIn CI, environment variables are enough:
export OPENFACTURA_URL=https://app.openfactura.coexport OPENFACTURA_API_KEY=of_test_...openfactura whoami| Value | Precedence |
|---|---|
| Server URL | --url → OPENFACTURA_URL → saved profile → https://app.openfactura.co |
| API key | OPENFACTURA_API_KEY → saved profile |
| Profile | --profile → OPENFACTURA_PROFILE → default |
Commands
Section titled “Commands”All of them accept --json (the API’s JSON on stdout), --url, --profile, and --help.
openfactura whoami # actor, permissions, environmentopenfactura emisor # tax details, establishments, loaded credentials
openfactura clientes list --q "contribuyente" # customers: production onlyopenfactura clientes add --file cliente.jsonopenfactura productos list --q licenciaopenfactura productos add --codigo LIC-001 --descripcion "Licencia anual" --precio 100 --tipo-item 2
openfactura catalogos CAT-013 --departamento 06
openfactura dte validar factura.jsonopenfactura dte emitir factura.json [--idempotency-key <key>]openfactura dte list --tipo 01 --estado procesado --desde 2026-11-01 --hasta 2026-11-30openfactura dte get <codigo>openfactura dte json <codigo> -o dte.jsonopenfactura dte pdf <codigo> -o factura.pdfopenfactura dte invalidar <codigo> --tipo 2 --motivo "Operación rescindida"openfactura dte retorno <codigo> retorno.json
openfactura eventos operaciones-especiales simplificadas.jsonopenfactura eventos list --tipo retornoopenfactura eventos get|json|pdf <codigo>
openfactura contingencia transmitir
openfactura webhooks listopenfactura webhooks add https://pos.ejemplo.com/hooks [--eventos dte.procesado,dte.rechazado] [--descripcion "POS"]openfactura webhooks test <id> # sends a webhook.prueba event (exit 1 if not delivered)openfactura webhooks deliveries <id> # last 50 deliveriesopenfactura webhooks rotate <id> # new signing secret, shown onceopenfactura webhooks remove <id>
openfactura uso [--desde 2026-11-01] [--hasta 2026-11-30] # issued, processed, and rejected per dayopenfactura registros list [--estado error] [--origen api] [--limite 50] # requires registros:read
openfactura certificacion estado # Open Factura Cloud onlyopenfactura certificacion ejecutar --receptor openfactura # issues the minimum tests (Open Factura Cloud)openfactura certificacion ejecutar --completo [--desde-cero] # every document; from scratchThe file for dte emitir is the same body as POST /api/v1/dte (see
Issue documents). - reads from standard input.
Saved customers only exist in production: with a test key, clientes responds
clientes_solo_produccion and the recipient goes in datos.receptor. Products and webhooks are those
of the key’s environment. In certificacion ejecutar, --receptor is openfactura (recommended) or
a JSON (file or -) with another taxpayer’s details; see
Certification.
Your customers (Plataforma)
Section titled “Your customers (Plataforma)”With Plataforma (Open Factura Cloud) you manage your customers’ companies
from the terminal. plataforma … always uses your key (enabled for Plataforma); usar switches
context, like gh accounts or kubectl contexts:
openfactura plataforma add "Casa Barista" --external-id cb-1 --nit 0614-290786-102-3openfactura plataforma enlace cb-1 # their link to activate the accountopenfactura plataforma list # status and what's missing (→ the one in use)
openfactura usar cb-1 # from here on you act as Casa Baristaopenfactura dte emitir factura.json # issued in THEIR space, with their numberingopenfactura webhooks add https://pos.casabarista.sv/hooksopenfactura usar --yo # back to your own account
openfactura plataforma clave cb-1 --live --yes # key for the customer's system (issues only for them)usar creates a key in the customer’s space once (a test key; with --live, a production key,
with confirmation) and saves it in your profile with 0600 permissions. Switching customers doesn’t
create new keys. whoami shows who you are acting as. When OPENFACTURA_API_KEY is set, that key
wins and the customer in use is ignored.
In scripts
Section titled “In scripts”codigo=$(openfactura dte emitir factura.json --json | jq -r .codigoGeneracion)openfactura dte pdf "$codigo" -o "facturas/$codigo.pdf"Errors go to stderr as Error [codigo]: mensaje; with --json, stderr gets the API’s error JSON.
| Exit code | Meaning |
|---|---|
0 |
Success |
1 |
API or validation error (includes network errors) |
2 |
Incorrect usage: invalid option, unreadable file, missing --yes |
3 |
Not authenticated: the key is missing, invalid, revoked, or expired |
4 |
Rate limit exceeded |
The CLI also includes an MCP server over stdio: openfactura mcp.
For AI assistants: llms.txt ·llms-full.txt ·every page as Markdown by adding .md to its path.