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

Group	What it covers
auth	log in / out, register, profile (profile, profile-update, change-password, set-email, set-avatar), API keys
config	local profiles (list, show, set, use)
org	organizations (list, create, invite, accept)
project	projects, scope switching, project config, share links
session	sessions, blocks, events
memory	memory entries, search, commit tasks
sandbox	sandboxes, exec, code, files, logs
agent	agent definitions, versions, prompts, runs, attachments
asset	assets, versions, credentials, publish
billing	subscription, usage, invoices
workflow	workflows (list, get, create, delete, counts)
admin	platform administration (platform admins only)
mcp	an MCP server on stdio, for Codex / Claude and other MCP clients

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

Variable	Meaning
RATHFLOW_BASE_URL	Gateway address
RATHFLOW_PROJECT	Project scope
RATHFLOW_TOKEN	Bearer token / API key
RATHFLOW_CONFIG_DIR	Config directory

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 (ALL_PROXY, HTTPS_PROXY, …). SOCKS proxies need socksio, which ships in the socks extra:

uv tool install 'rathflow-cli[socks]'

Clash and similar desktop setups often export ALL_PROXY=socks://.... httpx only understands socks5:///socks5h://, so the CLI rewrites that scheme for you (and maps socks4:// to socks5h://, because httpx has no SOCKS4). Nothing to configure — just install the extra.

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.