> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runchat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Line (CLI)

> Build and run Runchat workflows from the terminal.

`@runchat/cli` is a command-line interface for Runchat. It is a faithful port of the [MCP server](/concepts/integrations/mcp) and allows all commands (`list_runchats`, `create_node`, `run_nodes` etc) to be run from the shell, a script, or a CI job without an MCP client.

The CLI is **self-describing**. It lists its tools and reads each tool's parameters live from the server.

## Install

```bash theme={null}
# one-off, always the latest version
npx @runchat/cli <command>

# or install globally
npm install -g @runchat/cli
runchat <command>
```

The npm package is `@runchat/cli`; the installed command is `runchat`. Requires Node.js ≥ 18.

## Authenticate

The CLI authenticates with a **Runchat API key** (or an OAuth access token: [auth.md](https://runchat.com/auth.md)).

<Steps>
  <Step title="Create a key">
    Sign in at [runchat.com](https://runchat.com), open the account menu → **Get Runchat API key**, and then create a new key or copy an existing one.
  </Step>

  <Step title="Provide it to the CLI">
    Any of these work, highest precedence first:

    ```bash theme={null}
    runchat <tool> --api-key rc_xxx     # per-command flag
    export RUNCHAT_API_KEY=rc_xxx       # environment variable
    runchat login                       # stores it in your user config
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    runchat status   # shows the server, your key (masked), and verifies it (exit 0 = authenticated)
    ```
  </Step>
</Steps>

## Tool and command discovery

You can list available tools (broadcast from the MCP server) and get help with the following commands:

| Command                 | What it shows                                         |
| ----------------------- | ----------------------------------------------------- |
| `runchat tools`         | Every tool, grouped, with a one-line description      |
| `runchat tools --json`  | Raw tool definitions (name, description, JSON schema) |
| `runchat <tool> --help` | One tool's full description and every parameter       |
| `runchat guide`         | The canonical Runchat workflow-building guide         |

Add `--refresh` to force-update the cached tool list. Run `guide` first when building a workflow. This explains node types, the create → connect → organize → run order, choosing models, code nodes, and publishing.

## Quickstart

```bash theme={null}
export RUNCHAT_API_KEY=rc_xxx

# discover
runchat tools                                    # all tools, grouped
runchat create_node --help                       # one tool's parameters

# workspace
runchat list_runchats --query invoice --limit 5
runchat create_runchat --name "My flow" --tags '["demo"]'

# canvas tools take --runchat_id
ID=<runchat_id>
runchat get_canvas  --runchat_id "$ID"
runchat create_node --runchat_id "$ID" --type promptNode --label "Summarize"
runchat run_nodes   --runchat_id "$ID"           # spends credits — confirm first
```

<Note>
  `run_nodes` and `execute_tool` consume credits, just like in the app. Confirm
  before running anything with real cost.
</Note>

## Passing arguments

Arguments are plain `--flags`, and values are **smart-typed** — numbers, booleans, and JSON arrays/objects are parsed; everything else stays a string:

```bash theme={null}
--limit 5                                 # number  → 5
--is_private true                         # boolean → true
--name "My flow"                          # string  → "My flow"
--tags '["a","b"]'                        # array   → ["a","b"]
--initial_data '{"code":["return 1"]}'    # object
```

Bare words stay strings (`--model gpt-5.5` → `"gpt-5.5"`) and id-like values are preserved (`--x 007` → `"007"`). Dashes and underscores in argument names are interchangeable (`--runchat-id` == `--runchat_id`).

Pass the whole argument object at once with `--json` (individual `--flags` override its keys):

```bash theme={null}
runchat create_node --json '{"runchat_id":"abc","type":"promptNode"}'
```

Read large values (code, prompts) from a file or stdin with `@`:

```bash theme={null}
runchat edit_file --runchat_id "$ID" --node_id n1 --new_text @app.js
cat app.js | runchat edit_file --runchat_id "$ID" --node_id n1 --new_text @-
```

## Output & exit codes

Results print as pretty JSON. Use `--raw` for the server's exact text — handy for piping into `jq`:

```bash theme={null}
ID=$(runchat create_runchat --name "Demo" --raw | jq -r .id)
```

| Code | Meaning                                         |
| ---- | ----------------------------------------------- |
| `0`  | success                                         |
| `1`  | the tool reported an error                      |
| `2`  | bad usage (unknown argument, missing tool name) |
| `3`  | authentication problem (no/invalid key)         |
| `4`  | network failure                                 |

## Configuration

| Variable             | Purpose                                             |
| -------------------- | --------------------------------------------------- |
| `RUNCHAT_API_KEY`    | API key (alias: `RUNCHAT_TOKEN`)                    |
| `RUNCHAT_BASE_URL`   | Override the server (default `https://runchat.com`) |
| `RUNCHAT_CONFIG_DIR` | Override where config + cache are stored            |

The config file lives at `%APPDATA%\runchat\config.json` (Windows) or `~/.config/runchat/config.json` (macOS/Linux) and stores your API key.

## Use it from an agent

The CLI ships an [`AGENTS.md`](https://github.com/runchat-app/runchat-cli/blob/main/AGENTS.md) so coding agents can drive it without prior knowledge: set `RUNCHAT_API_KEY`, run `runchat guide` then `runchat tools`, read `runchat <tool> --help` as needed, and branch on the exit codes above.

## Related

<CardGroup cols={2}>
  <Card title="MCP Server" icon="plug" href="/concepts/integrations/mcp">
    Connect Claude, ChatGPT, or Cursor to your canvas over the Model Context
    Protocol.
  </Card>

  <Card title="Canvas API" icon="code" href="/api-reference/canvas-tools">
    The same operations as a plain REST API.
  </Card>
</CardGroup>