Docs menu · CLI
Guides
- Overview
- Connect your assistant
- Asking for automations
- Connections and secrets
- Trigger links
- Looking after automations
- State between runs
- Troubleshooting
- FAQ
- For coding agents
Reference
ClickRuntime CLI
Install the CLI, sign in from a terminal, and every command with its exit codes and JSON output.
The ClickRuntime CLI lets a coding assistant with a terminal, such as Claude Code, Codex or Cursor, do everything the ClickRuntime MCP server does, without MCP. It follows the same rules: you sign in, add keys and connections in the ClickRuntime dashboard, and confirm before anything goes live. The assistant never sees a key and can't confirm on its own. See also For coding agents and the API.
Install#
npx clickruntime status
Node.js 18 or later. Or install it with Python 3.9 or later:
pipx install clickruntime-cli
Both install the same clickruntime command, with the same commands, output and exit codes. The Python package never installs a clickruntime module, so it can't get in the way of scripts that import clickruntime.
Sign in#
clickruntime login
The CLI opens the ClickRuntime sign-in in your browser. Sign in or create an account with Google or an email link, pick a workspace and approve. The tab then says you can go back to your agent.
On a machine without a browser, such as a remote server or a sandbox, use a code instead:
clickruntime login --device
It prints a link and a code like BCDF-GHJK. Open clickruntime.com/device on any device, sign in, check the code matches and approve. Only enter a code you got from your own agent. If no browser sign-in arrives within five minutes, login also offers a code and keeps waiting for the browser for five more; whichever you finish first signs you in.
An agent that can't wait for you can run clickruntime login --device --no-wait, give you the link and the code, and later run clickruntime login --continue.
Each sign-in appears in the ClickRuntime dashboard under Settings → Assistants, in Signed in from a terminal, where you can sign it out. clickruntime logout does the same from the terminal.
Commands#
All commands take --json and --workspace <name>. Each one maps to an MCP tool, so the skills, the MCP server and the API read the same.
| Command | What it does | MCP tool |
|---|---|---|
clickruntime status | Signed in? Which workspace? | get_profile |
clickruntime login [--device] [--no-wait] | Sign in (the person approves in the browser) | — |
clickruntime logout | End this sign-in | — |
| `clickruntime init <name> --pattern schedule | incoming | remember_then_schedule` |
clickruntime save | Save the local files as a draft, or update it | save_draft, update_draft, change_automation |
clickruntime pull <id> | Download an automation's script and settings | get_automation, get_script |
clickruntime list | List automations | list_automations |
clickruntime show <id> | One automation | get_automation |
clickruntime setup <id> | Setup steps left, each with its link | get_setup_status |
| `clickruntime setup run --title <t> --purpose discover | setup` | Run a one-off discovery or setup script |
clickruntime deploy <id> | Turn on a draft, or apply a pending change (the person confirms) | prepare_confirmation |
clickruntime run <id> | Run it now (the person confirms) | prepare_confirmation |
clickruntime resume <id> | Resume a paused automation (the person confirms) | prepare_confirmation |
clickruntime delete <id> | Delete it (the person confirms) | prepare_confirmation |
clickruntime wait <confirmation_ref> | Wait for the person to confirm, then for the deploy | get_confirmation_status, wait_for_deploy |
clickruntime pause <id> | Pause a live automation | pause_automation |
clickruntime runs <id> | Recent runs | list_runs |
clickruntime run-log <run_id> [--wait] | One run with its logs | get_run |
clickruntime events <id> | Events received on the trigger link | list_incoming_events |
clickruntime replay <id> <event_id> | Run again on a received event | replay_event |
clickruntime test-event <id> --file payload.json | Send a sample event | send_test_event |
clickruntime connections | Connected accounts and saved key names | list_connections |
clickruntime connect <app> | A consent link for the person to connect an account | begin_connection |
clickruntime apps | Apps with ready-made connections | list_app_catalog |
clickruntime docs runtime | The script reference | clickruntime://docs/runtime |
clickruntime docs cli | This guide, as markdown | — |
clickruntime <command> --help | Help for one command: its flags, JSON output and exit codes (add --json for JSON) | — |
| `clickruntime issue report | list | show |
deploy, run, resume and delete print a confirm link. Nothing happens until you open it and confirm. With --json they return straight away with exit code 4; clickruntime wait <confirmation_ref> then waits for your decision. Without --json they wait unless you pass --no-wait.
A project folder#
clickruntime init writes two files. clickruntime save sends them, and records the automation's id in clickruntime.json so the next save updates the same automation.
{
"name": "Morning status",
"summary": "Weekday mornings, email me the status page.",
"pattern": "schedule",
"schedule": { "kind": "weekdays", "time": "09:00", "timezone": "Europe/London" },
"how_it_works": { "steps": ["Reads the status page.", "Emails you what it says."] },
"setup_needs": [{ "kind": "connection", "provider": "email" }],
"dependencies": []
}
automation.py is the script. Read the script reference first, or run clickruntime docs runtime.
JSON output#
With --json the CLI prints one JSON object on stdout. Whenever you have to do something, it includes next:
{
"next": {
"action": "open_link",
"url": "https://clickruntime.com/confirm/…",
"say": "Open this link and press Turn on to confirm: Turns on Morning status."
}
}
say is one sentence the agent can repeat to you. Errors are {"error", "message", "next"} on stdout too. Tokens are never printed.
Exit codes#
| Code | Meaning |
|---|---|
| 0 | Done |
| 1 | Error |
| 2 | Usage error |
| 3 | Not signed in, or the sign-in ended |
| 4 | Waiting on you: a link was printed |
| 5 | Too many requests; retry later |
| 6 | You cancelled the confirmation, or it expired |
Settings#
| Setting | Default |
|---|---|
CLICKRUNTIME_TOKEN | Use this access token instead of the credentials file, for sandboxes and CI |
CLICKRUNTIME_API_URL | https://clickruntime.com/api/v1 |
CLICKRUNTIME_AUTH_URL | https://clickruntime.com (where clickruntime login signs in) |
CLICKRUNTIME_CONFIG_DIR | ~/.config/clickruntime (Windows: %APPDATA%\clickruntime) |
The sign-in is stored in credentials.json in that folder, readable only by you. Access tokens last an hour and the CLI refreshes them. There are no long-lived API keys.
Limits#
The CLI uses the same plan as everything else in your workspace, including on the free plan: its runs, deploys and AI tokens count toward the same monthly limits. See Pricing.