Skip to main content

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, with two exceptions that ship with the Python package only: diff and otel, the OpenTelemetry bridge. 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 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 except diff — which runs entirely locally and never contacts an engine — accepts connection options, which also read from the environment so you can set them once:

OptionEnv varDefaultDescription
--uri <uri>ROCKETRIDE_URIPython: 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​

CommandWhat it does
startStart a new pipeline from a .pipe file and print its task token.
uploadSend files through a pipeline (by --pipeline or an existing task token).
stopStop a running task.
validateValidate .pipe files against the engine without executing them.
diffSemantic diff of two .pipe files, ignoring canvas noise. Local; no server. Python CLI only.
listList all active tasks.
otelExport live pipeline traces and metrics to an OpenTelemetry collector. Python CLI only.
storeFile-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:

FlagDescription
--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:

FlagDescription
--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:

FlagDescription
<files...>One or more .pipe files or glob patterns.
--source <id>Override the source component ID used for validation.
--jsonPrint 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.

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 guide covers the same command in depth, plus the importable rocketride.pipediff API behind it.

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

FlagDescription
<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>. If the file does not exist in <ref>, everything is reported as added.
--include-layoutEnumerate 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.
--jsonEmit a single JSON document to stdout (mutually exclusive with --markdown).
--markdownEmit compact, PR-comment-friendly Markdown to stdout (mutually exclusive with --json).
--exit-zeroAlways 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.

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.
  • 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.
  • 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:

Pipeline diff: 1 node changed, layout changed

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

Layout: changed (ui/viewport)

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

{
  "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": []
  },
  "viewport": [],
  "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
  }
}

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 | and backticks safely escaped so untrusted values can't break the comment):

**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, 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:

# .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 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 ships in a release after 1.3.0, so PyPI does not serve it yet. 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:

# 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` ships in a release AFTER 1.3.0, 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: |
          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 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 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.

rocketride list
rocketride list --json

Key flags:

FlagDescription
--jsonOutput 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: 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.

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

FlagDescription
--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-contentInclude pipeline payload content in spans, size-capped. By default no payload content is exported.
--no-metricsExport traces only.
--insecureAllow 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 guide covers the span model, the exported attributes, and per-backend recipes; the WebSocket Events 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.

# 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-commandDescription
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>.
Last updated on