rathflow-cli

The RathFlow command line client. It talks to the RathFlow northbound REST API and covers sessions, memory, sandboxes, agents, assets, projects, billing and workflows. Two implementations ship from this repository — Python (rathflow_cli/) and Node.js (node/) — with the same commands, options, output and exit codes. They share one config file, so you can switch between them freely.

Install

Python (3.10+):

uv tool install rathflow-cli
# or
pipx install rathflow-cli
# or
pip install rathflow-cli

Node.js (20+):

npm install -g rathflow-cli

Both install a rathflow command; install only one globally, or call the other by path. The two packages are released together from the same v* tag.

Releasing both packages is documented in RELEASING.md.

Quick start

# Log in with your email and password (the password prompt does not echo).
rathflow auth login -e you@example.com

# Who am I, what can I reach.
rathflow whoami

# Pick a project scope; every later command carries it.
rathflow project list
rathflow project use <project_id>

# Read something.
rathflow session list

The default gateway is https://rathflow.lynwe.com. Point it elsewhere with --base-url, RATHFLOW_BASE_URL, or rathflow config set base_url <url>.

Commands

Two more entry points sit at the root:

• rathflow whoami — identity, scope and reachable projects.
• rathflow api <Key> — call any endpoint directly; rathflow api --list prints the whole table. Streaming endpoints stream.

Every group has --help, e.g. rathflow session --help.

MCP

rathflow mcp serve runs an MCP server on stdio so an MCP client can drive RathFlow through the tools instead of a shell. Register it with the client, for example in .mcp.json:

{ "mcpServers": { "rathflow": { "command": "rathflow", "args": ["mcp", "serve"] } } }

It exposes 14 read tools, plus 5 write tools once RATHFLOW_MCP_WRITE=1 is set in the server's environment. Anything without a named tool is still reachable via rathflow_endpoints (the endpoint table) and rathflow_api_call. Authentication is the same as the CLI's: run rathflow auth login once, and the server refreshes the token as it goes.

mcp serve is available in the Python package only for now — the Node CLI has not been ported yet.

Authentication

rathflow auth login exchanges your email and password for a JWT, stored in the CLI config file (mode 0600). The CLI sends it as a Bearer token and never touches cookies, so it is unaffected by the browser CSRF rules.

For unattended use, issue a long-lived API key and pass it through the environment:

rathflow auth key-create          # prints the key once, right here
export RATHFLOW_TOKEN=rf_...      # or: rathflow config set token rf_...

Configuration

Precedence, highest first: command-line flag > environment variable > active profile > built-in default. Profiles live in ~/.config/rathflow/config.json (override the directory with RATHFLOW_CONFIG_DIR).

Output

• Default: human-readable tables.
• --json: one stable JSON document, for scripts.
• --quiet / -q: primary keys only.

Exit codes are stable: 0 success, and non-zero for usage errors, API errors and remote command failures (a sandbox exec returns the remote exit code).

Proxies

The CLI respects the standard proxy variables. One caveat: httpx cannot use a SOCKS proxy unless socksio is installed. If your environment sets ALL_PROXY=socks://... (some Clash setups do), install the extra or the CLI fails to start with Unknown scheme for proxy URL:

uv tool install 'rathflow-cli[socks]'
# or clear it for this command only
ALL_PROXY= rathflow whoami

Development

uv venv --python 3.12 .venv
uv pip install -e .
.venv/bin/rathflow --help
.venv/bin/python -m rathflow_cli.selftest

selftest checks that no command hard-codes a URL and, when the upstream generated endpoint table is available (RATHFLOW_ENDPOINTS_TS), that rathflow_cli/endpoints.py still matches it.

License

MIT — see LICENSE.