# CLI: BillOS from the terminal

```bash
npm install -g billos
billos login
```

`billos login` prints a short code and opens the console; you approve the code there with your signed-in developer account, and the CLI receives a **freshly-minted key of its own** over a private device code. The key never passes through the browser, and it is stored at `~/.config/billos/config.json` with `0600` permissions. Already hold a key? `billos login --key bk_live_...` skips the pairing.

| Command | |
|---|---|
| `billos whoami` | Which key is active, and how many businesses it holds |
| `billos businesses` | The businesses on the key, with their standing |
| `billos use <businessId>` | Set the default business for every later command |
| `billos docs [--status --from --to --take]` | List documents |
| `billos invoice --customer "שם" --amount 350` | Issue a document (`--type receipt\|invoice\|invoice-receipt`, `--desc`, `--method`, `--phone`) and print the customer's link |
| `billos expenses [--status --from --to]` | List expenses |
| `billos expense --supplier "שם" --amount 118 [--vat 18]` | Record an expense |
| `billos cancel <documentId> [--reason "…"]` | Issue the document's credit note: the only lawful way to undo an issued document |
| `billos customers` | The business's customers |
| `billos usage` | Your API traffic over the last 30 days |
| `billos logout` | Delete the local key (revoking it is a console action) |

Add **`--json`** to any command and it prints the raw API shape and nothing else, which is the mode to pipe into `jq` or a script. `--business <id>` acts on one business without changing your default.

**Amounts on the CLI are shekels**, not agorot: `--amount 350.50` is ₪350.50. It is the one surface where people type the number themselves, so the CLI converts at the edge; every API payload underneath is still integer agorot.

`BILLOS_API_KEY` overrides the stored key and `BILLOS_API_ORIGIN` the host, which is how the CLI runs in CI without a login: mint a key for the pipeline, revoke it when the pipeline changes hands.