# 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](/docs/agents) and the [API](/docs/api).

## Install

```bash
npx clickruntime status
```

Node.js 18 or later. Or install it with Python 3.9 or later:

```bash
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

```bash
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:

```bash
clickruntime login --device
```

It prints a link and a code like `BCDF-GHJK`. Open [clickruntime.com/device](/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` | Write automation.py and clickruntime.json | — |
| `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 | `run_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|reply` | Support issues | `report_issue`, `list_issues`, `get_issue`, `add_issue_message` |

`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.

```json
{
  "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](/docs/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`:

```json
{
  "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](/pricing).
