An AXI-compliant CLI for the Calendly API — built for agents.
calendly-axi wraps Calendly API v2 in an agent-ergonomic CLI: token-efficient TOON output, a UUID/URI/name accepted for every identifier, and errors translated into structured, actionable suggestions instead of raw API noise.
Its headline workflow is the booking loop — see what's scheduled, share a way to book, and manage the fallout (who booked, cancel, mark no-shows). Event type management, availability, and webhooks exist to support that loop.
$ calendly-axi
bin: ~/.local/share/npm/bin/calendly-axi
description: "Agent-ergonomic CLI for the Calendly API — see what's scheduled, share a way to book, and manage the fallout"
account: Ada Lovelace <[email protected]>
upcoming[3]{uuid,start,name,invitees}:
a1b2c3d4-1111-4a2b-9c3d-000000000001,"2026-08-12 14:00 (America/New_York)",Intro Call w/ Grace Hopper,1/1
a1b2c3d4-1111-4a2b-9c3d-000000000002,"2026-08-13 09:30 (America/New_York)",30 Minute Meeting w/ Alan Turing,1/1
a1b2c3d4-1111-4a2b-9c3d-000000000003,"2026-08-14 16:00 (America/New_York)",Project Sync,2/3
help[3]:
Run `calendly-axi events` to see what's scheduled
Run `calendly-axi link <event-type>` to get a booking link out
Run `calendly-axi types` to see what's bookable
npm install -g calendly-axiOr run it without installing:
npx -y calendly-axiread -rs T && printf %s "$T" | calendly-axi auth setup --token-stdinCreate a Personal Access Token at https://calendly.com/integrations/api_webhooks (Integrations → API & Webhooks → Generate new token) with these scopes: users:read, organizations:read, event_types:read/write, scheduled_events:read/write, availability:read/write, scheduling_links:write, webhooks:read/write. Legacy tokens without scopes have full access already.
The line above reads the token without echo and pipes it in on stdin, so it never lands in shell history or the process list. auth setup --token <pat> also works, for places where that doesn't matter (a CI step interpolating a secret).
Credentials and a bootstrap identity cache are stored in ~/.config/calendly-axi/config.json (dir 0700, file 0600; CALENDLY_AXI_CONFIG_DIR or XDG_CONFIG_HOME move it). Set CALENDLY_ACCESS_TOKEN instead to supply the token from the environment, with nothing stored — it takes precedence over the config file, which is useful in CI and cron. Verify either path with calendly-axi doctor.
auth setup only stores and validates the token. It reports whether the session hook is installed but never installs it — see Two ways to make it ambient.
| Command | What |
|---|---|
calendly-axi |
Home view: identity + up to 5 upcoming events + suggestions |
calendly-axi events [list|view|invitees|cancel|no-show] |
List upcoming events, inspect invitees, cancel, and mark no-shows |
calendly-axi link <event-type> |
Mint a single-use scheduling link for an event type |
calendly-axi book --type --at --name --email |
Book a meeting directly via the Scheduling API (paid plans only) |
calendly-axi busy |
Show busy intervals for the next 7 days |
calendly-axi types [list|view|slots|create|update|availability] |
List, inspect, and manage event types — bookable slots and availability rules |
calendly-axi webhooks [list|view|create|delete|sample] |
Manage webhook subscriptions (reads work on Free; creation needs a paid plan) |
calendly-axi auth [setup|whoami|logout] |
Connect, inspect, or remove the stored Personal Access Token |
calendly-axi doctor |
Five ordered health checks — credentials, token, organization, rate-limit headroom, hooks |
calendly-axi setup hooks [status|uninstall] [--scope user|project] |
Manage the SessionStart hook that injects the home view at session start |
calendly-axi events invitees <uuid> --email "[email protected]"
calendly-axi link "30 Minute Meeting"
calendly-axi book --type <uuid> --at 2026-08-18T15:00:00Z --name "Ada Lovelace" --email [email protected]
calendly-axi webhooks create --url https://example.com/hook --events invitee.created,invitee.canceledRun calendly-axi <command> --help for any command's full flag reference.
calendly-axi integrates into your agent's session so state is visible before you act. You only need one of these:
- SessionStart hook (recommended) — run
calendly-axi setup hooksto register a hook that injects the live home view (identity, upcoming events, booking-loop suggestions) at the start of every session, for Claude Code, Codex, and OpenCode. It is the only command that writes a hook;auth setupdoes not.--scope project(run from a repository root) writes that repository's agent config instead of your home one.calendly-axi setup hooks statusshows it;calendly-axi setup hooks uninstallremoves it. Idempotent and self-repairing. If any agent's settings file can't be written or the hook can't be confirmed afterwards, the command exits 1 withSETUP_FAILEDand names the file. - Installable skill — a static
SKILL.mdthe agent loads on demand (no per-session cost, broader agent support). It carries the same command guidance the hook's home view links out to, but not live state.
The hook gives you live data on every session; the skill is lower overhead and works anywhere. They're complementary — install whichever fits, or both.
Calendly's API has real walls. calendly-axi documents them at the point of need rather than papering over them:
- No delete for event types.
types update <type> --inactivedeactivates — the strongest removal the API offers. - Event type slugs are UI-only.
slug/scheduling_urlderive from the name at create time and are frozen thereafter; renaming withtypes update --namenever moves the booking URL, soupdatewarns when a rename lands. - Event type custom questions are UI-only.
custom_questionsis readable via the API but not writable —POST/PATCHbodies carrying it are silently ignored. - The API silently ignores unsupported write fields. Both of the boundaries above return a plain 200 with the field left untouched rather than an error —
calendly-axinever infers a field is writable just because a write succeeded. - No reschedule endpoint. Cancel with
events canceland rebook withbookorlink; invitees also carry their ownreschedule_urlfor the invitee-driven path. - No webhook update endpoint. Changing a subscription's URL or events is
webhooks delete+webhooks create. - Event type writes are solo-only.
types create/types updatework for one-on-one (kind: solo) types; group, collective, and round-robin types are read-only via the API. bookneeds a paid plan (Standard+) and has its own tighter rate limits, separate from the general per-minute cap: Trial 5/day; paid non-Enterprise 10/min, 50/hr, 100/day; Enterprise 500/min.- Webhook creation needs a paid plan (Standard+) on the subscribing organization; reads work on Free.
bun install
bun run dev # run the CLI from source
bun run build # compile to dist/
bun run check # type-check
bun run test # run the suite
bun run docs # regenerate skills/calendly-axi/SKILL.md from src/reference.ts
bun run docs:check # fail if the committed skill is staleBuilt on axi-sdk-js. Spec-driven — see specs/ for desired state and plans/ for the work-in-flight DAG.
MIT