Runchat Docs

@runchat/cli is a command-line interface for Runchat. It exposes the same canvas + workflow toolset as the MCP server — all commands (list_runchats, create_prompt_node, run_nodes etc) run from the shell, a script, or a CI job without an MCP client. Often the quickest way for a coding agent to build a workflow on its own. The CLI is self-describing. It lists its tools and reads each tool’s parameters live from the server.

Install

# 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

runchat login

This opens your browser to sign in to Runchat and approve the CLI, then saves a session that refreshes itself. It also works when a coding agent runs it — you just approve in the browser. Use --no-browser to print the sign-in URL instead, and --timeout <seconds> to change how long it waits (default 300).

runchat status   # who you're signed in as (exit 0 = signed in, exit 3 = not)
runchat logout   # remove saved credentials

API keys (CI and headless machines)

runchat login --paste               # opens runchat.com to create a key, then paste it
runchat login --api-key <key>       # save a key you already have
export RUNCHAT_API_KEY=<key>        # environment variable, nothing stored
runchat <tool> --api-key <key>      # per command

To create a key yourself, open runchat.com/dashboard?newkey=true, or the account menu → Get Runchat API Key. Precedence: --api-key flag > RUNCHAT_API_KEY > saved key > saved browser session. See auth.md for details.

Use with Claude Code

Install the Runchat skill so Claude Code knows to use the CLI whenever you mention Runchat:

npx @runchat/cli setup claude       # installs ~/.claude/skills/runchat

Or add it as a plugin from inside Claude Code:

/plugin marketplace add runchat-app/runchat.cli
/plugin install runchat@runchat

Then ask “use Runchat to build a workflow that …”. The first time, Claude runs runchat login and a sign-in page opens in your browser.

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

runchat login

# discover
runchat tools                                    # all tools, grouped
runchat create_prompt_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_prompt_node  --runchat_id "$ID" --label "Summarize" --prompt "Summarize the input"
runchat run_nodes           --runchat_id "$ID"   # spends credits — confirm first

run_nodes and execute_tool consume credits, just like in the app. Confirm before running anything with real cost.

Passing arguments

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

--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):

runchat create_prompt_node --json '{"runchat_id":"abc","prompt":"Summarize the input"}'

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

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:

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 or browser session. Set RUNCHAT_NO_BROWSER=1 to never open a browser.

Use it from an agent

The CLI ships an 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.

MCP Server

Connect Claude, ChatGPT, or Cursor to your canvas over the Model Context Protocol.

Canvas API

The same operations as a plain REST API.

Get Started

Plugins

Clipchat

Core Concepts

Node Reference

Examples

Command Line (CLI)

Install

Authenticate

API keys (CI and headless machines)

Use with Claude Code

Tool and command discovery

Quickstart

Passing arguments

Output & exit codes

Configuration

Use it from an agent

MCP Server

Canvas API

​Install

​Authenticate

​API keys (CI and headless machines)

​Use with Claude Code

​Tool and command discovery

​Quickstart

​Passing arguments

​Output & exit codes

​Configuration

​Use it from an agent

​Related

MCP Server

Canvas API

Install

Authenticate

API keys (CI and headless machines)

Use with Claude Code

Tool and command discovery

Quickstart

Passing arguments

Output & exit codes

Configuration

Use it from an agent

Related