CLI Reference

View as Markdown

CLI Reference

The rocketride command-line tool starts pipelines, streams files through them, and manages the engine's file store — the same operations the SDKs expose, from a terminal. It ships with both the TypeScript and Python clients, so installing either package puts rocketride on your path.

Driving the engine from an AI assistant instead of a terminal? The MCP server exposes the same pipeline operations as tools for Claude, Cursor, and other MCP clients.

Python vs TypeScript CLI: Both packages ship a rocketride command with the same commands and flag names. Output is plain, line-oriented text; continuous live monitoring is deliberately not part of the CLI (the platform's monitor apps own that job).

Install

Install either SDK to get rocketride on your path:

Python SDKpip install rocketride — installs the CLI alongside the Python client.TypeScript SDKnpm install rocketride — installs the CLI alongside the Node.js client.

New to the CLI? Run from the CLI walks from a fresh install to a running pipeline in five steps; this page is the command reference.

Connecting

Every command accepts connection options, which also read from the environment so you can set them once:

Option	Env var	Default	Description
--uri <uri>	ROCKETRIDE_URI	Python: https://api.rocketride.ai; TypeScript: http://localhost:5565 (normalized to ws:// at connect time)	Engine endpoint (see Cloud / Self-hosting).
--apikey <key>	ROCKETRIDE_APIKEY	-	API token for authentication.
--pipeline <path>	ROCKETRIDE_PIPELINE	-	Default pipeline path for start/upload.
--token <token>	ROCKETRIDE_TOKEN	-	Default task token for token-bearing commands.

Against a Cloud endpoint use an https:///wss:// URI so the connection is encrypted.

Commands

Command	What it does
start	Start a new pipeline from a .pipe file and print its task token.
upload	Send files through a pipeline (by --pipeline or an existing task token).
stop	Stop a running task.
validate	Validate .pipe files against the engine without executing them.
list	List all active tasks.
store	File-store operations: dir, type, write, rm, mkdir, stat.

start

Use start to run a pipeline. The command loads the pipeline, starts the engine task, prints the task token, and exits; the task keeps running on the engine.

rocketride start --pipeline ./rag.pipe

# Start with extra worker threads (useful for CPU-bound nodes)
rocketride start --pipeline ./rag.pipe --threads 8

Key flags:

Flag	Description
--pipeline <path>	Path to the .pipe JSON file.
--threads <n>	Number of worker threads. Default 4.
--token <token>	Supply a custom task token for the new run (the server generates one if not provided). A pipeline file is still required; to find tasks that are already running, use list.

upload

Use upload when you need to push one or more files through a pipeline. The command starts a new pipeline task (or reuses one via --token), uploads each file, and streams results back.

rocketride upload --pipeline ./extract.pipe ./invoice.pdf

# Upload multiple files concurrently
rocketride upload --pipeline ./extract.pipe ./docs/*.pdf --max-concurrent 4

# Feed files into an already-running task
rocketride upload --token <task-token> ./report-q1.pdf ./report-q2.pdf

Key flags:

Flag	Description
--pipeline <path>	Path to the .pipe file. Required unless --token is given.
--token <token>	Send files to an existing task instead of starting a new one.
--max-concurrent <n>	Maximum number of files to upload in parallel. Default 5. TypeScript CLI only.

stop

Use stop to terminate a running task. This sends a stop signal to the engine, which cleanly shuts down the pipeline run.

rocketride stop --token <task-token>

The token is printed by start at the beginning of the run, and list shows the token of every active task. Save it if you need to stop a long-running pipeline later.

validate

Use validate to check one or more .pipe files against the engine without executing them — before deploying a pipeline, or as a CI gate on every pull request. Glob patterns are expanded by the CLI itself, so wildcards behave the same on Windows shells. Files must contain a JSON object — either the pipeline config itself or the { "pipeline": { ... } } wrapper that .pipe files use; a file that cannot be read or parsed is reported as invalid.

The engine checks structure and component references only — duplicate ids, unknown input/control lanes, dangling from references, a source that names no component. Provider availability and lane compatibility are runtime concerns and are not reported here.

# Validate a single pipeline
rocketride validate ./rag.pipe

# Validate every pipeline in a directory
rocketride validate ./pipelines/*.pipe

# Machine-readable report for CI
rocketride validate ./pipelines/*.pipe --json

Key flags:

Flag	Description
<files...>	One or more .pipe files or glob patterns.
--source <id>	Override the source component ID used for validation.
--json	Print a machine-readable JSON report (files + summary) to stdout.

Exit codes: 0 — all files valid; 1 — at least one file failed validation (a file that cannot be read or parsed counts as invalid); 2 — usage error, connection failure, or no file could be processed at all (no file received a server validation verdict).

Runs in CI too: the validate-pipes GitHub Action starts an engine container and runs rocketride validate on your repository's .pipe files.

list

Use list to display all active tasks for your account — handy when you have multiple pipelines running and need to find a task token.

rocketride list
rocketride list --json

Key flags:

Flag	Description
--json	Output results as JSON instead of human-readable text.

store

Use store to inspect or write files in the engine's built-in file store. This is useful for debugging pipeline outputs or seeding input data.

# List the root of the file store
rocketride store dir /

# List a subdirectory
rocketride store dir /pipeline-outputs

# Print the contents of a file
rocketride store type /pipeline-outputs/result.json

# Write a local file into the store
rocketride store write /pipeline-inputs/source.txt --file ./local-source.txt

# Write inline content without a local file
rocketride store write /pipeline-inputs/prompt.txt --content "Summarize this document"

# Delete a file from the store
rocketride store rm /pipeline-outputs/old-result.json

# Create a directory in the store
rocketride store mkdir /pipeline-outputs/archive

# Print metadata for a file or directory
rocketride store stat /pipeline-outputs/result.json

Sub-commands:

Sub-command	Description
dir <path>	List directory contents at <path>.
type <path>	Print the contents of the file at <path>.
write <path> --file <local>	Upload <local> to the store at <path>.
write <path> --content <text>	Write inline text to the store at <path>.
rm <path>	Delete a file from the store.
mkdir <path>	Create a directory in the store.
stat <path>	Print metadata (size, type, modified time) for <path>.

Related

• Run from the CLI: the five-step tutorial.
• TypeScript SDK · Python SDK: the same operations, in code.
• MCP server: the same operations, as AI-assistant tools.
• WebSocket protocol: what the CLI sends to the engine.
• Cloud · Self-hosting: where the engine runs.