---
title: CLI Reference
---

import { SiPython, SiTypescript } from 'react-icons/si';

# 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](/clients/typescript) expose, from a terminal. It ships with both the
[TypeScript](/clients/typescript) and [Python](/clients/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](/connect/mcp/stdio) 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:

<div className="rr-card-grid">

<a className="rr-side-card" href="/clients/python">
  <span className="rr-side-card__head"><SiPython className="rr-card-icon" /><span className="rr-side-card__title">Python SDK</span></span>
  <span className="rr-side-card__body"><code>pip install rocketride</code> — installs the CLI alongside the Python client.</span>
</a>

<a className="rr-side-card" href="/clients/typescript">
  <span className="rr-side-card__head"><SiTypescript className="rr-card-icon" /><span className="rr-side-card__title">TypeScript SDK</span></span>
  <span className="rr-side-card__body"><code>npm install rocketride</code> — installs the CLI alongside the Node.js client.</span>
</a>

</div>

New to the CLI? [Run from the CLI](/quickstart/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](/operate/cloud) / [Self-hosting](/operate/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](/operate/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.

```bash
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.

```bash
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.

```bash
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.

```bash
# 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](https://github.com/rocketride-org/rocketride-server/tree/develop/.github/actions/validate-pipes)
> 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.

```bash
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.

```bash
# 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](/quickstart/cli): the five-step tutorial.
- [TypeScript SDK](/clients/typescript) · [Python SDK](/clients/python): the
  same operations, in code.
- [MCP server](/connect/mcp/stdio): the same operations, as AI-assistant tools.
- [WebSocket protocol](/connect/websocket): what the CLI sends to the engine.
- [Cloud](/operate/cloud) · [Self-hosting](/operate/self-hosting): where the engine runs.