NewProvince is only required for addresses in Spain
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog

CLI 0.3.0: commands follow the routes under the NIF

CLI 0.3.0 calls only the routes that name the company, so most commands change name: beel companies list-invoices <company_id> is now beel invoices list.

ChangelogBreaking

Version 0.3.0 of the CLI builds its commands from the routes under /v1/companies/{company_id} and /v1/accounts/{account_id} only. The flat routes that 0.2.x called stop answering on 2026-12-09, so the old commands had to go. 179 of the 217 commands in 0.2.2 change name, arguments or body.

npx @beel_es/cli always runs the latest version, so a script that calls it without a version runs 0.3.0 from its next run. Update the command names, or pin npx @beel_es/cli@0.2.2 while you do; 0.2.2 keeps working until the flat routes retire. If you type a 0.2.x name, 0.3.0 exits with code 2 and its error message gives the new name.

What else changed

  • The company comes from --company, BEEL_COMPANY_ID or your account. With one company the CLI finds it by itself, which needs the companies:list scope and one or two extra requests. With several, it exits with code 2 and lists them. Account-level commands take --account / BEEL_ACCOUNT_ID.
  • Status changes are one command: invoices mark-paid becomes invoices set-status <invoice_id> --status PAID. update becomes patch, which leaves the fields you leave out untouched.
  • Shorter action names: companies get-by-id is companies get, webhooks list-subscriptions is webhooks list, me get-my-identity is me get.
  • Body fields as flags: string, number and boolean fields take a flag named after the API field, checked against its enum. --data still takes the full body.
  • Compact JSON output: one line on stdout; --pretty indents it.
  • Payment-event commands take a connection ID from beel payment-connections list, not the provider name.

Where to go next

Upgrading from 0.2.x (every renamed command)Arguments, flags and --dataWhich company a command acts onThe deprecated flat routes now retire on 9 December

A new series needs its document type, and what else changes in this release

A new series needs `document_type`, several rejections now carry a specific code or status, and an issued invoice's PDF never changes. Plus behaviour changes.

Webhook retries now span about 3 days

A failed webhook delivery is now retried 7 times over about 3 days instead of for about a minute, so a short outage of your endpoint no longer loses events.