Skip to content

CLI

chronos creates and triggers schedules, starts one-off jobs, shows what ran and what failed, and manages heartbeat monitors. Every subcommand of schedules, jobs, executions, monitors and auth prints JSON with --json, and every command exits with a documented code, so scripts and coding agents can drive it.

The CLI has no pull worker. To claim pull jobs, use the Node.js SDK or Go SDK worker, or use push delivery.

On macOS or Linux, install with Homebrew:

Terminal window
brew install halffive/tap/chronos-cli

Homebrew builds from source, so it also installs Go as a build dependency.

To install without Homebrew, run the install script:

Terminal window
curl -fsSL https://chronos.sh/install.sh | sh

The script installs to ~/.local/bin. To install somewhere else, set CHRONOS_INSTALL_DIR on sh, as in curl -fsSL https://chronos.sh/install.sh | CHRONOS_INSTALL_DIR=~/bin sh. The script verifies the download against the release’s checksums.txt and installs nothing if the check fails. The script never edits your shell profile. If the install directory is not on your PATH, the script prints the export PATH line to add. To install a specific version, run sh -s -- v0.1.0 instead of sh.

To install with Go 1.26 or later:

Terminal window
go install chronos.sh/cli/cmd/chronos@latest

Archives for macOS, Linux and Windows are on the releases page.

To check the install, run chronos version.

Upgrade the same way you installed. chronos does not check for updates, so watch the releases page for new versions.

  • Homebrew: run brew upgrade chronos-cli.
  • Install script: run curl -fsSL https://chronos.sh/install.sh | sh again. If you set CHRONOS_INSTALL_DIR, set it to the same directory.
  • Go: run go install chronos.sh/cli/cmd/chronos@latest.
  • Release archive: download the new archive from the releases page. Replace the old binary with the one inside.

Your saved login and config stay in place.

Run chronos auth logout, which revokes a browser login and removes the saved login. For a Homebrew install, run brew uninstall chronos-cli. Otherwise, delete the binary. Then delete the config directory, ~/.config/chronos by default (see CHRONOS_CONFIG_DIR).

Choose how the CLI authenticates:

  • In your own terminal, run chronos auth login. It opens the browser, where you log in and pick a workspace. The CLI saves an OAuth token that acts as you, with your role in that workspace. chronos auth status shows the token’s scopes and when it expires.
  • In scripts, CI and agents, set CHRONOS_API_KEY. Create the key in the dashboard under Settings → Keys and pick the Full access or CI and deploys preset. The CLI reads only the environment, so export a key from a .env file first. CHRONOS_API_KEY always overrides a saved login.

To save an API key instead of logging in with the browser, run chronos auth login --paste-key to paste it hidden in a terminal, or chronos auth login --with-key < key.txt to read it from stdin. Without a terminal or with --json, auth login needs --with-key.

A browser login ends 90 days after you log in, or after 30 days without use. After that, commands exit 4 with code login_expired. To log in again, run chronos auth login. To end it sooner, run chronos auth logout, or revoke it in the dashboard under Settings → CLI logins.

The CLI sends a saved login only to the base URL it was saved for. To use another CHRONOS_BASE_URL, log in again with that base URL set, or set CHRONOS_API_KEY.

On a machine with no keychain, auth login saves the login in config.json with mode 0600. On macOS, any process running as your user can read the keychain item through /usr/bin/security.

--json output, exit codes, error codes, flag names and environment variables stay compatible. New ones can appear, and existing ones keep their names and numbers. Tables, tab-separated output, help text and messages can change, so scripts should use --json.

Flag Effect
--json Prints JSON on stdout, and errors as JSON on stderr. help, --help, completion, --version, and chronos or a command group with no subcommand still print text.
--dry-run Prints the request and sends nothing. Works on every schedules, jobs and monitors command that changes something, and needs no key.
-h, --help Shows help for a command.
-v, --version Shows the version. Works only on chronos itself, not on a subcommand.

A flag that sets an API field or query parameter is that name in kebab-case: max_retries is --max-retries and scheduled_for is --scheduled-for. The REST reference documents every field. These flags are the exceptions:

Flag Effect
--push-url <url> Sets delivery.type to push and delivery.http.url.
--push-method <method> Sets delivery.http.method. Defaults to POST.
--push-header 'Name: value' Adds a header to delivery.http.headers, replacing one with the same name in any case. Repeatable.
--file <path> Reads the full request body as JSON. Use - for stdin. Other flags override its fields, and an unknown field is an error.
--clear <field> On schedules update, sends null for description, handler, payload, runs or stop-at. On monitors update, sends null for description. Repeatable.
--grace <duration> Sets grace_seconds on a monitor.
--wait, --wait-timeout <duration> Waits for the job to finish. The timeout defaults to 60s and must be at least 1s. --wait-timeout without --wait exits 2.
--all Lists every page. Conflicts with --page.
--yes, -y Confirms a delete. Required without a terminal or with --json.
Kind Format Example
Duration A whole number with an optional s, m, h, d or w. A bare number is seconds. 90s, 5m, 2d
Time RFC 3339 2027-02-15T00:00:00Z
Time filter (--*-after, --*-before) RFC 3339, or a duration meaning that long ago 24h
--payload A JSON object: inline, @path, or @- for stdin '{"fileId":"file_abc123"}'
Command Effect
list [--status] [--search] [--page] [--size] [--all] Lists schedules, newest first.
get <id> Shows a schedule.
create Creates a schedule.
update <id> Changes only the fields you pass. --push-* flags replace the whole delivery setting, so pass --push-url with them.
pause <id> Stops the schedule from creating jobs until you resume it. Exits 0 with a note if it is already paused.
resume <id> Restarts a paused schedule from its next run and skips the runs it missed. Exits 0 with a note if it is already active.
trigger <id> [--wait] [--wait-timeout] Creates a job now. The job counts toward --runs.
archive <id> Stops the schedule for good and cancels its jobs waiting to run.
delete <id> [--yes] Deletes the schedule permanently. Its jobs remain.

create and update take --name, --description, --handler, --cron or --interval, --timezone, --runs, --stop-at, --timeout, --max-retries, --payload, --file and the --push-* flags.

Terminal window
chronos schedules create --name 'Nightly report' --handler report --cron '0 3 * * *' --timezone Europe/London
chronos schedules update SCHEDULE_ID --clear runs --clear stop-at
chronos schedules trigger SCHEDULE_ID --wait --json
Command Effect
list [--schedule-id] [--origin] [--handler] [--search] [--status] [--scheduled-after] [--scheduled-before] [--page] [--size] [--all] Lists jobs, newest first.
get <id> Shows a job.
create [--wait] [--wait-timeout] Creates a one-off job. It runs now unless --delay or --scheduled-for sets a later time.
wait <id> [--wait-timeout] Waits for a job to finish and prints it.
cancel <id> Cancels a job that is waiting to run.
skip <id> Skips a pending or queued job that a schedule created.
retry <id> Runs a failed job again now.

create takes --name, --handler, --delay or --scheduled-for, --timeout, --max-retries, --payload, --idempotency-key, --file and the --push-* flags.

Terminal window
chronos jobs create --name 'Send digest' --handler send-digest --delay 10m
chronos jobs create --name 'Rebuild index' --handler rebuild-index --wait --wait-timeout 5m --json
chronos jobs list --status failed --scheduled-after 24h

To act on a filtered list, collect the ids first. Changing jobs while --all fetches pages moves them between pages, so the list misses some:

Terminal window
ids=$(chronos jobs list --status failed --all --json | jq -r '.data[].id')
for id in $ids; do
chronos jobs retry "$id" --json
done
Command Effect
list [--job-id] [--schedule-id] [--origin] [--handler] [--search] [--status] [--created-after] [--created-before] [--page] [--size] [--all] Lists executions, newest first. --origin api selects executions of one-off jobs.
get <id> Shows an execution.
Terminal window
chronos executions list --job-id JOB_ID --json
chronos executions list --origin api --status timeout

A heartbeat monitor watches a job that runs outside Chronos. The job reports by calling the monitor’s ping URL with the Ping API. The CLI sends no pings.

Command Effect
list [--status] [--search] [--page] [--size] [--all] Lists monitors, newest first. --status is new, up, late, down or paused.
get <id> Shows a monitor and its ping URL.
create Creates a monitor in status new. It sends no alert until its first success or fail ping.
update <id> Changes only the fields you pass.
pause <id> Stops the monitor from alerting until you resume it. Exits 0 with a note if it is already paused.
resume <id> Restarts alerting with the monitor’s next success or fail ping. Exits 0 with a note if it is not paused.
rotate-ping-url <id> Replaces the ping URL. The old URL stops accepting pings at once.
list-pings <id> [--page] [--size] [--all] Lists the monitor’s pings, newest first. Chronos keeps the latest 1,000.
delete <id> [--yes] Deletes the monitor and its pings permanently. Its ping URL stops working.

create and update take --name, --description, --cron or --interval, --timezone, --grace and --file. A new monitor’s grace period defaults to 5 minutes.

Terminal window
chronos monitors create --name 'Nightly backup' --cron '0 3 * * *' --timezone Europe/London --grace 10m
chronos monitors update MONITOR_ID --grace 15m --clear description
chronos monitors list --status down --json

The ping URL holds the token that authenticates pings, so treat the URL as a secret. In text output, get, create and rotate-ping-url print the full URL, and update, pause and resume hide the token. With --json, every command that returns a monitor prints the ping_url the API returns. For a key without the monitors:write scope, the API masks the token as ****. A masked URL accepts no pings.

To create a monitor and save its ping URL to a file without printing it:

Terminal window
chronos monitors create --name 'Nightly backup' --cron '0 3 * * *' --json | jq -r '.ping_url' > ping-url.txt

If rotate-ping-url exits 7 or 130, the rotation may have happened. Run chronos monitors get <id> to read the current URL.

Command Effect
login [--paste-key | --with-key] Without flags, logs in with the browser and saves an OAuth token. --paste-key and --with-key check an API key with GET /v1/account and save it. Without a terminal or with --json, it needs --with-key.
status Shows which login or API key is in use, where it came from, and its workspace. For a browser login, it also shows the person the login acts as, the token’s scopes and when the login expires.
logout Revokes a browser login on the server, then removes the saved login. A saved API key is removed but stays valid until you revoke it in the dashboard.
Command Effect
version Shows the CLI, SDK and Go versions. With --json, it also shows the commit and build time.
completion bash|zsh|fish|powershell Prints a completion script.
exit-codes Lists the exit codes. help exit-codes prints the same list as text only.
environment Lists the environment variables the CLI reads. help environment prints the same list as text only.
Code Meaning error.code
0 Success, including --dry-run none
1 Any other failure, including a declined confirmation error, cancelled, or the API’s code
2 Bad flags or arguments, or a confirmation that needs --yes usage_error
3 The resource does not exist the API’s code
4 No usable login or API key, or the API rejected it api_key_missing, login_expired, or the API’s code
5 The API rejected the request for validation, a conflict, a plan limit or a missing scope the API’s code
6 Safe to run again: rate limited, a read that failed, or a write that never left the machine rate_limit_exceeded, network_error, or the API’s code
7 A write failed after it may have reached the API. Check the resource’s state before running the command again. outcome_unknown
8 The job you waited for failed, was cancelled or was skipped job_unsuccessful
9 The wait ended before the job finished, or a check failed during the wait. Continue with chronos jobs wait <id>, and do not create the job again. wait_timeout, wait_failed
130 Interrupted by Ctrl-C, SIGTERM or SIGHUP. A write may have reached the API, so check the resource’s state before running the command again. interrupted

With --wait, the CLI prints the job on stdout if it read the job, including on exits 8 and 9. On wait_failed, that job comes from the create or trigger response, so its status can be stale.

Output Shape
One resource The API object, in snake_case
List {"data": [...], "paging": {"page", "pages", "size", "total"}}
Delete {"id": "...", "deleted": true}
Dry run {"dry_run": {"method", "url", "body"}}
auth logout {"logged_out": true}, or false with exit 0 when no login was saved
version {"version", "commit", "built_at", "go_version", "sdk_version"}, where commit and built_at can be null
exit-codes {"exit_codes": [{"code", "meaning"}]}
environment {"variables": [{"name", "meaning"}]}

JSON is indented on a terminal and compact when piped, so parse it instead of matching text. With --all, paging describes the whole list. An empty list has pages: 0. A dry run masks push header values and any password in a push URL.

auth status and auth login print the credential’s source and the workspace:

{
"credential": {
"type": "api_key",
"source": "env",
"storage": null,
"prefix": "chrns_abc",
"last_four": "a1b2",
"scopes": null,
"expires_at": null
},
"base_url": "https://api.chronos.sh",
"account": {
"id": "b7c1f0de-...",
"name": "Acme",
"timezone": "Europe/London",
"created_at": "2026-10-01T09:14:52.701Z"
},
"user": null
}

type is api_key or oauth_token. source is env or saved, and storage is keychain, file or null. For a browser login, prefix is empty, scopes lists the token’s scopes, expires_at is when it ends, and user is the person it acts as:

{
"credential": {
"type": "oauth_token",
"source": "saved",
"storage": "keychain",
"prefix": "",
"last_four": "Y2z3",
"scopes": ["schedules:write", "jobs:write", "executions:read", "monitors:write", "account:read"],
"expires_at": "2027-01-26T12:00:00Z"
},
"base_url": "https://api.chronos.sh",
"account": {
"id": "b7c1f0de-...",
"name": "Acme",
"timezone": "Europe/London",
"created_at": "2026-10-01T09:14:52.701Z"
},
"user": {
"id": "0192f3a1-...",
"email": "ada@example.com",
"name": "Ada Lovelace"
}
}

In a terminal, auth status prints rows instead, including “Logged in as” with the person’s email and an “OAuth token” row with only the last four characters.

With --json, stderr has only this object:

{
"error": {
"status": 409,
"code": "idempotency_key_conflict",
"message": "A job with this idempotency key already exists",
"request_id": "req_123",
"field_errors": [],
"retryable": false
}
}

retryable is true when running the same command again is safe. field_errors holds {"field", "message", "value"} objects for a validation error, where field can be null or name several fields. The error codes reference lists the API’s codes.

Variable Effect
CHRONOS_API_KEY The API key. Overrides the login saved by chronos auth login. A blank value counts as unset.
CHRONOS_BASE_URL The API base URL. Defaults to https://api.chronos.sh. Plain http works only for localhost.
CHRONOS_CONFIG_DIR Where chronos saves its config. Defaults to $XDG_CONFIG_HOME/chronos, then ~/.config/chronos, or the user config directory on Windows.
CHRONOS_INSTALL_DIR Where the install script puts the binary. Defaults to ~/.local/bin.
NO_COLOR Turns off color when set to any value.