CLI reference
Every fr command, flag, environment variable, and exit code.
The fr CLI (package @fabricorg/runway-cli, also installed as fabric-runway) is the developer
and reviewer entry point to the control plane. It is a zero-dependency, hand-rolled CLI that
talks to the Runway v1 API over HTTP.
Connection
Every command targets a control plane and an organization (tenant):
| Flag | Environment variable | Default |
|---|---|---|
--api-url <url> | RUNWAY_API_URL | http://localhost:3100 |
--org <id> | RUNWAY_ORG | org-acme |
Auth headers are read from the environment: RUNWAY_API_TOKEN (sent as a Bearer token), and for
local development RUNWAY_DEV_ACTOR_ID / RUNWAY_DEV_ACTOR_TYPE.
Commands
fr init <name> [--dir .]
Scaffolds a governed RAG agent repository from the rag-agent template. The name must match
^[a-z][a-z0-9-]*$. Writes the agent, databricks.yml, app.yaml, the GitHub Actions pipeline,
and runway.json.
fr deploy [--dir .] [--version <v>] [--preview --pr <n>]
Reads runway.json, stages the built artifact to a content-addressed UC Volume path, registers
the app on first run, requests a deployment, and (for dev) requests the quality gate.
- No flags → a dev deploy plus a gate request.
--preview --pr <n>→ an isolated preview deploy for pull request<n>(no gate).--version <v>→ labels the deploy with a version (e.g. a commit SHA).
fr promote [--dir .]
Finds the latest gate_passed or approval_pending deployment and records the authenticated human
or agent as one distinct endorsement (runway.promotion_approve). It does not declare the
threshold complete or deploy prod — the trusted worker does that. Exits
with code 2 and the pipeline reason if nothing is promotable or a policy blocks approval.
fr preview destroy --pr <n>
Finds the active preview for pull request <n> and invokes runway.preview_destroy. The exact
PR-owned bundle target is destroyed; repeating the command is safe.
fr audit verify <export.jsonl> --manifest <manifest.json> [--org <id>] [--output <file>]
Verifies the export SHA-256 and row count, rejects mixed/wrong tenants and non-monotonic event
sequences, then rebuilds Runway projections. --output writes the rebuilt projection JSON for a
disaster-recovery drill.
fr catalog
Lists the organization's app catalog: name, template, owner, latest version, and deployment count.
fr mcp
Serves the governed actions as MCP tools over stdio, for use by AI agents.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Usage error or unexpected failure |
2 | Blocked by governance — a policy, gate, or state-machine rejection |
Exit code 2 is the one to script against in CI: it means the request was well-formed but the
governance layer stopped it (a failed gate, a stale verdict, a missing approval).
fr deploy || {
code=$?
[ "$code" -eq 2 ] && echo "Gate blocked the deploy" && exit 1
exit "$code"
}