FactuCat CLI

FactuCat CLI is the command-line interface for FactuCat, a cloud-only product for issuing Mexican CFDI 4.0 invoices.

It is designed for two use cases:

• interactive invoicing for humans who want a guided flow
• unattended automation for agents, scripts, and integrations that need stable --json output

FactuCat CLI works with Mexican tax concepts and SAT terminology such as CFDI, timbrado, RFC, razón social, régimen fiscal, uso CFDI, XML, and PDF.

Install

npm install -g @factucat/cli

Verify the installation:

factucat --help

Update to the latest version:

npm install -g @factucat/cli@latest

Authenticate

First generate an API key in FactuCat:

1. Sign in to https://factucat.com
2. Open the settings area
3. On any settings screen, with no input focused, type the Konami code: ↑ ↑ ↓ ↓ ← → ← → B A
4. FactuCat unlocks the hidden API keys section in the settings sidebar
5. Open API keys, create a new key, and copy it immediately

The full token is only shown once after creation.

Then save it locally:

factucat auth api-key set

You can also provide it explicitly:

factucat auth api-key set --value fc_live_xxxxx

Or through standard input:

printf 'fc_live_xxxxx\n' | factucat auth api-key set

Validate the current key:

factucat auth status
factucat auth status --json

How the workflow works

FactuCat CLI uses a remote draft workflow:

1. Create a draft in FactuCat Cloud
2. Assign the customer or receiver data
3. Set invoice metadata such as uso CFDI, payment method, and currency
4. Add line items
5. Review the invoice preview
6. Stamp the invoice
7. Download the XML or PDF if needed

The server is always the source of truth. The CLI only remembers your current draft locally for convenience.

Interactive workflow

Create a draft:

factucat invoice create

Create a draft and automatically resolve a customer by name or RFC:

factucat invoice create --customer "Donde nacen las ideas"

That command is a shortcut: it creates the draft and internally tries to find the customer before linking it to the draft.

Add a line item:

factucat invoice add-item \
  --description "Desarrollo de sistema de facturación" \
  --unit-price 10000

If you omit SAT product code, SAT unit code, IVA, or retained ISR, FactuCat tries to infer them automatically.

Set invoice metadata:

factucat invoice set-meta \
  --cfdi-use G03 \
  --payment-method PUE \
  --payment-form 03

If you switch the invoice to USD without specifying an exchange rate, FactuCat automatically fetches the official DOF exchange rate:

factucat invoice set-meta --currency USD

Preview the full invoice before stamping:

factucat invoice show

Stamp interactively:

factucat invoice stamp

In an interactive terminal, invoice stamp shows the full preview first and can ask whether you want to send the stamped invoice through the customer contact channels registered in FactuCat.

Unattended workflow

For agents and scripts, prefer --json and --no-input.

Create a draft:

factucat invoice create --json

Set receiver data:

factucat invoice set-receiver \
  --draft-id dft_123 \
  --rfc XAXX010101000 \
  --legal-name "Público en general" \
  --postal-code 06000 \
  --tax-regime 616 \
  --json

Set invoice metadata:

factucat invoice set-meta \
  --draft-id dft_123 \
  --cfdi-use S01 \
  --payment-method PUE \
  --payment-form 01 \
  --currency MXN \
  --json

Add a line item with explicit taxes:

factucat invoice add-item \
  --draft-id dft_123 \
  --description "Servicios de consultoría" \
  --quantity 1 \
  --unit-price 1000 \
  --iva 16 \
  --isr-retenido 10 \
  --json

Preview the draft:

factucat invoice show --draft-id dft_123 --json

Stamp without prompts:

factucat invoice stamp --draft-id dft_123 --no-input --json

Stamp and request delivery to customer contacts:

factucat invoice stamp \
  --draft-id dft_123 \
  --send-to-customer-contacts \
  --no-input \
  --json

Or request specific channels:

factucat invoice stamp \
  --draft-id dft_123 \
  --send-customer-email \
  --send-customer-whatsapp \
  --no-input \
  --json

Current draft helpers

Select an existing draft as your current one:

factucat invoice use dft_123

Check which draft is currently selected:

factucat invoice current

Discard the current draft:

factucat invoice discard

Customer commands

Search customers:

factucat customer search "Donde nacen"

List customers:

factucat customer list --limit 20

Create a customer:

factucat customer create \
  --legal-name "Donde nacen las ideas" \
  --rfc DNI240101AB1 \
  --postal-code 45116 \
  --tax-regime 601 \
  --email [email protected]

Review and artifact download

List issued invoices:

factucat invoice list

Get a stamped invoice by UUID or folio:

factucat invoice get 019d231a-779b-771b-a666-ecefc6803fd2
factucat invoice get MIAU-00036

Download XML:

factucat invoice download xml MIAU-00036
factucat invoice download xml MIAU-00036 --output ./facturas/

Download PDF:

factucat invoice download pdf MIAU-00036
factucat invoice download pdf MIAU-00036 --output ./facturas/factura-marzo.pdf

If you do not pass --output, the file is saved in the current working directory.

Notes about inference

FactuCat automatically infers several values when possible:

• invoice add-item can infer SAT product code, SAT unit code, IVA, and retained ISR
• invoice set-meta --currency USD can infer the official DOF exchange rate if you omit --exchange-rate

This mirrors the behavior of FactuCat's guided product flows and keeps the CLI aligned with the rest of the platform.

Troubleshooting

API key inválida o revocada

The configured API key is wrong, expired, or has been revoked. Save a valid key again:

factucat auth api-key set
factucat auth status

No hay borrador activo

You tried to mutate a draft without selecting one first. Either create a draft or point to one explicitly:

factucat invoice create
factucat invoice use dft_123

Customer lookup is ambiguous

If invoice create --customer "..." matches multiple customers, search first and then pass the exact customer id:

factucat customer search "Donde nacen"
factucat invoice create --customer-id cus_123

Stamping fails

Review the draft before retrying:

factucat invoice show

Common causes are incomplete CFDI data, missing receiver information, or invalid concepts.

Downloaded artifact location

If you are unsure where a file was saved, use --output explicitly to control the destination path.

Learn more

• FactuCat: https://factucat.com
• Help page in npm package format: this README