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 isub_a1b2c3d4

`ical update <id>`

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

chronary ical update isub_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 5 minutes via cron).

chronary ical sync isub_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