> ## Documentation Index
> Fetch the complete documentation index at: https://facturas-sdk.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# facturas CLI: Set Up and Diagnose ARCA Credentials

> The facturas CLI generates private keys, CSRs, and test invoices, and runs layer-by-layer diagnostics — no installation required beyond Node.js 20+.

The `facturas` CLI handles the hardest part of issuing your first electronic invoice: ARCA's credential setup. It generates your private key and CSR, walks you through every ARCA registration step, tests each integration layer in order, and names exactly which one fails — all from a single `npx` command, with no extra installation required beyond Node.js 20 or later.

## Installation

You don't need to install anything. Run any command directly with `npx`:

```sh theme={null}
npx facturas <command>
```

If you prefer to have `facturas` available as a local binary, install it globally:

```sh theme={null}
npm install -g facturas
```

<Note>
  All four commands work identically whether you use `npx facturas` or a globally installed `facturas` binary. The examples throughout this section use `npx facturas`.
</Note>

## Commands

<CardGroup cols={2}>
  <Card title="facturas init" icon="key">
    Generate a private key and CSR formatted for ARCA registration. Copies the CSR to your clipboard automatically.
  </Card>

  <Card title="facturas cert" icon="certificate">
    Save the PEM certificate ARCA issues after approving your CSR. Validates the certificate matches your key before writing.
  </Card>

  <Card title="facturas check" icon="circle-check">
    Test each ARCA integration layer in sequence and report the first one that fails, with the exact diagnosis and fix.
  </Card>

  <Card title="facturas issue" icon="file-invoice">
    Issue a real ARS 1 test invoice in the homologación environment to confirm end-to-end issuance works.
  </Card>
</CardGroup>

## Getting help

Run `--help` (or `-h`) on any command to see its flags and examples:

```sh theme={null}
npx facturas --help
npx facturas init --help
npx facturas cert --help
npx facturas check --help
npx facturas issue --help
```

`--help` always exits with code `0` and never touches the network, even if the rest of the command line is invalid. `-v` is an alias for `--version`.

## What the CLI writes (and what it doesn't)

* `init` and `cert` write credential files to disk. Neither they nor `check` ever write to ARCA — they only read.
* `init` copies your CSR to the clipboard automatically in the `test` environment (using `pbcopy`, `wl-copy`, `xclip`, `xsel`, or `clip`, whichever your system provides) — no shell invocation, no extra installs. In `production`, ARCA expects a file upload, so the CSR is not copied.
* The only other thing the CLI writes is the **WSAA ticket cache**, stored in `<tmpdir>/facturas-cli` with the directory at mode `0700` and files at `0600`. ARCA rejects a second login while a ticket is still valid (up to 12 hours), so the cache lets you run `check` multiple times in sequence without triggering `coe.alreadyAuthenticated`. Use `--no-cache` to skip reading and writing entirely.
* `issue` **does** write to ARCA: it issues a real homologación voucher. It refuses to run outside the `test` environment.

<Tip>
  Run `npx facturas check` as the very first step whenever you're troubleshooting a credential or connection problem. It tests every layer — config, key/certificate, WSAA auth, WSFE connection, and sales point availability — and stops at the first failure with the exact fix.
</Tip>

## Exit codes

| Code | Meaning                                                                                                      |
| ---- | ------------------------------------------------------------------------------------------------------------ |
| `0`  | Everything succeeded. Warnings do not change this code.                                                      |
| `1`  | A layer failed, or the voucher was not authorized.                                                           |
| `2`  | Usage error: unknown command, unknown flag, or a required value is missing (when running non-interactively). |

## Color output

The CLI uses ANSI color only when writing to a terminal. Turn it off with `--no-color` or the `NO_COLOR` environment variable. Force color on in non-TTY environments with `FORCE_COLOR` (`FORCE_COLOR=0` disables it). The text content is identical with or without color — only the escape sequences differ.

***

For the full flag reference for each command, see [Commands](./commands).