Skip to content
Docs

CLI

Every command takes --json and prints exactly the API response. Errors go to stderr as {"error","message"}.

Install

npm i -g devalender
devalender login
devalender slots ada/intro --from 2030-01-07 --to 2030-01-14 --json
devalender book ada/intro \
  --start 2030-01-07T10:00:00Z \
  --name "Bob" --email [email protected] --json

Without installing anything, run it through npx: npx devalender@latest slots ada/intro --from 2030-01-07 --to 2030-01-14 --json.

Authentication

devalender login opens your browser to approve the CLI. On a machine without a browser, or for an agent, use devalender login --no-browser. In CI, pass a key with devalender login --key dvl_... or set DEVALENDER_API_KEY and skip logging in. The key is stored in ~/.config/devalender/config.json; point at another server with DEVALENDER_API_URL or --api-url.

Output

With --json every command prints exactly the API response, with no decoration, so it is safe to pipe into jq. Times are shown in your system timezone; pass --tz <IANA name> to read and write them in another.

Exit codes

CodeMeaning
0success
1generic error (network, server)
2usage error or invalid input
3not authenticated / bad API key
4conflict (slot taken, booking not active)
5not found

Command reference

Generated from the CLI itself, so it always matches the published version.

Global options

NameDescription
-V, --versionoutput the version number
--jsonprint machine-readable JSON
--tz <timezone>IANA timezone for input and display (default: system)

devalender login

Log in through the browser, or store an API key in ~/.config/devalender

devalender login [options]
NameDescription
--key <key>API key (dvl_...) for CI; skips the browser flow
--no-browserprint the URL and code without opening a browser
--api-url <url>API base URL

devalender logout

Remove the stored API key

devalender logout [options]

devalender whoami

Show the host the current API key belongs to

devalender whoami [options]

devalender event-types list

List your event types

devalender event-types list [options]

devalender event-types get

Show one event type

devalender event-types get [options] <id>
NameDescription
<id>-

devalender event-types create

Create an event type

devalender event-types create [options]
NameDescription
--title <title>-
--slug <slug>URL slug (a-z, 0-9, -)
--description <text>-
--duration <minutes>Length in minutes
--buffer-before <minutes>Buffer before
--buffer-after <minutes>Buffer after
--min-notice <minutes>Minimum booking notice
--max-per-day <n>Max bookings per day
--location-kind <kind>-
--location-value <value>URL, phone number, address, or text
--color <key>Palette colour: brand, sky, emerald, amber, rose, violet, teal, orange, or none to clear
--groupGroup event: schedule sessions that many people join
--capacity <n>Default seats per session (group events)

devalender event-types update

Update an event type

devalender event-types update [options] <id>
NameDescription
<id>-
NameDescription
--title <title>-
--slug <slug>URL slug (a-z, 0-9, -)
--description <text>-
--duration <minutes>Length in minutes
--buffer-before <minutes>Buffer before
--buffer-after <minutes>Buffer after
--min-notice <minutes>Minimum booking notice
--max-per-day <n>Max bookings per day
--location-kind <kind>-
--location-value <value>URL, phone number, address, or text
--color <key>Palette colour: brand, sky, emerald, amber, rose, violet, teal, orange, or none to clear
--activeMake bookable
--inactiveHide from the public page

devalender event-types delete

Delete an event type (deactivated instead if it has bookings)

devalender event-types delete [options] <id>
NameDescription
<id>-

devalender availability get

Show weekly rules and date overrides

devalender availability get [options]

devalender availability set-rules

Replace all weekly rules from a JSON file

devalender availability set-rules [options]
NameDescription
--file <path>JSON array of {weekday, startMinute, endMinute} (weekday 0=Sun) (required)

devalender availability override add

Add a date override; omit --start/--end to block the whole day

devalender availability override add [options]
NameDescription
--date <YYYY-MM-DD>(required)
--start <HH:MM>Available from (host timezone)
--end <HH:MM>Available until (host timezone)

devalender availability override remove

Remove a date override

devalender availability override remove [options] <id>
NameDescription
<id>-

devalender slots

List open booking slots for a host event type

devalender slots [options] <target>
NameDescription
<target><handle>/<slug>
NameDescription
--from <date>YYYY-MM-DD or ISO 8601 with offset (required)
--to <date>YYYY-MM-DD or ISO 8601 with offset (required)

devalender book

Book a slot as an invitee (no login needed)

devalender book [options] <target>
NameDescription
<target><handle>/<slug>
NameDescription
--start <time>ISO 8601 with offset, or local time interpreted in --tz (required)
--name <name>Invitee name (required)
--email <email>Invitee email (required)

devalender bookings list

List bookings

devalender bookings list [options]
NameDescription
--from <time>Only bookings starting at or after this time
--to <time>Only bookings starting before this time
--status <status>-
--limit <n>Page size (1-200, default 50)
--cursor <cursor>Continue from a previous page
--allFollow cursors and return every booking

devalender bookings get

Show one booking

devalender bookings get [options] <id>
NameDescription
<id>-

devalender bookings cancel

Cancel a booking

devalender bookings cancel [options] <id>
NameDescription
<id>-
NameDescription
--reason <text>-

devalender bookings reschedule

Move a booking to a new start time

devalender bookings reschedule [options] <id>
NameDescription
<id>-
NameDescription
--start <time>ISO 8601 with offset, or local time interpreted in --tz (required)

devalender manage view

Show a booking

devalender manage view [options]
NameDescription
--id <id>Booking id (required)
--token <token>Manage token from `book` (required)

devalender manage cancel

Cancel a booking

devalender manage cancel [options]
NameDescription
--id <id>Booking id (required)
--token <token>Manage token from `book` (required)
--reason <text>-

devalender manage reschedule

Move a booking to a new start time; returns a fresh manage token

devalender manage reschedule [options]
NameDescription
--id <id>Booking id (required)
--token <token>Manage token from `book` (required)
--start <time>ISO 8601 with offset, or local time interpreted in --tz (required)

devalender keys list

List API keys (secrets are never shown again)

devalender keys list [options]

devalender keys create

Create an API key; the secret is printed once

devalender keys create [options]
NameDescription
--name <name>Label for the key (required)

devalender keys revoke

Revoke an API key

devalender keys revoke [options] <id>
NameDescription
<id>API key id

devalender sessions list

List sessions

devalender sessions list [options]
NameDescription
--event-type <slug>Only this event type
--from <time>-
--to <time>-

devalender sessions create

Schedule a session (optionally repeating weekly)

devalender sessions create [options]
NameDescription
--event-type <slug>Group event type slug (required)
--start <time>ISO 8601 with offset, or local time interpreted in --tz (required)
--capacity <n>Seats (default: the event type)
--repeat-weeks <n>Create this many weekly sessions

devalender sessions cancel

Cancel a session; every attendee is notified

devalender sessions cancel [options] <id>
NameDescription
<id>-
NameDescription
--followingAlso cancel later sessions in the series
--reason <text>Shown to attendees

devalender sessions attendees

List who holds a seat in a session

devalender sessions attendees [options] <id>
NameDescription
<id>-

devalender webhooks list

List webhook endpoints

devalender webhooks list [options]

devalender webhooks add

Add an endpoint; the signing secret is printed once

devalender webhooks add [options] <url>
NameDescription
<url>https URL that receives the POST
NameDescription
--events <list>comma-separated events (default: all)

devalender webhooks remove

Delete an endpoint

devalender webhooks remove [options] <id>
NameDescription
<id>webhook id

devalender webhooks test

Send a signed test event to an endpoint

devalender webhooks test [options] <id>
NameDescription
<id>webhook id

devalender webhooks rotate

Rotate the signing secret; the new one is printed once

devalender webhooks rotate [options] <id>
NameDescription
<id>webhook id

devalender webhooks deliveries

Show recent deliveries for an endpoint

devalender webhooks deliveries [options] <id>
NameDescription
<id>webhook id
NameDescription
--limit <n>number of deliveries (1-200) Default: 50.

devalender webhooks enable

Re-enable an endpoint

devalender webhooks enable [options] <id>
NameDescription
<id>webhook id

devalender webhooks disable

Pause an endpoint

devalender webhooks disable [options] <id>
NameDescription
<id>webhook id

devalender teams list

List teams you belong to

devalender teams list [options]

devalender teams get

Show a team with its members

devalender teams get [options] <team-id>
NameDescription
<team-id>-

devalender teams create

Create a team (you become its owner)

devalender teams create [options]
NameDescription
--name <name>(required)
--slug <slug>URL slug (a-z, 0-9, -) (required)

devalender teams update

Rename a team or change its slug (owner only)

devalender teams update [options] <team-id>
NameDescription
<team-id>-
NameDescription
--name <name>-
--slug <slug>-

devalender teams delete

Delete a team (owner only)

devalender teams delete [options] <team-id>
NameDescription
<team-id>-

devalender teams members

List a team’s members

devalender teams members [options] <team-id>
NameDescription
<team-id>-

devalender teams remove-member

Remove a member (owner only)

devalender teams remove-member [options] <team-id> <host-id>
NameDescription
<team-id>-
<host-id>-

devalender teams leave

Leave a team

devalender teams leave [options] <team-id>
NameDescription
<team-id>-

devalender teams invites

List pending invites (owner only)

devalender teams invites [options] <team-id>
NameDescription
<team-id>-

devalender teams invite

Invite someone by email (owner only)

devalender teams invite [options] <team-id>
NameDescription
<team-id>-
NameDescription
--email <email>(required)

devalender teams revoke-invite

Revoke a pending invite (owner only)

devalender teams revoke-invite [options] <team-id> <invite-id>
NameDescription
<team-id>-
<invite-id>-

devalender teams accept-invite

Accept a team invite with the token from the email

devalender teams accept-invite [options] <token>
NameDescription
<token>-

devalender teams event-types

List a team’s event types

devalender teams event-types [options] <team-id>
NameDescription
<team-id>-

devalender teams create-event-type

Create a round-robin team event type (owner only)

devalender teams create-event-type [options] <team-id>
NameDescription
<team-id>-
NameDescription
--title <title>-
--slug <slug>URL slug (a-z, 0-9, -)
--description <text>-
--duration <minutes>Length in minutes
--location-kind <kind>-
--location-value <value>-
--members <host-ids>Comma-separated host ids that take bookings (default: all members)

devalender teams update-event-type

Update a team event type (owner only)

devalender teams update-event-type [options] <team-id> <event-type-id>
NameDescription
<team-id>-
<event-type-id>-
NameDescription
--title <title>-
--slug <slug>URL slug (a-z, 0-9, -)
--description <text>-
--duration <minutes>Length in minutes
--location-kind <kind>-
--location-value <value>-
--members <host-ids>Comma-separated host ids that take bookings (default: all members)
--activeMake bookable
--inactiveHide from the public page

devalender teams delete-event-type

Delete a team event type (deactivated if it has bookings)

devalender teams delete-event-type [options] <team-id> <event-type-id>
NameDescription
<team-id>-
<event-type-id>-

devalender teams bookings

List a team’s bookings (owner only)

devalender teams bookings [options] <team-id>
NameDescription
<team-id>-
NameDescription
--from <time>Only bookings starting at or after this time
--to <time>Only bookings starting before this time
--status <status>-

devalender teams slots

List open slots for a team event type (no login needed)

devalender teams slots [options] <target>
NameDescription
<target><team-slug>/<event-slug>
NameDescription
--from <date>YYYY-MM-DD or ISO 8601 with offset (required)
--to <date>YYYY-MM-DD or ISO 8601 with offset (required)

devalender teams book

Book a team event type as an invitee (no login needed)

devalender teams book [options] <target>
NameDescription
<target><team-slug>/<event-slug>
NameDescription
--start <time>ISO 8601 with offset, or local time (required)
--name <name>Invitee name (required)
--email <email>Invitee email (required)

Teams

devalender teams manages teams, members, invites and team event types, and lists team bookings. teams slots <team-slug>/<event> and teams book work without logging in. See Teams and round-robin.

For AI agents

Scriptable JSON on every command, stable exit codes, and flows an agent can repeat safely: look up slots, book one, and keep the manage token to reschedule or cancel later.

Set DEVALENDER_API_KEY instead of logging in, so the agent never touches a config file. To have Claude Code set a project up for you, see AI-assisted setup.

export DEVALENDER_API_KEY=dvl_...
devalender slots ada/intro --from 2030-01-07 --to 2030-01-14 --json
devalender book ada/intro --start 2030-01-07T10:00:00Z --name "Bob" --email [email protected] --json
devalender manage reschedule --id <booking-id> --token <manageToken> --start 2030-01-08T10:00:00Z --json

Example agent prompt

You can book meetings with the devalender CLI.
1. Run: devalender slots <handle>/<event> --from <date> --to <date> --json
2. Pick a slot that suits the user and run: devalender book <handle>/<event> --start <slot start> --name <name> --email <email> --json
3. Keep the manageToken from the response; use it to reschedule or cancel.
Exit code 4 means the slot was taken; fetch slots again and retry.