bookrail

The Bookrail command line interface: booking infrastructure as code, and every operation of the API, designed so a person and a coding agent can use the same tool.

• Install nothing: npx bookrail <command>.
• Three runtime dependencies, none of which has dependencies of its own: 6.6 MB and 4 packages installed.
• --json on every command, printing one envelope. Exit codes 0 success, 1 user or configuration, 2 authentication, 3 network or service, 4 conflict.
• Test is the default environment. A sk_live_ key used without --live is refused before any request leaves the process.

npx bookrail login                       # store a sk_test_ key, mode 600
npx bookrail init --template padel       # write bookrail.config.ts
npx bookrail push --dry-run              # see the plan
npx bookrail push                        # apply it
npx bookrail availability --service svc_... --from 2026-09-14T00:00:00+02:00 --to 2026-09-15T00:00:00+02:00
npx bookrail bookings create --service svc_... --start 2026-09-14T18:00:00+02:00 --customer-email [email protected]

What it can do

| Group | Commands | | --- | --- | | Credentials | login, logout, whoami, env, version, doctor | | Configuration as code | init (nine verticals), push, pull, diff | | Objects | locations, resources, resource_groups, schedules, services, policies, customers | | Operating | availability (with next, check, --explain), holds, bookings (create, get, list, confirm, cancel, reschedule, check-in, no-show, complete) | | Events | webhooks (including listen), events list --follow | | Offline | schema, examples, docs | | Agents | mcp install --client claude-code \| cursor \| vscode \| windsurf \| generic |

bookrail --help and bookrail <command> --help are the reference, and the site publishes exactly that output at bookrail.dev/docs/cli.

Configuration as code

bookrail.config.ts describes locations, schedules, resources, groups, policies and services. push matches objects by metadata.config_id, never by name, so a second push updates instead of duplicating, and an object with no config_id is reported as unmanaged and left alone. Deletions need --yes. --adopt kind:config_id=remote_id takes over one existing object, explicitly.

Where the key comes from

1. BOOKRAIL_SECRET_KEY in the environment, if set.
2. ~/.config/bookrail/credentials.json (or $XDG_CONFIG_HOME/bookrail/credentials.json), written by bookrail login with mode 600.

The key is never printed. whoami and env show it masked.

Output

{ "ok": true, "environment": "test", "data": {}, "next_steps": ["..."] }

{ "ok": false, "environment": "test",
  "error": { "code": "...", "message": "...", "param": "...", "doc_url": "...", "fix": "..." } }

fix is an instruction, not a diagnosis. Colour and decoration are off whenever stdout is not a terminal, and always off with --json.

Documentation

• Quickstart, timed against the production API.
• CLI basics and the full CLI reference.
• Coding agents and For AI agents.

Status

Early access. The API is live at https://api.bookrail.dev, a test key is self service (npx bookrail signup, or bookrail.dev/signup) while a live key still comes from a person ([email protected]), and this package is on npm as bookrail, Apache 2.0, with its source in github.com/bookrail-dev/bookrail under packages/cli. logs, requests, keys, projects, dev, migrate and upgrade answer not_yet_available, because there is no endpoint behind them.

Licence

Apache-2.0.