CLI

The BeeL CLI lets you operate the API from the terminal: create and issue invoices, manage customers and products, validate NIFs, export data — without writing code. It is agent-first by design: JSON output for data commands, semantic exit codes, and sandbox by default, so both humans and AI assistants can use it safely.

Commands are derived from the API spec bundled with the installed CLI version, so each release exposes the API surface as of that version — new endpoints become new commands when you update the CLI. For an endpoint the installed version doesn't know yet, use the generic escape hatch.

Installation

npm install -g @beel_es/cli
beel --help

npx @beel_es/cli --help

Authentication

# 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)
beel login --api-key beel_sk_test_...
beel login --api-key beel_sk_live_...   # both can coexist

Get your keys at Settings > API Keys — each environment has its own, separate key. The CLI files each key into its slot by prefix: beel_sk_test_* → sandbox, beel_sk_live_* → production.

Check what is configured at any time:

beel config   # shows config path, base URL and which keys are stored (masked)

Common recipes

Commands follow the beel <resource> <action> pattern. These are everyday examples; the full, always-up-to-date list comes from beel commands (see below).

# Invoices
beel invoices list --status PAID --limit 5        # filter + paginate
beel invoices get <invoice_id>
beel invoices create --data @invoice.json         # create a draft
beel invoices issue <invoice_id> --wait-for-pdf   # emit + wait for the PDF
beel invoices mark-paid <invoice_id>              # body optional
beel invoices create-corrective <invoice_id> --data @rectificativa.json
beel invoices generate-pdf <invoice_id>          # returns the PDF download URL
beel invoices export-excel --data '{}' --output invoices.xlsx

# Customers & products
beel customers list --search "ACME"
beel customers create --data @customer.json
beel products search --q "consultoría"
beel products delete <product_id>

# Configuration, series & NIF
beel configuration list-series
beel configuration set-default-series <series_id>
beel configuration get-veri-factu                 # VeriFactu status
beel nif validate --data '{"nif":"B12345678"}'    # checks the AEAT census

Discovering commands

The CLI is agent-first: every command is derived from the API spec, so an assistant can discover the whole surface in one call instead of scraping help text.

beel commands            # full command index as JSON — { command, signature, description, method, path }
beel commands --markdown # the same grouped by resource as markdown tables

beel commands reflects the spec bundled with the installed CLI version — not the live API — so update the CLI to pick up newly added endpoints (or use the escape hatch meanwhile). There's no hand-maintained list to fall out of date. For details of a single command — flags, enums, defaults and body fields, all from the spec — use --help at any level:

beel --help
beel invoices --help
beel invoices create --help

For commands that take a --data body, --help also lists the top-level body fields (name, type, whether they're required, and any enums), so you know what to send without leaving the terminal:

$ beel invoices create --help
...
Body fields (--data JSON), * = required:
  * lines        object[]
  * recipient    object
  * type         string (STANDARD|CORRECTIVE|SIMPLIFIED)
    notes        string
    series_id    string  Invoicing series ID (if not specified, uses default)
Full schema (nested fields, formats): beel docs search invoices

• --data accepts inline JSON, @file.json, or - for stdin
• Binary responses (PDF, ZIP, Excel) require --output <path>
• POST requests get an automatic Idempotency-Key

Searching the docs

The CLI can search this documentation locally — useful for AI agents that want the relevant section without fetching whole pages. It downloads the machine-readable docs once (cached 15 minutes) and filters on your machine; search terms never leave your computer. No API key needed.

beel docs list                    # all documentation pages (JSON)
beel docs search idempotency key  # prints only the matching sections
beel docs get glossary            # prints a full page as markdown

Generic escape hatch

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

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

Output contract

Built for scripting and AI agents:

• stdout: for API/data commands, the response JSON pretty-printed — pipe straight into jq. Two helpers print human-readable markdown instead: docs (list/search/get) and commands --markdown (plain commands is JSON).
• stderr: errors as JSON: {"error": {"code", "message", "status", "details", "request_id"}}

BEEL_BASE_URL overrides the API host; BEEL_CONFIG_DIR overrides the config location.

Further reading