CLI
bookai is a command-line client for the Back Office API.
Install
pipx install bookai-cli
Authenticate
bookai login
Interactive
Most bookai workflows are guided rather than flag-driven — the CLI prompts
you for what it needs, so there's nothing to look up ahead of time.
Set up a brand-new venue. bookai venues create walks you through
creating a venue and its first (owner) account — no API key needed yet, since
this is how that first account gets created:
$ bookai venues create
Setting up a new venue on https://b2b.bookai.now. Ctrl-C to cancel at any time.
Venue name: The Grand Hall
Street address: 500 5th Ave
City: New York
State: NY
Country [US]:
Now your account -- you'll be this venue's first admin:
Your first name: Jamie
Your last name: Rivera
Your email: jamie@thegrandhall.com
Password:
Repeat for confirmation:
Create "The Grand Hall" (New York, NY) for jamie@thegrandhall.com?
Confirm [Y/n]: y
Created "The Grand Hall" (id: v_8f2a1c).
Run `bookai login` to authorize this machine as jamie@thegrandhall.com.
Explore without retyping bookai every time. Run bookai with no
command to drop into an interactive shell — every subcommand below works the
same way, just without the leading bookai:
$ bookai
bookai interactive shell -- commands run without the leading `bookai` (e.g. `venues list`).
Type `help` for the command list, `whoami` for your current env/key, `exit` to quit.
bookai (prod)> venues list
...
bookai (prod)> exit
Lay out a season. Showings are the dates and times people actually book.
A season is usually a repeating shape rather than a list of one-off dates, so
--repeat-weekly creates the showing plus that many weekly copies:
$ bookai offerings slots add gala-ocean --date 2026-11-19 --time 19:00 \
--duration 4 --capacity 400 --repeat-weekly 3
Added 4 showing(s)
id start_datetime end_datetime capacity sold available
a5bdc29f 2026-11-19T19:00Z 2026-11-19T23:00Z 400 0 400
7bcd5bab 2026-11-26T19:00Z 2026-11-26T23:00Z 400 0 400
35ab593f 2026-12-03T19:00Z 2026-12-03T23:00Z 400 0 400
1c227c4a 2026-12-10T19:00Z 2026-12-10T23:00Z 400 0 400
Run an offering for longer. Showings have to fall inside the offering's
run, so extending it is the usual first step. --to takes an exact date,
--by pushes the end date out from wherever it is now (3m, 6w, 30d):
$ bookai offerings extend gala-ocean --by 3m
Private Gala — Milstein Hall of Ocean Life now runs until 2027-03-31
The API stops you doing the things that would quietly break bookings, and the CLI shows you its reason rather than swallowing it:
$ bookai offerings extend gala-ocean --to 2026-11-01
Error: API error 409: 4 existing showing(s) between 2026-11-19 and 2026-12-10
would fall outside the run 2026-09-01 to 2026-11-01 and stop being bookable —
remove them first, or choose a wider window
The same applies to a showing someone has already booked onto: its capacity can't drop below what's sold, and it can't be removed at all.
Reference
bookai
bookai: manage venues, pricing, and orders from the command line.
Run bookai login once per environment to save a key and make it your
default -- or pass --api-key / set GROUPSALES_API_KEY for scripting and
CI. Run bookai with no command for an interactive shell.
Usage:
bookai [OPTIONS] [COMMAND] [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--api-key |
text | API key (or set GROUPSALES_API_KEY). Overrides a saved bookai login key. |
None |
--base-url |
text | Back office API base URL (or set GROUPSALES_BASE_URL). Overrides --env. | None |
--env |
choice (local | prod | sandbox) |
Shortcut for --base-url: local, prod, sandbox. Defaults to your last bookai login, or prod if you've never logged in. |
None |
--json |
boolean | Print raw JSON instead of a table. | False |
--version |
boolean | Show the version and exit. | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai ask
Ask about anything at your venue, in plain words.
The Ask agent looks it up in your venue's records -- guests, conversations, offers, quotes, orders, offerings, policies, pricing, payment terms, contacts -- and answers with links to what it used. It can read, not change anything.
bookai ask which offers need my approval? bookai ask -c and which of those are over 50 people? bookai ask # a conversation, one question per line
Quote a question that contains shell characters like ? or ! if your shell expands them: bookai ask "who went quiet after a quote?"
Usage:
bookai ask [OPTIONS] [QUESTION]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
-c, --continue |
boolean | Follow up on your last conversation instead of starting a new one. | Sentinel.UNSET |
--session |
text | Follow up on this conversation. | None |
--history |
boolean | List your recent conversations and exit. | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai contacts
Manage per-venue contacts.
Usage:
bookai contacts [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai contacts add
Add a new contact to a venue.
Usage:
bookai contacts add [OPTIONS] VENUE_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--first-name |
text | Contact's first name. | Sentinel.UNSET |
--last-name |
text | Contact's last name. | Sentinel.UNSET |
--email |
text | Contact's email address. | None |
--cell-number |
text | Contact's cell number. | None |
--whatsapp |
text | WhatsApp-reachable number, if different from --cell-number. | None |
--role |
text | e.g. 'Owner', 'Events Manager'. | None |
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai contacts delete
Delete a contact.
Usage:
bookai contacts delete [OPTIONS] VENUE_ID CONTACT_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai contacts get
Show one contact.
Usage:
bookai contacts get [OPTIONS] VENUE_ID CONTACT_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai contacts list
List contacts for a venue.
Usage:
bookai contacts list [OPTIONS] VENUE_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai contacts update
Replace an existing contact's details.
Usage:
bookai contacts update [OPTIONS] VENUE_ID CONTACT_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--first-name |
text | Contact's first name. | Sentinel.UNSET |
--last-name |
text | Contact's last name. | Sentinel.UNSET |
--email |
text | Contact's email address. | None |
--cell-number |
text | Contact's cell number. | None |
--whatsapp |
text | WhatsApp-reachable number, if different from --cell-number. | None |
--role |
text | e.g. 'Owner', 'Events Manager'. | None |
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai login
Authorize this machine via your browser and save the key locally.
Usage:
bookai login [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--timeout |
integer | Seconds to wait for browser authorization. | 300 |
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai logout
Remove the locally saved API key. Does not revoke it server-side -- revoke from the back office's API Keys page to invalidate it entirely.
Usage:
bookai logout [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--all |
boolean | Log out of every known environment, not just the current one. | False |
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai offerings
Manage offerings and their showings.
Usage:
bookai offerings [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai offerings extend
Extend how long an offering runs for.
Nothing more than setting valid_to, which is why it PATCHes the offering rather than calling some dedicated endpoint — but it's the single most common edit, so it gets a verb. The API refuses to narrow a run past showings that already exist.
Usage:
bookai offerings extend [OPTIONS] OFFERING_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--to |
text | New end date, YYYY-MM-DD. | None |
--by |
text | Extend past the current end date, e.g. 3m, 6w, 30d. | None |
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai offerings list
List this venue's offerings.
Usage:
bookai offerings list [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai offerings show
Show one offering, with its showings and pricing tiers.
Usage:
bookai offerings show [OPTIONS] OFFERING_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai offerings slots
Manage an offering's showings.
Usage:
bookai offerings slots [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai offerings slots add
Add a showing, optionally repeating it weekly.
A season is usually a repeating shape rather than a list of one-off dates, so --repeat-weekly lays the whole run down in one call.
Usage:
bookai offerings slots add [OPTIONS] OFFERING_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--date |
text | Date of the first showing, YYYY-MM-DD. | Sentinel.UNSET |
--time |
text | Start time, HH:MM (24h). | Sentinel.UNSET |
--duration |
float | Length in hours. | 3.0 |
--capacity |
integer | Seats available on each showing. | Sentinel.UNSET |
--repeat-weekly |
integer | Extra weekly copies — 3 gives four showings in total. | 0 |
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai offerings slots list
List an offering's showings.
Usage:
bookai offerings slots list [OPTIONS] OFFERING_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai offerings slots rm
Remove a showing. Refused by the API once seats have sold against it.
Usage:
bookai offerings slots rm [OPTIONS] OFFERING_ID SLOT_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--yes |
boolean | Skip the confirmation prompt. | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai offerings slots set
Move a showing or change its capacity.
The API refuses a capacity below what has already sold — those seats belong to real bookings.
Usage:
bookai offerings slots set [OPTIONS] OFFERING_ID SLOT_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--date |
text | Move it to this date, YYYY-MM-DD. | None |
--time |
text | Move it to this start time, HH:MM. | None |
--duration |
float | New length in hours. | None |
--capacity |
integer | New seat count. | None |
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai orders
View confirmed orders.
Usage:
bookai orders [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai orders list
List confirmed orders (paginated).
Usage:
bookai orders list [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--page |
integer | N/A | 1 |
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai pricing
Manage per-venue pricing rules.
Usage:
bookai pricing [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai pricing delete
Delete a pricing rule.
Usage:
bookai pricing delete [OPTIONS] VENUE_ID RULE_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai pricing get
Show one pricing rule.
Usage:
bookai pricing get [OPTIONS] VENUE_ID RULE_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai pricing list
List pricing rules for a venue.
Usage:
bookai pricing list [OPTIONS] VENUE_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai pricing set
Create a new pricing rule.
Usage:
bookai pricing set [OPTIONS] VENUE_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--min-group |
integer | Minimum group size this rule applies to. | Sentinel.UNSET |
--max-group |
integer | Maximum group size this rule applies to. | Sentinel.UNSET |
--min-price |
float | Price floor per person. | Sentinel.UNSET |
--max-price |
float | Price ceiling per person. | Sentinel.UNSET |
--offering-id |
text | Scope this rule to one offering instead of the whole venue. | None |
--source |
text | Origin tag, e.g. a 3P vendor name. | app |
--external-id |
text | 3P upsert key -- ignored while --source is 'app'. | None |
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai pricing update
Replace an existing pricing rule.
Usage:
bookai pricing update [OPTIONS] VENUE_ID RULE_ID
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--min-group |
integer | Minimum group size this rule applies to. | Sentinel.UNSET |
--max-group |
integer | Maximum group size this rule applies to. | Sentinel.UNSET |
--min-price |
float | Price floor per person. | Sentinel.UNSET |
--max-price |
float | Price ceiling per person. | Sentinel.UNSET |
--offering-id |
text | Scope this rule to one offering instead of the whole venue. | None |
--source |
text | Origin tag, e.g. a 3P vendor name. | app |
--external-id |
text | 3P upsert key -- ignored while --source is 'app'. | None |
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai search
Search every record at your venue: conversations, offers, quotes, orders, offerings, policies, pricing tiers, payment terms and contacts.
Matches exact words (names, emails, ids) and meaning, so
bookai search where do coaches park finds a guest asking about bus parking.
Usage:
bookai search [OPTIONS] QUERY...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--type |
choice (conversation | offer | quote | order | offering | rule | pricing_tier | payment_policy | contact) |
Only this kind of record. Repeat for several. | Sentinel.UNSET |
--limit |
integer range (between 1 and 50) |
N/A | 20 |
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai venues
Manage venues.
Usage:
bookai venues [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai venues create
Create a brand-new venue and its first (owner) account, guided step-by-step -- no API key needed yet, since this is how a venue's very first account gets created (same as signing up in the browser).
Usage:
bookai venues create [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai venues list
List venues visible to this API key's account.
Usage:
bookai venues list [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |
bookai whoami
Show which environment and API key this CLI is currently using.
Usage:
bookai whoami [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | Sentinel.UNSET |