CLI Usage

This guide walks through every CLI command group with practical examples. For a quick start, see the CLI Quickstart. For flag-level detail, see the CLI Reference.

Authentication

Login

The interactive login validates your key against the API before saving:

chronary auth login

Save to a named profile:

chronary auth login --profile staging

Multiple profiles

Manage separate keys for test, live, and different environments:

# List profiles
chronary auth list

   Profile     Key
*  default     chr_sk_a1b2...
   production  chr_sk_x9y8...

# Switch profiles
chronary auth switch production

# Remove a profile
chronary auth remove staging

Status

chronary auth status

Key:      chr_sk_a1b2...
Base URL: https://api.chronary.ai

Agents

List agents

chronary agents list

ID            Name                    Type  Status  Description                  Created
agt_a1b2c3d4  Sales Agent - Acme      ai    active  Handles meeting scheduling   2026-04-04
agt_e5f6g7h8  Support Bot             ai    active  Customer support scheduling  2026-04-05

Showing 2 of 2 agents

Filter by type or status:

chronary agents list --type ai --status active

Fetch all pages automatically:

chronary agents list --all

Register an agent

chronary agents create --name "Sales Agent" --type ai --description "Handles sales meetings"

Or from a JSON file:

chronary agents create @agent.json

Where agent.json contains:

{
  "name": "Sales Agent",
  "type": "ai",
  "description": "Handles sales meetings",
  "metadata": { "team": "sales", "region": "us-east" }
}

Get, update, delete

# Get full details
chronary agents get agt_a1b2c3d4

# Update fields
chronary agents update agt_a1b2c3d4 --name "Sales Agent v2" --status paused

# Delete (with confirmation prompt)
chronary agents delete agt_a1b2c3d4

# Skip confirmation
chronary agents delete agt_a1b2c3d4 --yes

Calendars

List calendars

# All calendars in your org
chronary calendars list

# Calendars for a specific agent
chronary calendars list --agent agt_a1b2c3d4

Create a calendar

# Org-level calendar
chronary calendars create --name "Conference Room B" --timezone "America/Chicago"

# Agent-owned calendar
chronary calendars create --agent agt_a1b2c3d4 --name "Sales Meetings" --timezone "America/New_York"

# With metadata
chronary calendars create \
  --name "Conference Room B" \
  --timezone "America/Chicago" \
  --metadata '{"capacity": 12, "floor": 4}'

Or from a file:

chronary calendars create @calendar.json

Get, update, delete

chronary calendars get cal_x1y2z3
chronary calendars update cal_x1y2z3 --name "New Name" --timezone "Europe/London"
chronary calendars delete cal_x1y2z3 --yes

Events

List events

Events require either a --calendar or --agent scope:

# Events on a specific calendar
chronary events list --calendar cal_x1y2z3

# All events across an agent's calendars
chronary events list --agent agt_a1b2c3d4

# With date and status filters
chronary events list --calendar cal_x1y2z3 \
  --start-after "2026-04-01T00:00:00Z" \
  --start-before "2026-04-30T23:59:59Z" \
  --status confirmed

Create an event

chronary events create \
  --calendar cal_x1y2z3 \
  --title "Strategy sync" \
  --start "2026-04-07T14:00:00Z" \
  --end "2026-04-07T14:30:00Z" \
  --description "Quarterly strategy alignment" \
  --status confirmed

All-day events:

chronary events create \
  --calendar cal_x1y2z3 \
  --title "Company Holiday" \
  --start "2026-07-04T00:00:00Z" \
  --end "2026-07-05T00:00:00Z" \
  --all-day

From a file:

chronary events create @event.json --calendar cal_x1y2z3

Get, update, delete

chronary events get evt_m1n2o3 --calendar cal_x1y2z3
chronary events update evt_m1n2o3 --calendar cal_x1y2z3 --title "Updated title" --status cancelled
chronary events delete evt_m1n2o3 --calendar cal_x1y2z3 --yes

Availability

Query free/busy slots for agents, calendars, or across multiple agents.

Agent availability

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

Calendar availability

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

Cross-agent availability

Find shared free time across multiple agents:

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

Include busy blocks

Add --include-busy to see what’s blocking each time slot:

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

Webhooks

List webhooks

chronary webhooks list

Create a webhook

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

Created webhook wh_a1b2c3d4
URL:    https://example.com/webhooks/chronary
Events: event.created, event.updated
Secret: whsec_abc123...
(Save this secret — it won't be shown again)

Caution

The webhook signing secret is only shown once at creation time. Save it immediately — you’ll need it to verify webhook signatures.

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

Get, update, delete

chronary webhooks get wh_a1b2c3d4
chronary webhooks update wh_a1b2c3d4 --events "event.created" --active=false
chronary webhooks delete wh_a1b2c3d4 --yes

iCal Subscriptions

Import external iCal feeds into a Chronary calendar. The API polls them approximately every 5 minutes.

List subscriptions

chronary ical list --agent agt_a1b2c3d4

Create a subscription

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

Get, update, delete, sync

# Get details
chronary ical get isub_a1b2c3d4

# Update label or URL
chronary ical update isub_a1b2c3d4 --label "Personal Google Cal"

# Delete
chronary ical delete isub_a1b2c3d4 --yes

# Trigger an immediate sync
chronary ical sync isub_a1b2c3d4

Usage & Quotas

Check your current plan usage:

chronary usage

Plan:   free
Period: 2026-04-01 to 2026-04-30

Resource              Used  Limit  Remaining
Agents                   2     10          8
Calendars                3     25         22
Events                  15    500        485
API Calls              142  10000       9858
Webhooks                 1      5          4
Availability Queries    28   1000        972
iCal Subscriptions       1      5          4

Health check

Verify the API is reachable:

chronary health

Status:  ok
Time:    2026-04-07T12:00:00Z
Latency: 45ms

File input

Any create command accepts a @file argument to read the request body from a JSON file instead of flags:

chronary agents create @agent.json
chronary calendars create @calendar.json
chronary events create @event.json --calendar cal_x1y2z3
chronary webhooks create @webhook.json

You can also pipe from stdin using @-:

echo '{"name":"Bot","type":"ai"}' | chronary agents create @-

Pagination

List commands return a single page by default. Use --all to fetch every page automatically:

# Default: first page (50 results)
chronary events list --calendar cal_x1y2z3

# Manual pagination
chronary events list --calendar cal_x1y2z3 --limit 10 --offset 20

# Auto-paginate everything
chronary events list --calendar cal_x1y2z3 --all

Output formats

Every command supports three output formats via the --output (or -o) flag:

# Table (default) — human-readable
chronary agents list

# JSON — for scripting and piping
chronary agents list -o json | jq '.data[].name'

# YAML — for readability in config contexts
chronary agents get agt_a1b2c3d4 -o yaml