@beel_es/cli

@beel_es/cli

Agent-first CLI for the BeeL invoicing API. Every command is derived at startup from the embedded OpenAPI spec — when the API gains an endpoint, the next CLI release gains the command, with zero hand-written wrappers.

npx @beel_es/cli --help

No install, no brew. Node 20+.

Auth

# Option A (recommended for agents/CI): env var
export BEEL_API_KEY=beel_sk_test_...

# Option B: store keys in ~/.config/beel/config.json (chmod 600)
npx @beel_es/cli login --api-key beel_sk_test_...
npx @beel_es/cli login --api-key beel_sk_live_...   # both can coexist

The key prefix decides the slot: beel_sk_test_* → sandbox, beel_sk_live_* → production.

Sandbox is the default. Every command uses the test key unless you pass --live. A live key in BEEL_API_KEY without --live is an error, not a silent upgrade — production access is always explicit.

Usage

npx @beel_es/cli invoices list --status PAID --limit 5
npx @beel_es/cli invoices get <invoice_id>
npx @beel_es/cli invoices create --data @invoice.json
npx @beel_es/cli invoices issue <invoice_id> --wait-for-pdf
npx @beel_es/cli customers create --data '{"fiscal_name":"ACME SL", ...}'
npx @beel_es/cli nif validate --data '{"nif":"B12345678"}'
npx @beel_es/cli invoices export-excel --output invoices.xlsx
npx @beel_es/cli --live invoices list          # production

--data accepts inline JSON, @file.json, or - for stdin. Binary responses (PDF, ZIP, Excel) require --output <path>.

Discover everything with --help at any level: beel --help, beel invoices --help, beel invoices list --help (flags, enums and defaults come from the API spec).

Docs search (no API key needed)

Search docs.beel.es locally — fetches llms-full.txt once (cached 15 min) and prints only the matching sections. An agent gets the relevant ~2KB instead of the full 660KB docs:

npx @beel_es/cli docs list                       # all pages (JSON)
npx @beel_es/cli docs search idempotency key     # top matching sections (markdown)
npx @beel_es/cli docs search rate limit --limit 5
npx @beel_es/cli docs get glossary               # one full page

Generic escape hatch

Any endpoint, even ones this CLI version doesn't know yet:

npx @beel_es/cli request GET /v1/invoices --query status=PAID --query limit=5
npx @beel_es/cli request POST /v1/customers --data @customer.json

Output contract (for agents)

• stdout: response JSON, pretty-printed. Nothing else.
• stderr: errors as JSON: {"error": {"code", "message", "status", "details", "request_id"}}.
• Exit codes: 0 ok · 1 unexpected · 2 usage/config · 3 auth (401/403) · 4 not found · 5 validation (400/409/422) · 6 rate limit (429) · 7 server (5xx).

POST requests get an automatic Idempotency-Key. BEEL_BASE_URL overrides the API host; BEEL_CONFIG_DIR overrides the config location.

How it stays in sync with the API

The OpenAPI spec ships inside the package and the command tree is interpreted from it at startup (src/runtime.ts). When the backend publishes a spec change, a repository_dispatch syncs openapi/public-api.yaml, CI rebuilds, and a patch release is published. Updating the CLI = npx picking the new version.

Development

npm install
npm run dev -- invoices --help   # run from source
npm test                         # vitest
npm run build                    # single-file bundle in dist/ (zero runtime deps)