fabric-cli

Command reference for the Fabric Agents CLI — send messages, list sessions, run one-shot prompts headlessly, automate from scripts and CI.

fabric-cli is the command-line client for Fabric Agents. It talks to a running Fabric Agents server (local or remote) over WebSocket, and has a self-contained run subcommand that spins up its own server for one-shot prompts — handy in scripts, CI, and automations.

When to use it

Scenario	Tool
Interactive work with streaming UI, file diffs, tool visualisation	Desktop app
Long-running sessions with state you come back to	Desktop app
Scripts and CI pipelines that invoke an agent non-interactively	`fabric-cli run`
Automations triggered by labels, schedules, or events	`fabric-cli` via Automations
Poking at a running server (list workspaces, tail events, send RPC)	`fabric-cli` against a running server

Installing

Installing Fabric Agents on macOS or Linux drops the fabric-cli binary on your PATH automatically. Windows installs put it on %LOCALAPPDATA%\FabricAgents\bin and add that to your user PATH.

See Installation if you don't have the app yet.

Connecting to a server

fabric-cli reads two env vars to know where to connect:

Variable	Purpose
`FABRIC_SERVER_URL`	WebSocket URL (`ws://` or `wss://`).
`FABRIC_SERVER_TOKEN`	Bearer token.

You can also pass --url and --token explicitly, which override the env vars.

The desktop app's local server is what fabric-cli hits by default on your machine — meaning fabric-cli sessions Just Works without any setup as long as the app is running.

Subcommands

Connection & diagnostics

Command	Description
`fabric-cli ping`	Verify server connectivity. Prints client ID and round-trip latency.
`fabric-cli health`	Check credential store health.
`fabric-cli versions`	Show server runtime versions.

Workspaces & sessions

Command	Description
`fabric-cli workspaces`	List all configured workspaces.
`fabric-cli sessions [--workspace <id>]`	List sessions in the current (or specified) workspace.
`fabric-cli session create [--name <str>] [--mode safe\|ask\|allow-all]`	Create a new session.
`fabric-cli session messages <session-id>`	Print the session's full message history.
`fabric-cli session delete <session-id>`	Delete a session.

Communication

Command	Description
`fabric-cli send <session-id> <message>`	Send a message to a session and stream the response. Reads from stdin if no message argument is given.
`fabric-cli cancel <session-id>`	Cancel in-progress processing on a session.

Sources & connections

Command	Description
`fabric-cli connections`	List configured LLM connections.
`fabric-cli sources`	List sources in the current workspace and their health status.

Raw RPC

Command	Description
`fabric-cli invoke <channel> [args-as-json]`	Low-level RPC call against any channel.
`fabric-cli listen <channel>`	Subscribe to a push channel; prints events as they arrive. Ctrl+C to stop.

`fabric-cli run` — one-shot headless prompts

run is the self-contained mode. It spawns a server, creates a session, sends your prompt, streams the response, and exits.

fabric-cli run "Summarise the latest commit"

Common flags

Flag	Default	Purpose
`--workspace-dir <path>`	—	Register this directory as the working workspace for the session.
`--source <slug>`	—	Enable a source for this run. Repeatable.
`--mode safe\|ask\|allow-all`	`allow-all`	Permission mode.
`--model <id>`	provider default	Specific model to use.
`--provider anthropic\|openai\|google\|openrouter\|groq\|mistral\|xai\|…`	`anthropic`	LLM provider.
`--api-key <key>`	`$LLM_API_KEY` or provider-specific env var	Credential for the provider.
`--base-url <url>`	—	Custom endpoint (proxies, self-hosted LLMs, Vercel AI Gateway).
`--output-format text\|stream-json`	`text`	What gets written to stdout. Use `stream-json` when piping into another script.
`--no-cleanup`	`false`	Keep the session on disk after the run for later inspection.

Example: one-shot API call

fabric-cli run \
  --workspace-dir ~/code/my-app \
  --source github \
  --mode ask \
  --output-format stream-json \
  "Summarise open PRs assigned to me and group by repo."

Example: against a specific model and endpoint

LLM_API_KEY=sk-... fabric-cli run \
  --provider openai \
  --model gpt-4o \
  --base-url https://gateway.example.com/v1 \
  "Draft release notes from this changelog."

Global flags

These work on every subcommand (not just run):

Flag	Default	Purpose
`--url <ws-url>`	`$FABRIC_SERVER_URL`	Server URL.
`--token <token>`	`$FABRIC_SERVER_TOKEN`	Bearer token.
`--workspace <id>`	(current)	Workspace the command operates in.
`--json`	`false`	Emit JSON output.
`--timeout <ms>`	10000	Request timeout.
`--send-timeout <ms>`	300000	Max wait for a `send` / `run` stream to complete.
`--tls-ca <path>`	`$FABRIC_TLS_CA`	PEM CA bundle for self-signed server certs.

Exit codes

Code	Meaning
`0`	Success.
`1`	Error (network, RPC, validation). Stderr has the details.
`130`	Interrupted by the user (Ctrl+C) or the server sent an `interrupted` event.

Output modes

text (default) — Streams the assistant's visible text. Good for humans and simple scripts.
stream-json — One JSON object per line, mirroring the session event stream (user messages, tool calls, tool results, assistant messages, errors). Good for piping into jq or downstream processing.

Use cases

CI: run a prompt on every PR

- name: Agent review
  run: |
    fabric-cli run \
      --workspace-dir . \
      --source github \
      --mode safe \
      "Summarise the risks in this PR and flag anything touching auth."

Automation: react to a Linear issue assignment

Configure an automation on LabelAdd for the triage label and let it invoke fabric-cli run with the relevant $FABRIC_* environment variables injected. See Environment variables.

Headless server validation

fabric-cli --validate-server

Runs a 21-step integration test against a locally-spawned server — handy for debugging a broken install.

Environment variables — the full FABRIC_* inventory.
Automations — trigger CLI runs on events.
Workspaces — remote (thin-client) workspace setup.

On this page