CLI
Every block on this page is the output of --help of the compiled CLI, captured at build
time. If a flag is here, this build has it.
Install nothing: npx bookrail <command>. Every command takes --json and prints
{ ok, environment, data, error?, next_steps? }. The default environment is test.
Usage: bookrail [options] [command]
Bookrail: booking infrastructure as code.
Describe locations, schedules, resources, groups, policies and services inbookrail.config.ts, then push them. Every command takes --json and prints{ ok, environment, data, error?, next_steps? }.
Exit codes: 0 success, 1 user or config error, 2 authentication, 3 network orservice, 4 conflict.
Options: -V, --version Print the CLI version and exit. --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. Implied when stdout is not a terminal. --api-url <url> Base URL of the API. Defaults to BOOKRAIL_API_URL, then the stored one. --timeout <seconds> Per-request timeout. Default 30. -h, --help display help for command
Commands: login [options] Store an API key for its environment. logout [options] Forget the stored key for this environment. whoami [options] Show which key, environment and API this invocation would use. version [options] Print the CLI version, the API version it asks for, and the Node version. env [options] Print the environment variables to set for this environment. init [options] Write bookrail.config.ts (and .env.example) from a vertical template. push [options] Make the project match bookrail.config.ts. pull [options] Write the current project out as a bookrail.config.ts. diff [options] Show what push would change, without changing anything. locations [options] Create, read, update and delete locations. resources [options] Create, read, update and delete resources. resource_groups [options] Create, read, update and delete resource_groups. schedules [options] Create, read, update and delete schedules. services [options] Create, read, update and delete services. policies [options] Create, read, update and delete policies. customers [options] Create, read, update and delete customers. availability [options] Ask what is bookable, and why an instant is not. holds [options] Take capacity for a few minutes, or give it back. bookings [options] Create, read and move bookings through their life cycle. webhooks [options] Register endpoints, inspect deliveries, and watch events arrive. events [options] Read the event log, and follow it. doctor [options] Check credentials, permissions, environment, reachability, version and config. schema [options] [entity] Print the JSON Schema of the configuration, or of one of its collections. examples [options] [vertical] Print a complete, working model of a vertical and the calls that follow it. docs [options] [topic] Print a page of the documentation bundled with this CLI, offline. mcp [options] Configure the Bookrail MCP server in a coding agent. logs [options] (not in this build) Request log, with --follow. requests [options] (not in this build) get REQUEST_ID. keys [options] (not in this build) list | create | revoke. projects [options] (not in this build) list | create | use. dev [options] (not in this build) Run the engine locally with a mini dashboard. migrate [options] (not in this build) Import from csv, json, Calendly, Acuity. upgrade [options] (not in this build) Update the CLI in place. help [command] display help for commandbookrail login
Section titled “bookrail login”Usage: bookrail login [options]
Store an API key for its environment.
Options: --token <key> The secret key, or `-` to read it from standard input. Without it, and with a terminal, you are asked. --api-url <url> Store a non-default API base URL alongside the key. --skip-verification Do not call the API to check the key before storing it. --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Needs: a sk_test_ or sk_live_ secret key, from --token or from the terminal.Returns: the environment, the masked key, and where it was stored (mode 600).Next: `bookrail whoami`, then `bookrail init`.bookrail logout
Section titled “bookrail logout”Usage: bookrail logout [options]
Forget the stored key for this environment.
Options: --all Remove the whole credentials file, both environments. --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Returns: which key was removed and from which file.bookrail whoami
Section titled “bookrail whoami”Usage: bookrail whoami [options]
Show which key, environment and API this invocation would use.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Needs: a stored key or BOOKRAIL_SECRET_KEY.Returns: environment, masked key, key source, API URL and version.Fails with exit 2 when the key is missing, wrong or refused.bookrail env
Section titled “bookrail env”Usage: bookrail env [options]
Print the environment variables to set for this environment.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
The key is masked: read the real one from the credentials file.bookrail version
Section titled “bookrail version”Usage: bookrail version [options]
Print the CLI version, the API version it asks for, and the Node version.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for commandbookrail init
Section titled “bookrail init”Usage: bookrail init [options]
Write bookrail.config.ts (and .env.example) from a vertical template.
Options: --template <name> Vertical to start from. Default: empty. --framework <name> Also write a minimal client for this framework. --dir <path> Directory to write into. Default: the working directory. --project <name> Override the `project` field of the template. --force Overwrite files that already exist. --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Templates: salon, padel, gym, rental, restaurant, clinic, coworking, tours, tutoring, empty.Frameworks: nextjs, nuxt, sveltekit, laravel, rails, django, expo, none (non-none also writes bookrail.ts, a minimal client).Needs: nothing. It never contacts the API and never prompts.Returns: the files written.Next: `bookrail push --dry-run`.bookrail push
Section titled “bookrail push”Usage: bookrail push [options]
Make the project match bookrail.config.ts.
Options: --config <path> Path to the configuration file. --dry-run Compute and print the plan; change nothing. --yes Accept the deletions in the plan. --adopt <kind:config_id=remote_id> Take over an existing object under this logical id. Repeatable. (default: []) --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Needs: a key, and a bookrail.config.* in the working directory (or --config).Returns: the plan (create / update / delete / unchanged) and what was applied.Objects with no metadata.config_id are never touched; they are listed as unmanaged.Deletions require --yes. Runs against the test environment unless --live is given. The environment is in every output.--adopt kind:config_id=remote_id makes one existing object managed, by stampingmetadata.config_id on it. Never by name: names are not unique, and adopting the wrong"Court 1" would write one court's hours onto another. Repeatable.Next: run `bookrail diff`. It must report no differences.bookrail pull
Section titled “bookrail pull”Usage: bookrail pull [options]
Write the current project out as a bookrail.config.ts.
Options: --out <path> Where to write. Default: bookrail.config.ts. --stdout Print the file instead of writing it. --force Overwrite an existing file. --adopt Stamp metadata.config_id on the unmanaged objects before writing. --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Needs: a key.Returns: the file written, and the objects that carry no metadata.config_id.Refuses to overwrite an existing file without --force.--adopt also STAMPS metadata.config_id on every unmanaged object, with the logical idthis command derived from its name, so the file it writes is one push will reconcileinstead of duplicating. It is the only way this command writes anything.bookrail diff
Section titled “bookrail diff”Usage: bookrail diff [options]
Show what push would change, without changing anything.
Options: --config <path> Path to the configuration file. --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Needs: a key and a configuration file.Returns: `has_changes` plus the same plan `push --dry-run` prints.Exit code stays 0 whether or not there are differences: branch on `has_changes`.bookrail locations
Section titled “bookrail locations”Usage: bookrail locations [options] [command]
Create, read, update and delete locations.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Commands: list [options] List locations, one cursor page at a time. get [options] <id> Read one location by its prefixed id. create [options] Create one location. update [options] <id> Update one location. Sub-lists are replaced wholesale. delete [options] <id> Delete one location. Requires --yes. help [command] display help for command
Sub-commands: list, get <id>, create, update <id>, delete <id>.Nothing is expandable on this collection.Bodies come from --data '{"..."}', --file body.json (or --file - for stdin), or --set key=value.Runs against the test environment unless --live is given. The environment is in every output.bookrail resources
Section titled “bookrail resources”Usage: bookrail resources [options] [command]
Create, read, update and delete resources.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Commands: list [options] List resources, one cursor page at a time. get [options] <id> Read one resource by its prefixed id. create [options] Create one resource. update [options] <id> Update one resource. Sub-lists are replaced wholesale. delete [options] <id> Delete one resource. Requires --yes. blocks [options] <id> List the periods this resource is closed for. help [command] display help for command
Sub-commands: list, get <id>, create, update <id>, delete <id>.Expandable: schedule (repeat --expand).Bodies come from --data '{"..."}', --file body.json (or --file - for stdin), or --set key=value.Runs against the test environment unless --live is given. The environment is in every output.bookrail resource_groups
Section titled “bookrail resource_groups”Usage: bookrail resource_groups [options] [command]
Create, read, update and delete resource_groups.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Commands: list [options] List resource_groups, one cursor page at a time. get [options] <id> Read one resource group by its prefixed id. create [options] Create one resource group. update [options] <id> Update one resource group. Sub-lists are replaced wholesale. delete [options] <id> Delete one resource group. Requires --yes. help [command] display help for command
Sub-commands: list, get <id>, create, update <id>, delete <id>.Expandable: resources (repeat --expand).Bodies come from --data '{"..."}', --file body.json (or --file - for stdin), or --set key=value.Runs against the test environment unless --live is given. The environment is in every output.bookrail schedules
Section titled “bookrail schedules”Usage: bookrail schedules [options] [command]
Create, read, update and delete schedules.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Commands: list [options] List schedules, one cursor page at a time. get [options] <id> Read one schedule by its prefixed id. create [options] Create one schedule. update [options] <id> Update one schedule. Sub-lists are replaced wholesale. delete [options] <id> Delete one schedule. Requires --yes. help [command] display help for command
Sub-commands: list, get <id>, create, update <id>, delete <id>.Nothing is expandable on this collection.Bodies come from --data '{"..."}', --file body.json (or --file - for stdin), or --set key=value.Runs against the test environment unless --live is given. The environment is in every output.bookrail services
Section titled “bookrail services”Usage: bookrail services [options] [command]
Create, read, update and delete services.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Commands: list [options] List services, one cursor page at a time. get [options] <id> Read one service by its prefixed id. create [options] Create one service. update [options] <id> Update one service. Sub-lists are replaced wholesale. delete [options] <id> Delete one service. Requires --yes. help [command] display help for command
Sub-commands: list, get <id>, create, update <id>, delete <id>.Expandable: requirements (repeat --expand).Bodies come from --data '{"..."}', --file body.json (or --file - for stdin), or --set key=value.Runs against the test environment unless --live is given. The environment is in every output.bookrail policies
Section titled “bookrail policies”Usage: bookrail policies [options] [command]
Create, read, update and delete policies.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Commands: list [options] List policies, one cursor page at a time. get [options] <id> Read one policy by its prefixed id. create [options] Create one policy. update [options] <id> Update one policy. Sub-lists are replaced wholesale. delete [options] <id> Delete one policy. Requires --yes. help [command] display help for command
Sub-commands: list, get <id>, create, update <id>, delete <id>.Nothing is expandable on this collection.Bodies come from --data '{"..."}', --file body.json (or --file - for stdin), or --set key=value.Runs against the test environment unless --live is given. The environment is in every output.bookrail customers
Section titled “bookrail customers”Usage: bookrail customers [options] [command]
Create, read, update and delete customers.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Commands: list [options] List customers, one cursor page at a time. get [options] <id> Read one customer by its prefixed id. create [options] Create one customer. update [options] <id> Update one customer. Sub-lists are replaced wholesale. delete [options] <id> Delete one customer. Requires --yes. help [command] display help for command
Sub-commands: list, get <id>, create, update <id>, delete <id>.Nothing is expandable on this collection.Bodies come from --data '{"..."}', --file body.json (or --file - for stdin), or --set key=value.Runs against the test environment unless --live is given. The environment is in every output.bookrail availability
Section titled “bookrail availability”Usage: bookrail availability [options] [command]
Ask what is bookable, and why an instant is not.
Options: --service <id> The service to ask about. Required. --from <instant> Start of the window, e.g. 2026-09-08T00:00:00+02:00. Required. --to <instant> End of the window, exclusive. Required. --tz <timezone> Time zone of the answer. Presentation only: it never moves the grid. --quantity <n> Units per booking. Default: the service capacity_per_booking. --resource <id> Restrict the candidate resources. Repeatable. (default: []) --customer <id> Apply this customer’s limits. --granularity <kind> slots (default) or ranges, for free-duration services. --explain Say why every rejected instant was rejected. Max 7 days. --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Commands: next [options] The first bookable instant, searched up to 90 days ahead. check [options] Is this precise instant bookable, and if not, why.
Needs: --service, --from and --to, each an ISO 8601 instant with an explicit offset.Returns: the slots (or ranges), with capacity, price and the concrete resource options.--explain adds one row per rejected instant and reason. It is capped at 7 days.A window may not span more than 90 days. Runs against the test environment unless --live is given. The environment is in every output.Next: `bookrail holds create` on a start you got here, or `bookrail bookings create`.Sub-commands: next (the first bookable instant), check (one precise instant).bookrail holds
Section titled “bookrail holds”Usage: bookrail holds [options] [command]
Take capacity for a few minutes, or give it back.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Commands: create [options] Hold capacity on one slot. get [options] <id> Read one hold: is it still alive, until when, and what it became. release [options] <id> Give the capacity back before the hold expires. help [command] display help for command
Sub-commands: create, get <id>, release <id>.A hold expires by itself (policy.hold_duration_seconds, 10 minutes by default, 30 max).Runs against the test environment unless --live is given. The environment is in every output.bookrail bookings
Section titled “bookrail bookings”Usage: bookrail bookings [options] [command]
Create, read and move bookings through their life cycle.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Commands: create [options] Book one slot, or convert a hold. get [options] <id> Read one booking, with its allocations. list [options] List bookings, filtered and paginated. confirm [options] <id> Move the booking to its confirm state. check-in [options] <id> Move the booking to its check_in state. complete [options] <id> Move the booking to its complete state. no-show [options] <id> Move the booking to its no_show state. cancel [options] <id> Cancel a booking and compute the refund its policy promises. reschedule [options] <id> Move a booking to another instant, atomically. help [command] display help for command
Sub-commands: create, get <id>, list, confirm <id>, cancel <id>, reschedule <id>,check-in <id>, no-show <id>, complete <id>.There is no `update`: a booking changes by an action, never by a field edit.Expandable on get and list: customer, allocations.resource. Runs against the test environment unless --live is given. The environment is in every output.bookrail webhooks
Section titled “bookrail webhooks”Usage: bookrail webhooks [options] [command]
Register endpoints, inspect deliveries, and watch events arrive.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Commands: list [options] List the endpoints of this project and environment. get [options] <id> Read one endpoint. The secret is never in the answer. create [options] Register an endpoint and print its signing secret, once. update [options] <id> Change the URL, the subscriptions, or the status of an endpoint. delete [options] <id> Delete an endpoint and its whole delivery log. Requires --yes. test [options] <id> Send a synthetic webhook.test delivery, now, and report what came back. deliveries [options] <id> The delivery log of one endpoint, newest first. retry [options] <id> <delivery-id> Queue a delivery again, with a fresh retry ladder. listen [options] Receive deliveries on a local port, or follow the event log. help [command] display help for command
Sub-commands: list, get <id>, create, update <id>, delete <id>, test <id>,deliveries <id>, retry <id> <delivery-id>, listen.The signing secret is shown once, by create, and by nothing else ever. Runs against the test environment unless --live is given. The environment is in every output.bookrail events
Section titled “bookrail events”Usage: bookrail events [options] [command]
Read the event log, and follow it.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Commands: list [options] List events, oldest first, and optionally keep following. get [options] <id> Read one event by id. help [command] display help for command
Sub-commands: list, get <id>.The log is read-only and ordered by (txid, seq); the public cursor is an event id.A row becomes visible only once the transaction that wrote it has finished, which iswhat makes the cursor safe: nothing ever appears below a position already passed.Runs against the test environment unless --live is given. The environment is in every output.bookrail doctor
Section titled “bookrail doctor”Usage: bookrail doctor [options]
Check credentials, permissions, environment, reachability, version and config.
Options: --config <path> Configuration file to validate. --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Needs: nothing. Every problem is a check, never an exception.Returns: one { name, status, message, fix } per check, and a summary.Exits 1 when at least one check failed, 0 otherwise.bookrail schema
Section titled “bookrail schema”Usage: bookrail schema [options] [entity]
Print the JSON Schema of the configuration, or of one of its collections.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Names: config, locations, schedules, resources, resourceGroups, policies, services. Without one, the list is printed.bookrail examples
Section titled “bookrail examples”Usage: bookrail examples [options] [vertical]
Print a complete, working model of a vertical and the calls that follow it.
Options: --framework <name> Show the calls in TypeScript instead of curl. --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Verticals: salon, padel, gym, rental, restaurant, clinic, coworking, tours, tutoring, empty.bookrail docs
Section titled “bookrail docs”Usage: bookrail docs [options] [topic]
Print a page of the documentation bundled with this CLI, offline.
Options: --markdown Print raw markdown. This is also the default. --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for commandbookrail mcp
Section titled “bookrail mcp”Usage: bookrail mcp [options] [command]
Configure the Bookrail MCP server in a coding agent.
Options: --json Print the structured envelope instead of a human table. --live Operate on the live environment. Without it everything is test. --non-interactive Never prompt; fail with a fix instead. --api-url <url> Base URL of the API. --timeout <seconds> Per-request timeout in seconds. -h, --help display help for command
Commands: install [options] Write or update the bookrail entry in an MCP client configuration. help [command] display help for command
The server itself is `npx @bookrail/mcp`; this command only writes the entry thatstarts it into the client you name. It never writes a key: the server reads the samecredentials `bookrail login` stores.