CLI reference
Every fr command with its flags, environment variables and exit codes, so you can script a delivery run without reading the source.
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 .] [--template <name>]
Scaffolds a governed delivery repository from a bundled template. The name must match
^[a-z][a-z0-9-]*$. Available templates:
rag-agent(default): governed RAG agent: the agent job,databricks.yml,app.yaml, the GitHub Actions pipeline, andrunway.json.tower: a Fabric Tower deployment: the parameterized Databricks bundle (App + Lakebase Autoscaling + UC analytics + Genie space + the events projector job), the operator setup runbook, CI, andrunway.json. The Tower product source is vendored at./towerper the runbook.
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 with 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"
}