Skip to main content
@runchat/cli is a command-line interface for Runchat. It is a faithful port of the MCP server 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

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

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

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
3

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:
CommandWhat it shows
runchat toolsEvery tool, grouped, with a one-line description
runchat tools --jsonRaw tool definitions (name, description, JSON schema)
runchat <tool> --helpOne tool’s full description and every parameter
runchat guideThe 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_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
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_node --json '{"runchat_id":"abc","type":"promptNode"}'
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)
CodeMeaning
0success
1the tool reported an error
2bad usage (unknown argument, missing tool name)
3authentication problem (no/invalid key)
4network failure

​
Configuration

VariablePurpose
RUNCHAT_API_KEYAPI key (alias: RUNCHAT_TOKEN)
RUNCHAT_BASE_URLOverride the server (default https://runchat.com)
RUNCHAT_CONFIG_DIROverride 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.