facturas CLI Commands: init, cert, check, and issue

The facturas CLI provides four commands that cover the full credential setup and verification workflow for ARCA. This page documents every flag, output, and exit condition for each command. For a high-level introduction, see CLI Overview.

init, cert, and check never write to ARCA and do not create or modify any fiscal records. Only issue contacts ARCA to create a document — a real homologación voucher.

`facturas init`

Generates a 2048-bit RSA private key (PKCS#8, unencrypted) and a CSR formatted with the subject ARCA requires:

C=AR, O=<org>, CN=<alias>, serialNumber=CUIT <cuit>

Note the literal space after CUIT — this is what the ARCA spec mandates.

npx facturas init --cuit 20123456786 --env test

Running without flags in an interactive terminal prompts you for the CUIT and environment. In CI or scripts (no TTY), --cuit and --env are required; the command exits with code 2 if either is missing. CUIT validation runs before writing anything. The CLI accepts CUITs with or without hyphens or spaces (20-12345678-6, 20 12345678 6, 20123456786) and validates the 11-digit format and modulo-11 check digit. In a terminal it retries up to three times with the reason; non-interactively it exits immediately with code 2. After writing the files, init prints the exact steps to follow in ARCA — page names, field labels, and button text — for whichever environment you chose. It then prompts you to paste the certificate (equivalent to running facturas cert immediately after). Press Ctrl-C or pass --no-paste to skip that step and do it later with npx facturas cert.

Flags

required

Your 11-digit CUIT. Accepts hyphens and spaces. Validated before any file is written.

required

Target environment. Determines file names, clipboard behavior, and the ARCA instructions printed.

Common name for the CSR. Defaults to facturas. The alias ARCA sees is this name with hyphens and dots removed, plus Test or Production (ARCA only accepts letters and digits in symbolic names).

Organization field of the CSR. Defaults to the CUIT when omitted.

Directory to write the key and CSR. Defaults to the current working directory.

Overwrite existing arca-<env>.key and arca-<env>.csr files. Without this flag, the command refuses to overwrite and exits with code 1.

Print the CSR to the terminal instead of copying it to the clipboard.

Skip the certificate prompt at the end. Use npx facturas cert later to save the certificate.

Output files

File	Permissions	Contents
`arca-test.key` / `arca-production.key`	`0600`	RSA 2048 private key, PKCS#8 unencrypted
`arca-test.csr` / `arca-production.csr`	default	CSR for ARCA registration

If a .gitignore file exists in the target directory, init appends arca-*.key and arca-*.crt to it (once only) and tells you.

On Windows, 0600 permissions are not enforced by the OS. Store your key file outside your repository.

Clipboard behavior

In test (--env test), init copies the CSR to your clipboard before printing the instructions, so pasting it into the ARCA form requires no manual selection. It uses the first available tool: pbcopy, wl-copy, xclip, xsel, or clip — called directly, without a shell, with no extra installs. If none of these tools is available (headless server, SSH session), the CSR is printed inline in the instructions instead. In production (--env production), the CSR is not copied to the clipboard because ARCA expects a file upload, not a text paste.

Example

npx facturas init --cuit 20123456786 --env test

`facturas cert`

Saves the PEM certificate that ARCA issues after approving your CSR. This is the same step init offers at the end — cert exists for when you skipped it with Ctrl-C or --no-paste, or when you ran init in a non-interactive environment.

npx facturas cert --env test

The command prompts you to paste the full PEM block (from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----). It finishes automatically as soon as it sees the closing line. In scripts, pipe in the file instead:

npx facturas cert < arca-test.crt

Before writing, cert verifies two things and exits with code 1 if either check fails — without saving anything:

The certificate’s RSA modulus matches arca-<env>.key (same key pair)
The CUIT in the certificate’s serialNumber field matches your configured CUIT

If what you paste isn’t a valid PEM block, the command tells you and retries up to three times in a terminal. Non-interactively it exits with code 1 on the first failure.

Flags

Which key/certificate pair to use when both are present in the directory. Required when arca-test.key and arca-production.key both exist; the command exits with code 1 and asks you to specify.

Where to look for arca-<env>.key (and write arca-<env>.crt). Defaults to the current working directory.

Overwrite an existing arca-<env>.crt file.

Output file

File	Contents
`arca-test.crt` / `arca-production.crt`	PEM certificate from ARCA

Example

npx facturas cert --env test

`facturas check`

Tests each ARCA integration layer in sequence and stops at the first failure, reporting the exact diagnosis and the fix. After running init and cert, you need nothing else:

npx facturas check

✓ configuración          arca-test.crt en este directorio, CUIT 20123456786 del certificado
✓ certificado y clave    coinciden, vence 2027-09-05
✓ WSAA                   ticket obtenido
✓ WSFE                   servidor ok
✓ puntos de venta        1 informado
  3 (habilitado, CAE)

check also works with environment variables — the same ones your application will use:

export ARCA_TAX_ID=20123456786
export ARCA_ENVIRONMENT=test
export ARCA_CERTIFICATE_PEM="$(cat arca-test.crt)"
export ARCA_PRIVATE_KEY_PEM="$(cat arca-test.key)"
npx facturas check

Layers tested

#	Layer	What it tests
1	`configuración`	Resolves flags, env vars, and files; validates all values
2	`certificado y clave`	Parses both PEMs, verifies the key matches the certificate, reads expiry
3	`WSAA`	Logs in for the `wsfe` service; reuses a cached ticket if still valid
4	`WSFE`	Calls `getServerStatus()` then `getSalesPoints()`
5	`puntos de venta`	Lists enabled sales points; checks `--sales-point` if provided

Value resolution order

check and issue resolve configuration in this order — the first source that provides a value wins:

Priority	Source	Provides
1	Flags	`--tax-id`, `--env`, `--cert`, `--key`
2	Environment variables	`ARCA_TAX_ID`, `ARCA_ENVIRONMENT`, `ARCA_CERTIFICATE_PEM`, `ARCA_PRIVATE_KEY_PEM`
3	Files in the directory	`arca-<env>.crt` and `arca-<env>.key` (environment inferred from filename)

File discovery rules:

One complete pair → that pair is used; environment is inferred from the filename
Both pairs present → exits with code 1 and asks you to specify --env
Half a pair (key without certificate, or vice versa) → tells you which file is missing

Flags

Read the certificate PEM from a file instead of ARCA_CERTIFICATE_PEM.

Read the private key PEM from a file instead of ARCA_PRIVATE_KEY_PEM.

CUIT override. Validated with the same rules as init.

Environment override, or disambiguation when both pairs exist in the directory.

Directory to search for arca-<env>.crt and arca-<env>.key. Defaults to the current directory.

Verify a specific sales point. Must be an integer from 1 to 99999; any other value exits with code 2.

Skip the WSAA ticket cache entirely — request a new ticket and hold it in memory only. Use this when you want to force a fresh login.

Print a single JSON object instead of the human-readable output. Layers that weren’t reached are omitted.

WSAA ticket cache

The CLI caches WSAA tickets in <tmpdir>/facturas-cli (directory mode 0700, files mode 0600). ARCA rejects a second login while a ticket is still valid — up to 12 hours (coe.alreadyAuthenticated) — so the cache makes it safe to run check multiple times, or chain check with issue, without triggering that error. Pass --no-cache to request a fresh ticket that is never written to disk.

Warnings that don’t fail

Two conditions produce a warning but keep the exit code at 0:

A certificate expiring within 30 days
An empty sales point list in the test environment (ARCA often omits them in homologación even when they work; a --sales-point not found in the list is reported as 3 (no informado) and issue can still proceed)

In production, an empty sales point list is always a failure (exit code 1).

JSON output

{
  "ok": false,
  "environment": "test",
  "taxId": "20123456786",
  "layers": [
    { "name": "config", "ok": true, "detail": "ARCA_TAX_ID, ARCA_ENVIRONMENT=test" },
    { "name": "certificate", "ok": true, "detail": "coinciden, vence 2027-09-05", "expiresAt": "2027-09-05" },
    { "name": "wsaa", "ok": true, "detail": "ticket vigente" },
    {
      "name": "wsfe",
      "ok": false,
      "code": "ARCA_AUTHENTICATION_ERROR",
      "reason": "missing_relationship",
      "diagnosis": "El certificado no tiene la relación con Facturación Electrónica.",
      "fix": "Administrador de Relaciones → Nueva Relación → Webservices → Facturación Electrónica."
    }
  ],
  "salesPoints": [{ "number": 3, "blocked": false, "system": "CAE" }]
}

Example

npx facturas check --env test

Diagnostics reference

All check failures and fixes

Each named failure maps to exactly one row in this table.

Layer	Case	Diagnostic	Fix
configuración	No CUIT found anywhere	Falta el CUIT.	`export ARCA_TAX_ID=20123456786`
configuración	Invalid `ARCA_TAX_ID` or `--tax-id`	CUIT inválido: `<cuit>` tiene `<n>` dígitos y necesita 11. / …no pasa el dígito verificador.	Must be 11 digits; the last digit is a check digit. Hyphens are accepted.
configuración	Certificate has no CUIT field	El certificado no dice de qué CUIT es.	Pass `--tax-id 20123456786` or set `ARCA_TAX_ID`.
configuración	`ARCA_ENVIRONMENT` missing	Falta el entorno.	`export ARCA_ENVIRONMENT=test`
configuración	PEM file missing	Falta el certificado o la clave.	Save `arca-<env>.crt` and `arca-<env>.key` here, or pass `--cert`/`--key`, or set the `ARCA_*_PEM` variables.
configuración	Both environments present in directory	Están `arca-test.crt` y `arca-production.crt`…	Choose with `--env test` or `--env production`.
configuración	Key present, certificate missing	Está `arca-test.key` pero falta `arca-test.crt`.	Download the certificate from ARCA and save it as `arca-test.crt`.
configuración	Certificate present, key missing	Está `arca-test.crt` pero falta `arca-test.key`.	Place the key you used to generate the CSR here, or pass `--key`.
certificado y clave	Certificate is for a different CUIT	El certificado es del CUIT `<a>` y el configurado es `<b>`.	Use the certificate for that CUIT, or correct `--tax-id` / `ARCA_TAX_ID`.
certificado y clave	PEM does not parse	El archivo no es un PEM válido.	Check that you copied the full block, including BEGIN and END lines.
certificado y clave	Key doesn’t match certificate	La clave privada no corresponde a este certificado.	Use the key you generated the CSR with (`arca-<env>.key`).
certificado y clave	Certificate expired	El certificado venció el `<date>`.	Generate a new CSR with `npx facturas init` and renew in ARCA.
WSAA	`cms.cert.expired`	El certificado venció.	Same as above.
WSAA	`cms.cert.untrusted`, `cms.cert.invalid`	ARCA no reconoce este certificado en este entorno.	Test and production require separate certificates; check `ARCA_ENVIRONMENT`.
WSAA	`cms.bad`, `cms.sign.invalid`	La firma del pedido no es válida.	Key doesn’t match certificate, or the PEM is truncated.
WSAA	`coe.notAuthorized`	El certificado no está autorizado para `wsfe`.	In test: WSASS → Crear autorización a servicio. In production: Administrador de Relaciones.
WSAA	`coe.alreadyAuthenticated`	Ya hay un ticket vigente para este certificado.	Another process or machine holds the ticket (valid up to 12 hours). Wait, or run `check` from the same machine.
WSAA	`xml.generationTime.invalid`, `xml.expirationTime.*`	La hora de tu máquina difiere de la de ARCA.	Sync the system clock (NTP) and try again.
WSAA	Transport failure	No se pudo conectar con `<host>`.	Check network, proxy, or firewall. ARCA’s test environment is often down on weekends.
WSFE	`reason: missing_relationship`	El certificado no tiene la relación con Facturación Electrónica.	Administrador de Relaciones → Nueva Relación → Webservices → Facturación Electrónica.
WSFE	`reason: unauthorized_computer`	El certificado o computador no está autorizado.	Verify the alias is associated with the service in the correct environment.
WSFE	`reason: invalid_token`	El ticket fue rechazado.	Re-run `check`; if it persists, check the system clock.
WSFE	`reason: authentication_rejected`	ARCA denegó el acceso al servicio.	Check the environment and the certificate’s service relationship.
WSFE	Other SOAP fault	ARCA respondió con un error: `<message>`.	—
puntos de venta	`--sales-point` not in list	El punto de venta `<n>` no está habilitado para web services.	ARCA → Administración de Puntos de Venta y Domicilios → Nuevo → the web services system for your tax condition.
puntos de venta	Production returns no sales points	ARCA no informa ningún punto de venta para web services.	ARCA → Administración de Puntos de Venta y Domicilios → Nuevo → `RECE para aplicativo y Web Services` (responsable inscripto) or `Factura Electrónica – Monotributo – Web Services` (monotributo).
puntos de venta	Sales point is blocked	El punto de venta `<n>` está bloqueado.	Review the sales point status in ARCA.

Any error not listed here surfaces with the SDK’s safe message and stable error code. See the Errors reference for the full error hierarchy.

`facturas issue`

Issues one ARS 1 invoice in the homologación environment to verify that the full issuance circuit works end-to-end. The command refuses to run outside test — it will not issue in production. Before emitting, issue runs all five check layers. If any layer fails, it stops there and exits with code 1.

npx facturas issue --sales-point 3 --issuer monotributo

✓ Factura C emitida - 00003-00000007   CAE 74123456789012   Vto. CAE 2026-09-16   ARS 1,00

Esta es la llamada que hizo el CLI. Pegala en tu aplicación:

  const factura = await arca.issue({
    issuer: "monotributo",
    salesPoint: 3,
    to: { condition: "consumidor_final" },
    items: [{ amount: 100 }],
  });

After a successful issuance, the CLI prints the equivalent SDK call so you can paste it directly into your application code.

issue creates a real voucher in ARCA’s homologación environment. It does not use an idempotency key or store. For production use, always configure both — see the quick-start guide.

Flags

Accepts all check flags (--dir, --no-cache, --env, --cert, --key, --tax-id) plus:

required

Sales point number. Prompted interactively if not provided in a terminal.

The issuer’s tax condition. One of: monotributo, responsable_inscripto, exento, no_alcanzado. Prompted interactively if not provided in a terminal.

Print the result as JSON — same shape as the SDK’s issue() return value. On ARCA failure, prints an error object with the stable SDK error code.

Non-`authorized` outcomes

Result	Exit code	What the CLI shows
`rejected`	`1`	ARCA’s error messages, one per line
`indeterminate`	`1`	Reserved number + evidence, with a link to the recovery guidance
`conflict`	`1`	Conflicting voucher number + evidence

If ARCA fails after the layers pass (between number reservation and authorization), the CLI shows ✗ emisión with the SDK’s safe error message and exits with code 1. No raw traces or PEM contents are ever printed.

Example

npx facturas issue --sales-point 1 --env test

Get Started

Core Concepts

Guides

CLI

Reference

facturas CLI Commands: init, cert, check, and issue

`facturas init`

Flags

Output files

Clipboard behavior

Example

`facturas cert`

Flags

Output file

Example

`facturas check`

Layers tested

Value resolution order

Flags

WSAA ticket cache

Warnings that don’t fail

JSON output

Example

Diagnostics reference

`facturas issue`

Flags

Non-`authorized` outcomes

Example

​facturas init

​Flags

​Output files

​Clipboard behavior

​Example

​facturas cert

​Flags

​Output file

​Example

​facturas check

​Layers tested

​Value resolution order

​Flags

​WSAA ticket cache

​Warnings that don’t fail

​JSON output

​Example

​Diagnostics reference

​facturas issue

​Flags

​Non-authorized outcomes

​Example

`facturas init`

Flags

Output files

Clipboard behavior

Example

`facturas cert`

Flags

Output file

Example

`facturas check`

Layers tested

Value resolution order

Flags

WSAA ticket cache

Warnings that don’t fail

JSON output

Example

Diagnostics reference

`facturas issue`

Flags

Non-`authorized` outcomes

Example