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.
Install
Section titled “Install”On macOS or Linux, install with Homebrew:
brew install halffive/tap/chronos-cliHomebrew builds from source, so it also installs Go as a build dependency.
To install without Homebrew, run the install script:
curl -fsSL https://chronos.sh/install.sh | shThe 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:
go install chronos.sh/cli/cmd/chronos@latestArchives for macOS, Linux and Windows are on the releases page.
To check the install, run chronos version.
Upgrade
Section titled “Upgrade”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 | shagain. If you setCHRONOS_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.
Uninstall
Section titled “Uninstall”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 statusshows 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.envfile first.CHRONOS_API_KEYalways 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.
What stays compatible
Section titled “What stays compatible”--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. |
Values
Section titled “Values”| 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"}' |
chronos schedules
Section titled “chronos schedules”| 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.
chronos schedules create --name 'Nightly report' --handler report --cron '0 3 * * *' --timezone Europe/Londonchronos schedules update SCHEDULE_ID --clear runs --clear stop-atchronos schedules trigger SCHEDULE_ID --wait --jsonchronos jobs
Section titled “chronos jobs”| 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.
chronos jobs create --name 'Send digest' --handler send-digest --delay 10mchronos jobs create --name 'Rebuild index' --handler rebuild-index --wait --wait-timeout 5m --jsonchronos jobs list --status failed --scheduled-after 24hTo act on a filtered list, collect the ids first. Changing jobs while --all fetches pages moves them between pages, so the list misses some:
ids=$(chronos jobs list --status failed --all --json | jq -r '.data[].id')for id in $ids; do chronos jobs retry "$id" --jsondonechronos executions
Section titled “chronos executions”| 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. |
chronos executions list --job-id JOB_ID --jsonchronos executions list --origin api --status timeoutchronos monitors
Section titled “chronos monitors”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.
chronos monitors create --name 'Nightly backup' --cron '0 3 * * *' --timezone Europe/London --grace 10mchronos monitors update MONITOR_ID --grace 15m --clear descriptionchronos monitors list --status down --jsonThe 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:
chronos monitors create --name 'Nightly backup' --cron '0 3 * * *' --json | jq -r '.ping_url' > ping-url.txtIf rotate-ping-url exits 7 or 130, the rotation may have happened. Run chronos monitors get <id> to read the current URL.
chronos auth
Section titled “chronos auth”| 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. |
Other commands
Section titled “Other commands”| 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. |
Exit codes
Section titled “Exit codes”| 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.
JSON output
Section titled “JSON output”| 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.
Errors
Section titled “Errors”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.
Environment variables
Section titled “Environment variables”| 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. |