CLI: BillOS from the terminal
npm install -g billos # or run any command as: npx billos …
billos sandbox # a sandbox key: prints a link, you approve in the browser, the key is stored
billos login # or sign in with a developer accountbillos sandbox calls POST /sandboxes (section 10): it prints a link and a code, you approve in the console, and it stores the sandbox key it then collects. Without a terminal to wait in (--json, or output that is not a TTY) it prints the link and exits, and running it again after the approval collects the key, which is how an agent drives it. 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 sandbox [--name …] | Ask for a sandbox key: a link a person approves in the console, then the key, saved for the CLI. --no-wait (and --json) prints the link and exits; run it again to collect. --no-save prints the key and stores nothing; a stored key is replaced only with --force |
billos seed | Fill a sandbox with the demo business (section 10) |
billos init [--dir . --agents claude,cursor,codex] | Prepare a repository for coding agents: the MCP entry for Claude Code, Cursor and Codex (each reads BILLOS_API_KEY from the environment, so every file is safe to commit), a short AGENTS.md block and a Cursor rule with the rules an integration gets wrong, and BILLOS_API_KEY= in .env.example. Nothing a person wrote is overwritten |
billos listen --forward-to <url> | Forward events to a local server, signed like a real delivery, with no tunnel: it reads the event log and POSTs each new event to the URL. Prints a signing secret at start (--secret to give your own); --events, --business, --interval narrow and pace it |
billos whoami | Which key is active, and how many businesses it holds |
billos env | The stored key as one line, BILLOS_API_KEY=…, for a project's .env (billos env >> .env). The one command that prints the whole key |
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. --dry-run validates and shows what would be issued, and issues nothing; --idempotency-key order-1001 makes a retry safe. --currency USD makes the amount dollars (the books still record shekels, at --rate or the Bank of Israel rate of the day); --lang en prints it in English; --zero-vat states מע"מ בשיעור אפס (סעיף 30) on an invoice. On a receipt, --settles <id,id> names the invoices it pays (printed as "על חשבון"); on an invoice, --due 2026-10-01 prints the payment term and is what ages it in billos receivables |
billos expenses [--status --from --to] | List expenses |
billos expense --supplier "שם" --amount 118 [--vat 18] | Record an expense |
billos cancel <documentId> [--amount 118 --reason "…" --refund] | Issue the document's credit note: the only lawful way to undo an issued document. --amount credits PART of it (הוראה 23א, so --reason is then required); --refund on a חשבונית מס-קבלה also issues the negative receipt for money handed back |
billos receivables [--party --as-of] | Who owes you, aged, with each document's id |
billos vat [--period 2026-08 --months 2 --file PCN874.TXT] | The periodic VAT figures, and the PCN874 file on disk with --file |
billos archive [--source --q --from --to] | The documents filed from the previous software (importing is an API job) |
billos customers | The business's customers |
billos access [invite --email … --role …|revoke <id>] | Who else can see this business, and the way in and out. --role accountant|bookkeeper|viewer, or --scopes documents:read,export for an explicit list (section 4, Shared access) |
billos connections [revoke <id>] | The apps the owner connected to this business, and disconnecting one |
billos apps [create|update|rotate|delete] | Your Connect apps (section 15). create --name … --redirect … --scopes … prints the client_secret once and a ready authorize URL; rotate replaces the secret; delete disconnects every business under the app |
billos usage | Your API traffic and response times 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; an error is then the API's error body on stderr, with exit code 1. Without it, a refusal prints its hint and doc_url under the message.
Output is English, and Hebrew when the machine's locale is Hebrew; BILLOS_LANG=he|en or --ui-lang overrides it. That is the CLI's own language only: the language a document prints in is --lang on billos invoice, a separate flag on purpose. --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.