bookai-cli

Command-line client for the bookai group-sales back office API — manage venue pricing, offerings and their showings, and view confirmed orders from the terminal or a script, instead of clicking through the admin web app.

This is a thin HTTP client: it talks only to the public, authenticated JSON API and contains no business logic or backend code.

Install

pip install bookai-cli

Authenticate

bookai login

Opens your browser to authorize this machine, then saves the key locally (your OS keychain, or a 0600 file under your user config dir if no keychain is available) — no copy-pasting a raw key required. The environment you just logged into also becomes your default for every later command that doesn't explicitly pass --env/--base-url (see Environments below) — run bookai login again any time to re-authorize, switch accounts, or switch which environment is your default.

Check what's currently active any time with:

bookai whoami

For scripting/CI, skip login and use a key directly instead — mint one from the back office's API Keys page and set it as an environment variable:

export GROUPSALES_API_KEY=gsk_...

--api-key (or GROUPSALES_API_KEY) always takes priority over a bookai login-saved key when both are present.

bookai logout removes the locally saved key (add --all to clear every environment at once). This only forgets the key on this machine — it stays valid until you revoke it from the back office's API Keys page.

Environments

This project runs three environments:

You don't need to pass --env on every command. bookai login sets the environment you just authorized as your default (saved to a small local config file, separate from the key itself) — so once you've run bookai --env sandbox login, every later bookai venues list / bookai pricing ... targets sandbox automatically, with no flags needed. Run bookai whoami any time to check which environment and key are currently active.

--env <name> (or --base-url <url>/GROUPSALES_BASE_URL for a fully custom URL not in the table above) overrides your default for that one command only — it doesn't change what bookai login set as your default. bookai login saves a separate key per base URL, so logging into sandbox and prod don't clobber each other; switching your default just means running bookai login again against the other one.

Before your first bookai login, the default is prod if nothing else is set.

Global options (--api-key, --base-url, --env, --json) go before the subcommand: bookai --json venues list, not bookai venues list --json.

Interactive shell

Run bookai with no command to get a prompt — commands run without the leading bookai, and your environment/key from that shell's startup (or from a login/--env typed mid-session) stays in effect line to line:

$ 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 (sandbox)> venues list
...
bookai (sandbox)> exit

exit/quit/Ctrl-D leaves the shell. This is purely a convenience layer — every line is dispatched through the exact same commands as one-shot usage, so anything in Usage below works here too.

Usage

bookai venues list
bookai venues create                            # guided prompts -- creates a brand-new venue + your account, no key needed yet

bookai contacts list <venue_id>
bookai contacts get <venue_id> <contact_id>
bookai contacts add <venue_id> --first-name Jamie --last-name Rivera --email jamie@example.com --role Owner
bookai contacts update <venue_id> <contact_id> --first-name Jamie --last-name Rivera --role "Events Manager"
bookai contacts delete <venue_id> <contact_id>

bookai pricing list <venue_id>
bookai pricing get <venue_id> <rule_id>
bookai pricing set <venue_id> --min-group 10 --max-group 50 --min-price 20 --max-price 30
bookai pricing set <venue_id> --min-group 10 --max-group 50 --min-price 20 --max-price 30 \
    --source acme-isv --external-id acme-rule-42   # tag a rule as synced from an external system
bookai pricing update <venue_id> <rule_id> --min-group 10 --max-group 50 --min-price 18 --max-price 28
bookai pricing delete <venue_id> <rule_id>

bookai offerings list
bookai offerings show <offering_id>
bookai offerings extend <offering_id> --to 2027-03-31    # run it for longer
bookai offerings extend <offering_id> --by 3m            # ...or just push the end date out

bookai offerings slots list <offering_id>
bookai offerings slots add <offering_id> --date 2026-11-19 --time 19:00 --capacity 400
bookai offerings slots add <offering_id> --date 2026-11-19 --time 19:00 --capacity 400 \
    --duration 4 --repeat-weekly 3                       # lay out a four-week run in one go
bookai offerings slots set <offering_id> <slot_id> --time 14:00    # move it, keeping its length
bookai offerings slots set <offering_id> <slot_id> --capacity 250
bookai offerings slots rm <offering_id> <slot_id>

bookai orders list
bookai orders list --page 2

Showings

offerings slots manages the individual showings of a timed offering — the dates and times people actually book. --repeat-weekly is there because a season is usually a repeating shape rather than a list of one-off dates: --repeat-weekly 3 creates the showing plus three weekly copies, four in total.

The API keeps you from doing the things that would quietly break bookings, and the CLI reports its reason rather than swallowing it:

• a showing with seats already sold can't be removed, and its capacity can't drop below what's sold
• a showing outside the offering's run is refused, rather than sitting on the calendar looking bookable — extend the run first
• narrowing a run past showings that already exist is refused for the same reason: they'd stay on the calendar while quietly dropping out of availability

offerings extend is exactly that "extend the run first" step. It's a plain update of the offering's end date — --to for an exact date, --by 3m (also 6w, 30d) to push it out from wherever it currently ends.

bookai venues create is the one command that works with no API key at all — it's how a brand-new venue's very first account gets created in the first place (same as signing up in the browser). It asks for the venue's details and your own name/email/password one at a time, confirms before submitting, then tells you to run bookai login next.

Add --json anywhere for machine-readable output instead of a table — useful for piping into jq or scripting in CI.

Development

pip install -e ".[dev]"
pytest

Tests are fully offline (HTTP is mocked via respx) — no server or database required.