CLI reference

fabric is a non-interactive client: you pass everything as flags and it never stops to prompt you. By default it prints human-readable output; add --json to any command to get the same result as structured JSON for scripts and agents to parse. fabric --help and fabric <cmd> --help are always accurate: consult them rather than guessing, since the live command set is the source of truth.

Auth

Agent principals

Agent principals are named, org-scoped identities for automated callers (CI bots, coding agents, deploy pipelines). Each agent gets its own API key, appears as a distinct participant in channels, and can be revoked independently.

Use the minted key as FABRIC_TOKEN or pass it via --token when running the agent. The agent authenticates on every /v1 request exactly like a user key, but its identity resolves to the agent principal, so channel messages and audit entries attribute the work to the agent (with its sponsor visible).

fabric agent serve flags

Data directory. The bridge persists its event cursor and session state under ~/.config/fabric/agents/<agent-name>/state.json (respects FABRIC_CONFIG_DIR). On restart it resumes from the persisted cursor, so no events are reprocessed.

Agents can also be managed from the settings UI under Team > Agents.

The change loop

The merge queue

When a trunk batches accepts (batch_size or concurrency_window above one in queue.toml), an accepted change does not land inline. It merges into a staged candidate frontier (trunk plus the queued changes), is tested there, and advances trunk only once a check passes against it. Several changes can be trialled at once, stacked in order, and the longest passing prefix lands together. A change that fails is evicted and the ones behind it re-form without it. Trunk only ever lands on a state a check passed against.

On a repo that never opts into batching (the zero-config default, batch size 1), the queue is always empty: each accept lands inline once its checks pass, and fabric queue says so.

Checks and runs

Checks only run once a change is proposed, so fabric checks on a draft change has nothing to poll: it tells you to run fabric propose first instead of blocking. If the checks make no progress for the --timeout budget, the command prints the last states it saw and exits non-zero, so you always get status even on a stuck run.

A run reported with --report is marked local in the web runs list so reviewers can tell it ran on your machine rather than on hub infrastructure. A local run is informational only: it never counts toward the required-checks gate that fabric accept enforces.

When a check fails, fabric checks names the failing step in the summary (for example Step 'Run linter' failed), and each check in the --json payload carries a web_url (the job’s block on the web runs page) and a log_url (the REST endpoint fabric checks --logs reads). Reach for --logs <job> to pull the full output and diagnose the failure in place.

The hub runner has no Docker daemon, so a workflow that needs one (a services: container, a container: job, or a Docker-based action) fails with a clear message instead of running part way. See Runner compatibility for the supported subset.

Build artifacts

A workflow step that runs actions/upload-artifact uploads named files during a run, exactly as on GitHub. Fabric captures each uploaded artifact and stores it against the run, so you can download it afterward.

Artifacts show up in two places:

• The run-detail page on the web runs view lists every artifact the run produced, each with its size and a Download link. The bytes stream back through the hub as a .zip.
• The API, for agents and scripts. GET /v1/vcs/runs/<run-id>/artifacts returns the run’s artifacts as JSON (id, name, size, download_url), and GET /v1/vcs/artifacts/<id>/download streams one artifact’s zip. The run-id is the run-group (batch) id you see on the runs page; both endpoints are scoped to your org, so you can only ever fetch an artifact your org owns.

Uploading uses the standard action, so no Fabric-specific workflow change is needed:

- uses: actions/upload-artifact@v4
  with:
    name: build-output
    path: dist/

Artifacts are retained alongside the run. When old runs age out of a change’s retained history, their artifacts are reclaimed with them.

Comments

Comments live on the hub, not in your clone, so these verbs are the only way to read or answer them. Read comment ids from fabric comments list --json, then pass them to the write verbs.

list --json returns each comment’s id, anchor, body, author, thread parent_id, resolved state, outdated flag, and reactions. These are the same comments the web file viewer shows. The hub resolves each anchor for you: a comment whose target moved or vanished since it was written is marked (outdated), and a text comment that can no longer be placed shows as unplaced with its original quoted text. Comments on non-text files carry their own coordinate instead of a line: a PDF page (--page N), an audio/video moment (--time-ms N, with an optional --time-end-ms), or an image box (--region "[x,y,w,h]").

Convention: resolve a comment only after the push that addresses it has landed, and reply first with what changed, so the fix is traceable from the thread.

Tickets

Tickets are version-controlled markdown that live in your repo: each one is a file with a front-matter header (title, status, assignee, priority, labels) and a markdown body. Creating or editing a ticket records ops in the operation log, so a ticket carries its full history like any other file. The hub keeps a fast read model behind list and show.

create accepts --status (defaults to your workflow’s first state), --assignee, --priority (higher sorts first), --labels (comma-separated), and --body (markdown). edit takes the same flags plus --title; only the flags you pass are changed, so fabric ticket edit TIX-12 --status done leaves everything else as-is. Pass --labels "" to clear labels.

Relations (TIX keys in the same workspace) are set with --blocks, --blocked-by, and --related (each a comma-separated list) and --parent (a single key, making the ticket a sub-issue). On edit each relation flag REPLACES that whole relation with what you pass, so --blocks TIX-2,TIX-5 sets exactly those two and --related "" clears it. An unknown, cross-org, or self target is rejected. show prints every non-empty relation plus the sub-issues and the tickets that reference this one. Read keys from fabric ticket list --json, then feed them to show and edit.

Reporting Fabric bugs

fabric ticket files into your own tracker. When the problem is with Fabric itself (a broken runner, a CLI that misbehaves, an engine error, a missing feature), fabric report sends it upstream to the Fabric team instead, from the terminal where it happened.

Every report carries a context envelope the CLI gathers for you, so a report is reproducible by construction rather than whatever you remember to paste: the fabric version, the hub URL, the repo id, the tracked change id, and your OS/arch. Pass --change <id> to set the change explicitly when you are not inside a clone.

Because a report leaves your machine for the Fabric team, privacy is enforced before anything is sent:

• Secrets in any attached logs are scrubbed on your machine (tokens, keys, KEY=value assignments) before they enter the payload. The hub scrubs again as a backstop.
• The CLI prints a preview of the exact payload (title, body, and the whole context envelope) and asks you to confirm.
• Log attachment is opt-in (--attach-logs); nothing about your checks is sent unless you ask.
• Under --json or a non-interactive stdin there is no prompt, so sending requires an explicit --yes. A report is never sent silently.

When fabric checks reports a failure it prints a one-line hint pointing at fabric report --from-last-error --attach-logs, so the fastest path to telling the Fabric team is right where the failure showed up.

Watching events

Instead of polling each surface, watch the hub’s event stream over a long-lived SSE connection. The hub pushes each new event the instant it lands, filtered server-side.

Both commands remember the highest event cursor they delivered (saved per change) and resume from it on the next connection, so an event that landed while nothing was connected is replayed rather than missed. A first-ever wait starts live at the current tip; pass --since <cursor> to start from a specific point, or --from-start to replay the whole history. The event types and each event’s data shape are documented in the agent guide.

Onboarding & history

Diversion to object storage is by size only: files over the cap divert to LFS pointers; a small binary imports inline and round-trips byte-for-byte.

Keeping the CLI current

fabric update is an alias for fabric upgrade. The hub cross-compiles the CLI on every deploy, so upgrading keeps you in sync with the hub you talk to. It resolves the hub from --hub, FABRIC_HUB_URL, or your saved login.

When your installed CLI differs from the build the hub serves, any command that talks to the hub prints a one-line reminder on stderr (it never touches --json output) telling you to run fabric update. That way a CLI lagging behind a newer hub, missing a command the hub already documents, tells you so instead of failing cryptically.

Conventions

• --json on any command. Default output is human-readable text; --json gives the same result as structured data for scripting and agents.
• Every command prints a link. Commands that act on a change end with a View: <url> line you can open to see it in the browser. Under --json the same link is in the web_url field instead.
• Op refs are actor:seq: a frontier coordinate, not a content hash.
• Idempotent push. Re-running push only appends what’s new; “nothing to do” means your tree already matches the change tip.
• Clone never clobbers. fabric clone refuses a target that already holds files and writes nothing, so you never lose local work by cloning over it. Pass --force to write over it anyway (same-path files overwritten, unrelated files kept). Under --json a refusal is {error: "clone_target_not_empty", message, suggestion, dir} with a non-zero exit.
• Stale working dir. Once the change you cloned is accepted, abandoned, or deleted, pull stops with the reason plus a next step (fabric clone --at trunk to read trunk, or fabric change create then fabric clone to keep editing). With --json the same reason rides in {error, message, suggestion}. status is offline, so it flags only a working dir whose .fabric/state.json tracks no change at all.

The definitive, always-current command set is fabric --help. This page mirrors it for reference. When in doubt, trust the CLI.