CLI Reference

Global options

These flags are available on every command:

Flag	Short	Default	Description
--output	-o	table	Output format: table, json, or yaml
--debug		false	Show HTTP request/response details
--api-key			API key (overrides env and config file)
--base-url		https://api.chronary.ai	API base URL
--no-color		false	Disable colored output

Environment variables

Variable	Description
CHRONARY_API_KEY	API key (used if --api-key not set and no config profile)
CHRONARY_BASE_URL	API base URL override

Config file

The CLI stores credentials in ~/.config/chronary/config.json (or the platform-specific user config directory). Managed via chronary auth commands.

---

chronary auth

Manage authentication profiles.

auth login

Interactive login — prompts for your API key, validates it, and saves to a profile.

Flag	Default	Description
--profile	default	Profile name to save credentials under

chronary auth login
chronary auth login --profile staging

auth status

Show the active profile’s key (masked), mode (test/live), and base URL.

chronary auth status

auth list

List all configured profiles with their mode and masked key.

chronary auth list

auth switch <profile>

Switch the active profile.

chronary auth switch production

auth remove <profile>

Delete a saved profile.

chronary auth remove staging

---

chronary keys

Manage agent-scoped API keys. Aliases: key.

These commands require an org-level API key.

keys list

List all agent-scoped keys for the authenticated organization.

chronary keys list
chronary keys list -o json

keys create [@file]

Flag	Default	Description
--agent		Agent ID (required unless using @file)
--label		Optional label shown in later listings

The raw key is printed once on successful creation.

chronary keys create --agent agt_a1b2c3d4 --label "Sales agent"
chronary keys create @key.json

keys delete <id>

Flag	Short	Description
--force	-f	Skip confirmation prompt
--yes	-y	Skip confirmation prompt (alias)

chronary keys delete key_abc123
chronary keys delete key_abc123 --yes

---

chronary agents

Manage agents. Aliases: agent.

agents list

Flag	Default	Description
--type		Filter by type: ai, human, resource
--status		Filter by status: active, paused, decommissioned
--limit	50	Max results per page
--offset	0	Pagination offset
--all	false	Fetch all pages automatically

chronary agents list
chronary agents list --type ai --status active --all

agents create [@file]

Flag	Default	Description
--name		Agent name (required unless using @file)
--type	ai	Agent type: ai, human, or resource
--description		Agent description
--metadata		Metadata as a JSON string

chronary agents create --name "Sales Bot" --type ai
chronary agents create @agent.json

agents get <id>

Retrieve an agent by ID.

chronary agents get agt_a1b2c3d4

agents update <id>

Flag	Description
--name	New name
--status	New status: active or paused
--description	New description
--metadata	New metadata as JSON string

At least one flag is required.

chronary agents update agt_a1b2c3d4 --name "Sales Bot v2" --status paused

agents delete <id>

Flag	Short	Description
--force	-f	Skip confirmation prompt
--yes	-y	Skip confirmation prompt (alias)

chronary agents delete agt_a1b2c3d4
chronary agents delete agt_a1b2c3d4 --yes

---

chronary calendars

Manage calendars. Aliases: calendar, cal.

calendars list

Flag	Default	Description
--agent		Filter by agent ID
--limit	50	Max results per page
--offset	0	Pagination offset
--all	false	Fetch all pages automatically

chronary calendars list
chronary calendars list --agent agt_a1b2c3d4

calendars create [@file]

Flag	Default	Description
--name		Calendar name (required unless using @file)
--timezone	UTC	IANA timezone (e.g., America/New_York)
--agent		Agent ID to own the calendar
--metadata		Metadata as JSON string

chronary calendars create --name "Sales Meetings" --timezone "America/New_York" --agent agt_a1b2c3d4
chronary calendars create @calendar.json

calendars get <id>

chronary calendars get cal_x1y2z3

calendars update <id>

Flag	Description
--name	New name
--timezone	New timezone
--metadata	New metadata as JSON string

chronary calendars update cal_x1y2z3 --name "Updated Name"

calendars delete <id>

Flag	Short	Description
--force	-f	Skip confirmation
--yes	-y	Skip confirmation (alias)

chronary calendars delete cal_x1y2z3 --yes

calendars context <id>

Return the temporal context (current event, next event, recent, upcoming) for a calendar.

chronary calendars context cal_x1y2z3

calendars availability-rules

Manage buffer-time and working-hours rules for a calendar. Aliases: rules.

chronary calendars availability-rules get cal_x1y2z3
chronary calendars availability-rules set cal_x1y2z3 @rules.json
chronary calendars availability-rules delete cal_x1y2z3 --yes

---

chronary events

Manage events. Aliases: event.

events list

Flag	Default	Description
--calendar		Calendar ID (required if --agent not set)
--agent		Agent ID (lists all events across agent’s calendars)
--start-after		Filter: start time after (ISO 8601)
--start-before		Filter: start time before (ISO 8601)
--status		Filter: confirmed, tentative, or cancelled
--limit	50	Max results per page
--offset	0	Pagination offset
--all	false	Fetch all pages automatically

chronary events list --calendar cal_x1y2z3
chronary events list --agent agt_a1b2c3d4 --status confirmed --all

events create [@file]

Flag	Default	Description
--calendar		Calendar ID (required)
--title		Event title (required unless using @file)
--start		Start time, ISO 8601 (required unless using @file)
--end		End time, ISO 8601 (required unless using @file)
--description		Event description
--all-day	false	All-day event
--status		Status: confirmed, tentative, cancelled, or hold
--metadata		Metadata as JSON string
--hold-expires-at		Required when --status=hold. ISO 8601 timestamp 30s–15min in the future.
--hold-priority	0	Priority for hold conflict resolution (0–100)

chronary events create \
  --calendar cal_x1y2z3 \
  --title "Team standup" \
  --start "2026-04-07T09:00:00Z" \
  --end "2026-04-07T09:15:00Z"

# Place a 5-minute hold at priority 10
chronary events create \
  --calendar cal_x1y2z3 \
  --title "[hold] Candidate slot" \
  --start "2026-04-07T14:00:00Z" \
  --end "2026-04-07T14:30:00Z" \
  --status hold \
  --hold-expires-at "2026-04-07T13:05:00Z" \
  --hold-priority 10

events get <id>

Flag	Description
--calendar	Calendar ID (required)

chronary events get evt_m1n2o3 --calendar cal_x1y2z3

events update <id>

Flag	Description
--calendar	Calendar ID (required)
--title	New title
--start	New start time (ISO 8601)
--end	New end time (ISO 8601)
--description	New description
--status	New status
--metadata	New metadata as JSON string

chronary events update evt_m1n2o3 --calendar cal_x1y2z3 --status cancelled

events delete <id>

Flag	Short	Description
--calendar		Calendar ID (required)
--force	-f	Skip confirmation
--yes	-y	Skip confirmation (alias)

chronary events delete evt_m1n2o3 --calendar cal_x1y2z3 --yes

events confirm <id>

Promote a hold (status=hold) to a confirmed event. The hold must still be active.

chronary events confirm evt_m1n2o3

events release <id>

Manually release a hold before its TTL, freeing the slot for other agents.

chronary events release evt_m1n2o3

---

chronary availability

Query free/busy time slots. Aliases: avail.

Shared flags

All availability subcommands accept:

Flag	Default	Description
--start		Start of window, ISO 8601 (required)
--end		End of window, ISO 8601 (required)
--slot-duration	30m	Slot size: 15m, 30m, 45m, 1h, 2h
--include-busy	false	Include busy blocks in response

availability agent <id>

chronary availability agent agt_a1b2c3d4 \
  --start "2026-04-07T09:00:00Z" \
  --end "2026-04-07T17:00:00Z"

availability calendar <id>

chronary availability calendar cal_x1y2z3 \
  --start "2026-04-07T09:00:00Z" \
  --end "2026-04-07T17:00:00Z"

availability cross

Flag	Description
--agents	Comma-separated agent IDs (required)
--calendars	Comma-separated calendar IDs (optional filter)

chronary availability cross \
  --agents "agt_a1b2c3d4,agt_e5f6g7h8" \
  --start "2026-04-07T09:00:00Z" \
  --end "2026-04-07T17:00:00Z" \
  --slot-duration 1h

---

chronary webhooks

Manage webhook subscriptions. Aliases: webhook, wh.

webhooks list

Flag	Default	Description
--limit	20	Max results per page
--offset	0	Pagination offset
--all	false	Fetch all pages

webhooks create [@file]

Flag	Description
--url	Webhook endpoint URL (required unless using @file)
--events	Comma-separated event types (required unless using @file)

Valid events: agent.created, agent.updated, event.created, event.updated, event.deleted.

chronary webhooks create \
  --url "https://example.com/hook" \
  --events "event.created, event.updated"

webhooks get <id>

chronary webhooks get wh_a1b2c3d4

webhooks update <id>

Flag	Description
--url	New endpoint URL
--events	New comma-separated event types
--active	Enable (true) or disable (false) the webhook

chronary webhooks update wh_a1b2c3d4 --active=false

webhooks delete <id>

Flag	Short	Description
--force	-f	Skip confirmation
--yes	-y	Skip confirmation (alias)

---

chronary ical

Manage iCal feed subscriptions. Aliases: ical-subscriptions.

ical list

Flag	Default	Description
--agent		Agent ID (required)
--status		Filter: active, error, paused
--limit	50	Max results per page
--offset	0	Pagination offset
--all	false	Fetch all pages

chronary ical list --agent agt_a1b2c3d4

ical create

Flag	Description
--agent	Agent ID (required)
--calendar	Calendar ID to sync into (required)
--url	iCal feed URL, must be HTTPS (required)
--label	Label for this subscription

chronary ical create \
  --agent agt_a1b2c3d4 \
  --calendar cal_x1y2z3 \
  --url "https://calendar.google.com/calendar/ical/example/basic.ics" \
  --label "Google Calendar"

ical get <id>

chronary ical get ics_a1b2c3d4

ical update <id>

Flag	Description
--label	New label
--url	New iCal feed URL (HTTPS)

chronary ical update ics_a1b2c3d4 --label "Work Calendar"

ical delete <id>

Flag	Short	Description
--force	-f	Skip confirmation
--yes	-y	Skip confirmation (alias)

ical sync <id>

Trigger an immediate sync (normally runs approximately every 15 minutes via cron).

chronary ical sync ics_a1b2c3d4

---

chronary scheduling

Manage multi-agent scheduling proposals. Aliases: schedule, proposals.

scheduling create @file

Requires a @file payload with title, organizer_agent_id, participant_agent_ids, calendar_id, and slots.

chronary scheduling create @proposal.json

scheduling list

Flag	Default	Description
--status		Filter: pending, confirmed, expired, cancelled
--organizer		Filter by organizer agent ID
--limit	50	Max results per page
--offset	0	Pagination offset
--all	false	Fetch all pages automatically

scheduling get <id>

Returns the full proposal (slots + responses).

scheduling respond <id> @file

Submit an agent response. @file body: { agent_id, response, selected_slot_id?, counter_slots?, message? }.

chronary scheduling respond spr_a1b2c3 @respond.json

scheduling resolve <id>

Pick the winning slot and create the event.

chronary scheduling resolve spr_a1b2c3

scheduling cancel <id>

Cancel a pending proposal.

chronary scheduling cancel spr_a1b2c3

---

chronary usage

Show current plan usage and quota limits. No flags beyond global options.

chronary usage
chronary usage -o json

---

chronary health

Check API connectivity and latency. No authentication required.

chronary health
chronary health -o json

---

chronary version

Print the CLI version.

chronary version