Skip to content
Docs menu · CLI

Guides

Reference

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.

CommandWhat it doesMCP tool
clickruntime statusSigned in? Which workspace?get_profile
clickruntime login [--device] [--no-wait]Sign in (the person approves in the browser)—
clickruntime logoutEnd this sign-in—
`clickruntime init <name> --pattern scheduleincomingremember_then_schedule`
clickruntime saveSave the local files as a draft, or update itsave_draft, update_draft, change_automation
clickruntime pull <id>Download an automation's script and settingsget_automation, get_script
clickruntime listList automationslist_automations
clickruntime show <id>One automationget_automation
clickruntime setup <id>Setup steps left, each with its linkget_setup_status
`clickruntime setup run --title <t> --purpose discoversetup`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 deployget_confirmation_status, wait_for_deploy
clickruntime pause <id>Pause a live automationpause_automation
clickruntime runs <id>Recent runslist_runs
clickruntime run-log <run_id> [--wait]One run with its logsget_run
clickruntime events <id>Events received on the trigger linklist_incoming_events
clickruntime replay <id> <event_id>Run again on a received eventreplay_event
clickruntime test-event <id> --file payload.jsonSend a sample eventsend_test_event
clickruntime connectionsConnected accounts and saved key nameslist_connections
clickruntime connect <app>A consent link for the person to connect an accountbegin_connection
clickruntime appsApps with ready-made connectionslist_app_catalog
clickruntime docs runtimeThe script referenceclickruntime://docs/runtime
clickruntime docs cliThis guide, as markdown—
clickruntime <command> --helpHelp for one command: its flags, JSON output and exit codes (add --json for JSON)—
`clickruntime issue reportlistshow

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#

CodeMeaning
0Done
1Error
2Usage error
3Not signed in, or the sign-in ended
4Waiting on you: a link was printed
5Too many requests; retry later
6You cancelled the confirmation, or it expired

Settings#

SettingDefault
CLICKRUNTIME_TOKENUse this access token instead of the credentials file, for sandboxes and CI
CLICKRUNTIME_API_URLhttps://clickruntime.com/api/v1
CLICKRUNTIME_AUTH_URLhttps://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.