@beel_es/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BeeL (beel.es)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @beel_es/cli
+
+Agent-first CLI for the [BeeL](https://beel.es) 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.
+
+```bash
+npx @beel_es/cli --help
+```
+
+No install, no brew. Node 20+.
+
+## Auth
+
+```bash
+# 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
+
+```bash
+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).
+
+### Generic escape hatch
+
+Any endpoint, even ones this CLI version doesn't know yet:
+
+```bash
+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](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
+
+```bash
+npm install
+npm run dev -- invoices --help   # run from source
+npm test                         # vitest
+npm run build                    # single-file bundle in dist/ (zero runtime deps)
+```