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

The CLI authenticates with a Runchat API key (or an OAuth access token: auth.md).

Create a key

Sign in at runchat.com, open the account menu → Get Runchat API key, and then create a new key or copy an existing one.

Provide it to the CLI

Any of these work, highest precedence first:

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

Verify

runchat status   # shows the server, your key (masked), and verifies it (exit 0 = authenticated)

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

export RUNCHAT_API_KEY=rc_xxx

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

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

Tool and command discovery

Quickstart

Passing arguments

Output & exit codes

Configuration

Use it from an agent

MCP Server

Canvas API

​Install

​Authenticate

​Tool and command discovery

​Quickstart

​Passing arguments

​Output & exit codes

​Configuration

​Use it from an agent

​Related

MCP Server

Canvas API

Install

Authenticate

Tool and command discovery

Quickstart

Passing arguments

Output & exit codes

Configuration

Use it from an agent

Related