> Documentation index for agents: https://docs.rocketride.ai/llms.txt

# CLI Reference

The `rocketride` command-line tool sets up a workspace, starts pipelines,
streams files through them, manages the engine's file store, profiles running
pipelines, and deploys pipelines and apps — 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 the Python package puts `rocketride` on your path, and the Node
package runs with `npx rocketride`.

> Driving the engine over MCP instead of a terminal? The
> [MCP server](/connect/mcp/http) exposes most pipeline operations as tools. Some commands are
> CLI-only, for example `init`, `login`, `diff`, `otel`, `profile`, `app` and the store write commands.

> **Python vs TypeScript CLI:** Both packages ship a `rocketride` command, but
> not the same set of commands. [`diff`](#diff) and `otel`, the
> [OpenTelemetry bridge](/clients/python/otel-bridge), ship with the Python
> package only. The Python package has only three [`app`](#app) sub-commands
> (`create`, `verify`, and `deploy`) and no `deploy source-config`. The
> [Commands](#commands) table notes each difference. Output is plain,
> line-oriented text; continuous live monitoring is deliberately not part of
> the CLI (the platform's monitor apps own that job) — `otel` forwards the
> engine's monitor stream to your own observability backend rather than
> rendering it in a terminal.

## Install

Install the Python package to get `rocketride` on your path (in a virtual
environment, while it is active). For Node, run it with `npx rocketride`;
`npm install rocketride` does not put it on your path:

- [Python SDK](/clients/python/): pip install rocketride — installs the CLI alongside the Python client.

- [TypeScript SDK](/clients/typescript/): npm install rocketride — installs the CLI alongside the Node.js client; run it with npx rocketride.

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 _except_ [`diff`](#diff) and [`app verify`](#app) — which run
entirely locally and never contact an engine — accepts connection options,
which also read from the environment so you can set them once:

| Option           | Env var                | Default               | Description                                                            |
| ---------------- | ---------------------- | --------------------- | ---------------------------------------------------------------------- |
| `--uri <uri>`    | `ROCKETRIDE_URI`       | `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.                                          |

Two task options read the environment the same way, on the commands that take
them: `--pipeline <path>` (`start` and `upload`) defaults to
`ROCKETRIDE_PIPELINE`, and `--token <token>` (`start`, `stop`, and `upload`)
defaults to `ROCKETRIDE_TOKEN`. A variable exported in your shell takes
precedence over the same one in `.env`.

Against a [Cloud](/operate/cloud) endpoint use an `https://`/`wss://` URI so the
connection is encrypted.

The `deploy` commands, and every `app` command except `create`, `dev`, and
`verify`, connect to the deployment target instead: `ROCKETRIDE_DEPLOY_URI` and
`ROCKETRIDE_DEPLOY_APIKEY`, which `init` and `login` write to `.env`. They
refuse to run when no deployment target is set, and when no deployment API key
is set: set `ROCKETRIDE_DEPLOY_APIKEY` or pass `--apikey`.

## Commands

| Command  | What it does                                                               |
| -------- | -------------------------------------------------------------------------- |
| `init`   | Sign in and set up a workspace: sync the component catalog and schemas, and install the platform packages and agent docs. |
| `login`  | Sign in again and save the credentials to `.env`.                          |
| `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.        |
| `diff`   | Semantic diff of two `.pipe` files, ignoring canvas noise. Local; no server. Python CLI only. |
| `list`   | List all active tasks.                                                     |
| `otel`   | Export live pipeline traces and metrics to an OpenTelemetry collector. Python CLI only. |
| `store`  | File-store operations: `dir`, `type`, `write`, `rm`, `mkdir`, `stat`.     |
| `profile` | Find where the server or a running pipeline spends its time.             |
| `app`    | Create, preview, check, deploy, and publish apps. The Python CLI has only `create`, `verify`, and `deploy`. |
| `deploy` | Version pipelines in the server's registry, point teams at a version, and schedule runs. `source-config` is TypeScript CLI only. |

### init and login

Run `init` once per workspace, and again whenever the server changes. It signs
you in, syncs the services catalog and schemas into `.rocketride/`, vendors the
platform packages, installs the agent docs, and adds `.rocketride/` and `.env`
to `.gitignore`. Run `login` when a command reports rejected credentials.

```bash
# Set up a workspace against RocketRide Cloud
rocketride init --uri https://api.rocketride.ai

# Sign in again
rocketride login

# Sign in without a browser, from CI or an agent
rocketride login --apikey <key>
```

Against RocketRide Cloud, signing in opens your browser and mints a personal API
key. A self-hosted server takes an API key, from `--apikey` or a
prompt. The credentials go to `.env` as the development pair. They also go to
the deployment pair, unless you pass `--no-deploy` or `.env` already has a
deployment pair for a different server, which both commands leave alone.
`init` writes credentials only when it signs you in. If the development pair
already in `.env` works, `init` reuses it and writes nothing. To set or change
the deployment pair in either case, run `rocketride login --deploy --uri <uri>`.

Without `--apikey`, `login` first tries the development key from `.env` or your
shell. If the server rejects that key, for example after a command reports
rejected credentials, pass a valid key with `--apikey <key>`. Or pass
`--apikey ""` to sign in through the browser instead, or to be prompted for a
key on a self-hosted server. If you exported `ROCKETRIDE_APIKEY` in your shell,
unset it afterwards, because it takes precedence over the new key in `.env`.
With `--deploy`, also pass the deployment server's `--uri`, because `--uri`
defaults to `ROCKETRIDE_URI`, the development server.

Key flags:

| Flag | Description |
| --- | --- |
| `--apikey <key>` | Save this key instead of signing in through the browser. |
| `--deploy` | On `login`, sign in for the deployment pair (`ROCKETRIDE_DEPLOY_*`) instead of the development pair. On `init` (TypeScript CLI only), also use this server as the deployment target, which `init` does by default. |
| `--no-deploy` | Do not write the deployment pair. |
| `--no-install` | `init` only. Skip the workspace `pnpm install`. |

### 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. The Python CLI accepts this flag but ignores it. |

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

### diff

Use `diff` to see what actually changed between two versions of a `.pipe` file.
A raw `git diff` of a pipeline is dominated by **canvas coordinate churn** —
every time you nudge a node, its `ui.position` `x`/`y` values change, and the
top-level `viewport` shifts when you pan or zoom. Those lines say nothing about
behavior, yet they bury the changes that do: a swapped LLM provider, a re-tuned
chunk size, a rewired retrieval step. `diff` computes a **semantic** diff
instead — it groups changes into **Nodes** (added / removed / re-provisioned),
**Edges** (the wiring between components), and **Config** (per-field changes as
readable dotted paths) — and collapses all layout churn into a single line.

> **Local only — no engine, no auth.** Unlike every other command, `diff` never
> connects to an engine or the network: it reads files (or a git ref) and
> compares parsed JSON entirely on your machine. It therefore takes **none** of
> the `--uri` / `--apikey` / `--token` connection options the other commands
> share. Python CLI only.

> The [Pipeline Diff](/clients/python/pipe-diff) guide covers the same command in
> depth, plus the importable `rocketride.pipediff` API behind it.

```bash
# Compare two files on disk (old, then new)
rocketride diff old.pipe new.pipe

# Compare a working-tree file against a git ref (uses `git show <ref>:<file>`)
rocketride diff --git HEAD rag.pipe
rocketride diff --git main rag.pipe

# Machine-readable output
rocketride diff old.pipe new.pipe --json
rocketride diff old.pipe new.pipe --markdown

# Include the layout churn that is hidden by default
rocketride diff old.pipe new.pipe --include-layout
```

Key flags:

| Flag | Description |
| --- | --- |
| `<old.pipe> <new.pipe>` | The two files to compare (positional). Omit one and pass `--git` instead. |
| `--git <ref>` | Diff the single working-tree `FILE` against `<ref>` via `git show <ref>:<FILE>`, looking the file up under the path given. `<ref>` must not be empty. If the file does not exist in `<ref>`, everything is reported as added, plus a version change from `null` when the file has a `version`, and `layout changed` when its `viewport` is non-empty. A symlink committed as a symlink — the file itself or any directory on its path — is compared through the target it had at `<ref>`, wherever it points today. An absolute target inside the checkout, or one that climbs out of the repository and back in through its root (`../<repo>/x.pipe`), is read at `<ref>` like any other link; a target that ends outside the repository, or a loop of links, is an error. On POSIX systems `lnk/../x` follows `lnk` as it was committed at `<ref>`, and a relative `FILE` typed inside a directory link is looked up under the link as the shell spells it (`$PWD`). On a case-insensitive filesystem, a differently cased spelling of a tracked file or of any directory on its path is compared against that file. |
| `--include-layout` | Enumerate the layout churn that is hidden by default — each node's `ui` block as `ui.*` changes on that node, and the top-level `viewport` as `viewport.*` changes — and count it, so a layout-only edit then exits `1`. |
| `--json` | Emit a single JSON document to stdout (mutually exclusive with `--markdown`). |
| `--markdown` | Emit compact, PR-comment-friendly Markdown to stdout (mutually exclusive with `--json`). |
| `--exit-zero` | Always exit `0` on a successful run, even when changes are found. Use for informational, non-gating runs. |

Exit codes: `0` — no semantic changes (or any successful run when `--exit-zero`
is set); `1` — semantic changes were found; `2` — usage error, or an unreadable
/ unparseable file or bad git ref. `diff` reads no configuration and does not
load the workspace `.env`, so a `NO_COLOR` set only there is ignored; one in the
shell environment still disables color.

Non-JSON constants (`NaN`, `Infinity`, `-Infinity`), numeric overflow, and
nonzero underflow are input errors (exit `2`). Fractional and exponent literals
use finite IEEE 754 binary64 precision, so literals that round to the same
binary64 value compare equal; integer literals remain exact within the JSON
decoder's size limit. These rules also apply to Git blobs. Excessive nesting
that exceeds parsing, comparison, or reporting limits returns an actionable
error on stderr with exit `2` and empty stdout. `--exit-zero` does not suppress
errors. Each error `diff` reports is one line, with control, bidi, invisible and
line-separator characters taken from the inputs written as `\xNN`/`\uNNNN` escapes.

#### What counts as a change

- **Nodes** are matched by `id`. A new or deleted `id` is an add/remove; an `id`
  present on both sides with a different `provider` is a provider change.
  Providers and config values are compared as JSON values: a boolean never
  equals a number and a string never equals either, so `0` → `false` is a
  change, while numerically equal literals such as `512` and `512.0` compare
  equal.
- **Config** is deep-diffed into dotted paths — nested objects become
  `config.default.strlen`, list items become `config.instructions[0]` — and each
  leaf is reported as added, removed, or changed with its old → new value.
- **Edges** are the directed wires between components, reconstructed from every
  component's `input[]` (data lanes) and `control[]` (agent orchestration lanes,
  such as an agent's `llm`, `tool`, or `memory`). Rewiring a step shows up as a
  removed edge plus an added edge.
- **Version** changes (the top-level `version` field) are always reported and
  always count as a change — they are never hidden.
- **Layout** — each node's `ui` block and the `viewport` — is ignored by default
  and summarized as a single `Layout: changed` line. A pure canvas move is **not**
  a semantic change, so `diff` exits `0` on it. Pass `--include-layout` to
  enumerate the individual `ui.*` coordinates and `viewport.*` fields; with the
  flag they count as changes, so a canvas-only edit exits `1`.
- **Canvas groups.** The editor saves a group's children inside the group,
  under `config.pipeline.components`. Each child is diffed as a node in its own
  right, matched by `id`: its `ui` is layout, its wiring is edges, and its
  provider and config changes are reported on the child. Moving a node into or
  out of a group is layout.
- **Everything else at the top level is ignored.** `diff` reads exactly
  `components`, `version` and `viewport`; `project_id`, `isLocked`, and any key a
  later schema adds are editor/session metadata, so editing one never reports a
  change.

#### Output modes

The default **human** output is grouped and colored (color auto-disables when
piped or when `NO_COLOR` is set), with `+` added, `-` removed, and `~` changed:

```text
Pipeline diff: 1 node changed, layout changed

Config
  chunker_1
    ~ config.default.strlen: 512 -> 1024

Layout: changed (ui/viewport)
```

`--json` emits one stable document with sorted keys — `edges`, `nodes`, a
`summary` block with counts and the overall `has_semantic_changes` flag, and
`viewport` — ideal for feeding another tool:

```json
{
  "edges": { "added": [], "removed": [] },
  "nodes": {
    "added": [],
    "changed": [
      {
        "config_changes": [
          { "kind": "changed", "new": 1024, "old": 512, "path": "config.default.strlen" }
        ],
        "id": "chunker_1",
        "provider_change": null
      }
    ],
    "removed": []
  },
  "summary": {
    "config_changes": 1,
    "edges_added": 0,
    "edges_removed": 0,
    "has_semantic_changes": true,
    "layout_changed": true,
    "nodes_added": 0,
    "nodes_changed": 1,
    "nodes_removed": 0,
    "provider_changes": 0,
    "version_change": null,
    "viewport_changes": 0
  },
  "viewport": []
}
```

The top-level `viewport` array carries the same
`{"path", "kind", "old", "new"}` shape as a config change and is populated only
under `--include-layout`; `summary.viewport_changes` is its length.

`--markdown` emits a compact, PR-comment-friendly report — a one-line summary,
bullet lists for nodes and edges, and a table for config changes (with `|`,
backticks, and control, bidi, zero-width and non-ASCII space characters escaped so
untrusted values can't break, reorder or hide anything in the comment):

```markdown
**Pipeline diff:** 1 node changed, layout changed

**Config**

| Node | Field | Change |
| --- | --- | --- |
| `chunker_1` | `config.default.strlen` | `512` → `1024` |

_Layout (ui/viewport) changed._
```

#### Review pipelines like code in CI

Because `diff` is local and exits non-zero on change, it drops straight into a
pull-request check. The supported way to wire it up is the bundled
[`pipe-diff` composite action](https://github.com/rocketride-org/rocketride-server/tree/develop/.github/actions/pipe-diff),
which finds every changed `.pipe`, diffs each against the merge base with the
pull request's base branch, and posts one
**sticky** comment so reviewers see "OpenAI → Anthropic, chunk size 512 → 1024,
retrieval rewired through a reranker" instead of a wall of coordinate noise:

```yaml
# .github/workflows/pipe-diff.yml
name: Pipeline diff
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  diff:
    runs-on: ubuntu-latest
    steps:
      # default fetch-depth: 1 is fine; the action fetches the base itself
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
      - uses: rocketride-org/rocketride-server/.github/actions/pipe-diff@develop
```

Every `uses:` runs with the job's token, so pin each one to a full commit SHA
(the `# v4` comment keeps it readable) instead of a mutable tag or branch — a
retagged action changes what your job executes. Pin `@develop` to a tag or commit
SHA the same way once the action is released. The `./`-relative
form (`uses: ./.github/actions/pipe-diff`) works only inside the
`rocketride-server` repository itself, where the action lives on disk.

The action installs the CLI, resolves the merge base, and maintains a single
sticky comment for you. See its
[README](https://github.com/rocketride-org/rocketride-server/blob/develop/.github/actions/pipe-diff/README.md)
for the `files`, `cli-version`, `install-from`, `comment`, and `include-layout`
inputs.

> **Fork pull requests:** on a `pull_request` event from a fork, GitHub hands the
> job a read-only `GITHUB_TOKEN` no matter what `permissions:` says, so the
> comment API returns `403`. The action warns rather than failing, and every run
> also writes the full report to the job summary — so the diff stays visible. Set
> `comment: false` to skip the API call entirely, or use `pull_request_target`
> for a writable token — the action comments on that event too, but never check
> out or run the PR head's code from that workflow: the action then diffs the
> base branch against itself, reports no changes and warns. To comment on fork
> PRs, compute on `pull_request` and post from a `workflow_run` workflow.

> **Before the CLI release:** `rocketride diff` is not in a PyPI release yet —
> 1.4.0 and earlier do not include it; the first release with it will be 1.5.0
> or later. Until then, set `install-from` to a pip source
> that does provide the subcommand. Inside `rocketride-server` that is the
> checkout itself (`install-from: ./packages/client-python`); from any other
> repository it is this repository's client package at a pinned commit:
> `install-from: 'git+https://github.com/rocketride-org/rocketride-server@<full-commit-sha>#subdirectory=packages/client-python'`.
> pip executes the source's build code, so pin a full SHA rather than a branch.

If you would rather not vendor the composite action, the same result can be
assembled inline — check out with `fetch-depth: 0` so the base branch is present
for `--git`, then diff and post the Markdown yourself:

```yaml
# Alternative: inline equivalent of the composite action, for a single file.
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          fetch-depth: 0 # need the base branch for `git show`
      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
        with:
          python-version: "3.12"
      # `rocketride diff` is not in a PyPI release yet (1.4.0 and earlier lack
      # it), so `pip install rocketride` would install a CLI without the
      # subcommand and the next step
      # would fail with "invalid choice: 'diff'". Until that release, install the
      # client package straight from this repository at a pinned commit; pip runs
      # the source's build code, so pin a full SHA, never a branch. Afterwards
      # switch to the published release: pip install "rocketride==<release>".
      - run: >-
          pip install
          "rocketride @ git+https://github.com/rocketride-org/rocketride-server@<full-commit-sha>#subdirectory=packages/client-python"
      - name: Semantic diff of the pipeline
        run: |
          set -o pipefail  # keep an exit-2 input error from being masked by tee
          rocketride diff --git "origin/${{ github.base_ref }}" rag.pipe \
            --markdown --exit-zero | tee pipe-diff.md
      - name: Comment on the PR
        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2.9.4
        with:
          path: pipe-diff.md
```

This is the review half of the "pipelines as code" story: [`validate`](#validate)
a `.pipe` to confirm it is well-formed before it runs, and `diff` it to review
exactly what changed between revisions — the same lint / review loop teams
already run on their source, now applied to their pipelines. See the
[side-by-side example](https://github.com/rocketride-org/rocketride-server/blob/develop/examples/pipe-diff-example.md)
for the full before/after contrast and the PR-comment recipe.

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

### otel

Use `otel` to export live pipeline traces and metrics to any OpenTelemetry
collector over OTLP — Jaeger, Grafana Tempo, Datadog, Langfuse, LangSmith, or
anything else that speaks OTLP. The command is a pure consumer of the engine's
[monitor event stream](/connect/websocket/observability): it subscribes to all
tasks your API key owns and maps lifecycle, flow, and status events to OTel
spans and metrics. It runs until interrupted (Ctrl+C), closing open spans and
flushing exporters on shutdown.

```bash
# Requires the optional OpenTelemetry extra
pip install 'rocketride[otel]'

# Export to a local collector (default endpoint http://localhost:4318)
rocketride otel

# Export to a specific backend — pass auth via the env var so the secret
# stays out of shell history and process listings
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${AUTH_VALUE}"
rocketride otel --endpoint https://cloud.langfuse.com/api/public/otel --no-metrics

# Include pipeline payload content in spans (excluded by default, 8 KB cap)
rocketride otel --include-content
```

Key flags:

| Flag | Description |
| --- | --- |
| `--endpoint <url>` | OTLP base URL; `/v1/traces` and `/v1/metrics` are appended automatically. Defaults to `OTEL_EXPORTER_OTLP_ENDPOINT`, honoring the signal-specific `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` variables when neither is set, else the exporter default (`http://localhost:4318` for http, `localhost:4317` for grpc). |
| `--protocol <http\|grpc>` | OTLP transport. Default `http` (http/protobuf); `grpc` needs the separate gRPC exporter package. |
| `--service-name <name>` | `service.name` resource attribute. Defaults to `OTEL_SERVICE_NAME` or `rocketride-engine`. |
| `--headers <k=v,k=v>` | Headers sent with every OTLP request. Prefer `OTEL_EXPORTER_OTLP_HEADERS` for secrets — command-line arguments are visible in shell history and `ps` output. |
| `--include-content` | Include pipeline payload content in spans, size-capped. By default no payload content is exported. |
| `--no-metrics` | Export traces only. |
| `--insecure` | Allow credential-bearing OTLP headers over cleartext transport to a non-loopback collector. Without it the bridge exits `2` rather than putting an `Authorization` / `x-api-key` value on the wire in the clear. Also settable with `ROCKETRIDE_OTEL_ALLOW_INSECURE=1`. |

Per-component flow spans appear only for runs started with a
`pipelineTraceLevel` (e.g. `client.use(..., pipelineTraceLevel='summary')`) —
the bridge cannot change the trace level of runs it did not start. Task
lifecycle spans and metrics are exported regardless.

> Available in the Python CLI only. Requires `pip install 'rocketride[otel]'`.
> The [OpenTelemetry bridge](/clients/python/otel-bridge) guide covers the span
> model, the exported attributes, and per-backend recipes; the
> [WebSocket Events](/connect/websocket/observability) page documents the
> underlying event stream.

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

### profile

Use `profile` to find where the time goes. With `--token`, it profiles the
engine subprocess that runs that task's nodes. Without `--token`, it profiles
the server process. Here `--token` does not read `ROCKETRIDE_TOKEN`.

```bash
# Profile a running pipeline for 30 seconds, then read the call tree
rocketride profile run --token <task-token> --duration 30
rocketride profile tree --token <task-token>

# Profile the server process until Ctrl+C
rocketride profile run
```

Sub-commands:

| Sub-command | Description |
| --- | --- |
| `start --token <token>` | Start a session on a task and return at once. |
| `stop --token <token>` | Stop the session. Its results stay readable. |
| `run` | Start a session, wait for Ctrl+C or `--duration <seconds>`, then stop it. |
| `status` | Show the active session, or whether a report exists. |
| `list` | Show the same for the server process and every task. `--active` lists only the processes being profiled. |
| `report` | Print a text report of the last completed session. |
| `threads` | List threads, busiest first. |
| `tree` | Print the call tree of the last completed session. `--thread <id>`, `--min-pct <n>`, `--max-depth <n>`, and `--no-include-system` trim it. |

### app

Use `app` to build and ship apps from a terminal, with the same steps as the
[App Builder](/guides/apps/app-builder). The Python CLI has only `create`,
`verify`, and `deploy`, and its `verify` has no `--store` and its `deploy` has
no `--publish`. The other sub-commands need the TypeScript CLI
(`npx rocketride`).

```bash
rocketride app create clock                 # scaffold ./apps/clock-ui
rocketride app dev clock --open             # live preview that updates on every save
rocketride app verify clock                 # check the app without deploying it
rocketride app deploy clock --publish @me   # deploy, wait for the server build, publish to yourself
rocketride app versions clock
```

`[app]` is an app folder, an app id, the app's name, or nothing for the
current directory. In the Python CLI, `verify` and `deploy` take only an app
folder, and it is required.

Sub-commands:

| Sub-command | Description |
| --- | --- |
| `create <slug>` | Scaffold a new app under `./apps/<slug>-ui`. |
| `dev [app]` | Serve a live preview. `--open` opens it in your browser. |
| `verify [app]` | Check the manifest, the declared assets, and the pack size. Needs no connection. `--store` adds the public store-submission checks. |
| `deploy [app]` | Pack the source and deploy it as the next registry version. `--publish <target>` waits for the server build and publishes the new version. |
| `publish [app] [version]` | Publish a version to `--to @me` (the default), `@team/<name>`, or `@public`. |
| `unpublish [app]`, `disable [app]` | Stop serving the audience given by `--from`. `disable` keeps it listed, switched off. |
| `versions [app]` | List versions, newest first, with build status and audiences. |
| `where [app]` | Show which audiences serve which version. |
| `log [app] [version]` | Print a version's server build log. |
| `submit [app] [version]`, `withdraw [app] [version]` | Enter or leave public store review. |
| `reply [app] [version] -m <text>` | Post on the store review thread. |
| `developer status`, `developer register <id>` | Show or register your organization's developer id. |

### deploy

Use `deploy` to version pipelines in the server's registry, point teams at a
version, and schedule runs. `--team` takes `@me`, a team name, or a team id.

```bash
rocketride deploy add pipelines/ingest.pipe --comment "v2 parse"   # next registry version
rocketride deploy publish <projectId> 3 --team @me                  # point a team at version 3
rocketride deploy schedule set <projectId> <sourceId> "0 9 * * 1-5" --team @me
rocketride deploy list
```

Sub-commands:

| Sub-command | Description |
| --- | --- |
| `add <file>` | Deploy a `.pipe` file as the next registry version. `--deploy-to <team>` also points that team at it. |
| `list` | List deployments. |
| `get <project>` | Show one deployment's state and schedules. |
| `versions <project>` | List registry versions. |
| `history <project>` | Show the deploy and publish audit trail. |
| `publish <project> <version>` | Point a team at a version. |
| `run <project> <source>` | Run a source now. |
| `artifact <project> <version>` | Print one version's artifact JSON. |
| `enable <project>`, `disable <project>`, `remove <project>` | Switch a deployment on or off, or remove it. Versions and history survive `remove`. |
| `schedule set <project> <source> <cron>` | Set a source's schedule (five-field cron), or `none` to clear it. `--ttl <seconds>` sets a fixed run window. |
| `schedule pause <project> <source>`, `schedule resume <project> <source>` | Pause or resume a schedule. |
| `schedule preview <cron>` | Check a cron expression and list its next firings. |
| `source-config <project> <source>` | Set a source's run settings, such as `--trace-level`. TypeScript CLI only. |
| `log <appId> <version>` | Print an app version's server build log. |

## 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/http): most of the same operations, as MCP tools.
- [WebSocket protocol](/connect/websocket): what the CLI sends to the engine.
- [Cloud](/operate/cloud) · [Self-hosting](/operate/self-hosting): where the engine runs.
