fabro/docs/public/reference/cli.mdx
fabro-sh-0530[bot] 7b7a2c9044
Add fabro variable CLI namespace for server-managed variables (#434)
## Summary

Exposes the existing variables API through a new `fabro variable` CLI
namespace (`list`, `get`, `set`, `rm`), following the same patterns as
`fabro secret`. Variables are intentionally readable — `list` and `get`
show stored values — while `fabro secret` remains write-only. This PR
also ships a significant set of accompanying changes: a refactored
sandbox lifecycle model in the web UI, removal of the
`fabro-devcontainer` crate, and a new `RunSandbox` OpenAPI schema that
models the full planned → initializing → ready/failed lifecycle.

## What Changed

### CLI (`fabro variable`)
- New `fabro variable` namespace with `list` (aliased `ls`), `get`,
`set`, and `rm` subcommands, dispatched through the same
`ServerTargetArgs` pattern as `fabro secret`.
- `fabro-client` gains five new wrapper methods (`list_variables`,
`get_variable`, `create_variable`, `update_variable`, `delete_variable`)
over the generated OpenAPI client.
- `set` is an upsert; `--value-stdin` accepts empty input after
newline-trimming (unlike the secrets equivalent).
- CLI reference docs (`docs/public/reference/cli.mdx`) regenerated;
`docs/public/workflows/variables.mdx` gains a short section explaining
`{{ vars.NAME }}` interpolation and the variables-vs-secrets security
boundary.

### Sandbox lifecycle model (web)
- New `RunSandbox` OpenAPI shape splits the old flat object into `kind`
(planned/initializing/ready/failed) + `plan` + optional `instance` +
optional `failure`.
- `apps/fabro-web/app/lib/run-sandbox-lifecycle.ts` centralises
lifecycle helpers (`sandboxLifecycleKind`, `sandboxInstance`,
`sandboxRuntime`, `sandboxIsReady`, `sandboxTabVisible`,
`SANDBOX_LIFECYCLE_DISPLAY`).
- Run summary panel and sandbox route now show lifecycle state
(Initializing / Failed with causes / Not created) before or instead of
the fully-loaded `SandboxDetails`.
- The sandbox details query is skipped entirely until `sandboxIsReady`
returns true, preventing unnecessary 404 fetches for planned/failed
sandboxes.
- `runHasSandbox` in `tabs-shell.tsx` delegates to `sandboxTabVisible`,
hiding the Sandbox tab for `planned` state and showing it for
`initializing`/`ready`/`failed`.
- Legacy flat sandbox shape (no `kind`) is handled via
backwards-compatible shims in the new helpers.

### `fabro-devcontainer` removal
- The `fabro-devcontainer` crate has been removed from `Cargo.lock` and
all dependent crates.
- References to devcontainer in internal plans, docs, changelog entries,
and event schemas have been cleaned up or reworded to reflect that the
feature is no longer present.

### Plan summary
- **Unit 1:** `fabro-client` variable wrappers
- **Unit 2:** CLI args, dispatch, and `commands/variable/mod.rs`
- **Unit 3:** `list`, `get`, `set`, `rm` behavior modules
- **Unit 4:** Test harness helpers and integration tests
- **Unit 5:** Regenerated CLI docs + `variables.mdx` update


### Fabro Details

<details>
<summary>Ran 8 stages in 58m 50s for $23.81</summary>

| Stage | Duration | Cost | Retries |
|---|---|---|---|
| start | 0s | – | 0 |
| toolchain | 1s | – | 0 |
| preflight_compile | 2m 9s | – | 0 |
| preflight_lint | 2m 21s | – | 0 |
| implement | 31m 34s | $18.44 | 0 |
| simplify_opus | 8m 48s | $2.60 | 0 |
| simplify_gpt | 4m 1s | $2.77 | 0 |
| verify | 9m 17s | – | 0 |
| **Total** | **58m 50s** | **$23.81** | **0** |

</details>

<details>
<summary>Ran <code>ImplementPlan.fabro</code> (11 nodes and 14
edges)</summary>

```dot
digraph ImplementPlan {
    graph [
        goal="Implement and simplify",
        model_stylesheet="
            * { model: claude-opus-4-7; }
        "
    ]
    rankdir=LR

    start [shape=Mdiamond, label="Start"]
    exit  [shape=Msquare, label="Exit"]

    toolchain         [label="Toolchain", shape=parallelogram, script="command -v cargo >/dev/null || { curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && sudo ln -sf $HOME/.cargo/bin/* /usr/local/bin/; }; cargo --version 2>&1", max_retries=0]
    preflight_compile [label="Preflight Compile", shape=parallelogram, script="cargo check -q --workspace 2>&1", max_retries=0]
    preflight_lint    [label="Preflight Lint", shape=parallelogram, script="cargo +nightly-2026-04-14 clippy -q --workspace --all-targets -- -D warnings 2>&1", max_retries=0]
    fix_lints         [label="Fix Lints", prompt="The preflight lint step failed. Read the build output from context and fix all clippy lint warnings.", max_visits=3]
    implement         [label="Implement", prompt="Read the plan file referenced in the goal and implement every step. Make all the code changes described in the plan. Use red/green TDD.", model="gpt-55", reasoning_effort="xhigh"]
    simplify_opus     [label="Simplify (Opus)", prompt="@prompts/simplify.md"]
    simplify_gpt      [label="Simplify (GPT-55)", prompt="@prompts/simplify.md", model="gpt-55"]
    verify            [label="Verify", shape=parallelogram, script="git fetch origin main 2>&1 && git merge --no-edit --no-stat origin/main 2>&1 && cargo +nightly-2026-04-14 fmt --all 2>&1 && cargo dev docs refresh 2>&1 && cargo +nightly-2026-04-14 fmt --check --all 2>&1 && { command -v rg >/dev/null 2>&1 || { echo 'rg is required for verify'; exit 127; }; } && ! rg -n 'AuthMode::Disabled|RunAuthMethod|RunSubjectProvenance|\bActorRef\b|\bActorKind\b|AuthenticatedSubject|AuthenticatedService|AuthorizeRunScoped|AuthorizeRunBlob|AuthorizeStageArtifact|AuthorizeCommandLog|auth_method\s*==\s*\"disabled\"' lib/crates apps lib/packages docs/public/api-reference/fabro-api.yaml 2>&1 && cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings 2>&1 && cargo nextest run --workspace --status-level slow --profile ci 2>&1 && cargo dev docs check 2>&1 && bun install --frozen-lockfile 2>&1 && (cd apps/fabro-web && bun run typecheck) 2>&1 && (cd apps/fabro-web && bun run test) 2>&1 && (cd lib/packages/fabro-api-client && bun run typecheck) 2>&1 && cargo dev build -- -p fabro-cli --release 2>&1", goal_gate=true, retry_target="fixup"]
    fixup             [label="Fixup", prompt="The verify step failed. Read the build output from context and fix all format, clippy, Rust test, docs, TypeScript typecheck/test, and build failures.", max_visits=3]

    start -> toolchain
    toolchain -> preflight_compile [condition="outcome=succeeded"]
    toolchain -> exit
    preflight_compile -> preflight_lint [condition="outcome=succeeded"]
    preflight_compile -> exit
    preflight_lint -> implement [condition="outcome=succeeded"]
    preflight_lint -> fix_lints
    fix_lints -> preflight_lint
    implement -> simplify_opus -> simplify_gpt -> verify
    verify -> exit  [condition="outcome=succeeded"]
    verify -> fixup
    fixup -> verify
}

```

</details>

⚒️ Generated with [Fabro](https://fabro.sh)

---------

Co-authored-by: Fabro <noreply@fabro.sh>
2026-05-27 13:57:25 -04:00

1734 lines
40 KiB
Text

---
title: "CLI Reference"
description: "Fabro command-line interface reference"
---
## Global options
These flags apply to all subcommands:
| Flag | Description |
|---|---|
| `--json` | Output machine-readable JSON when the command supports it |
| `--debug` | Enable DEBUG-level logging (default is INFO) |
| `--no-upgrade-check` | Skip the automatic background upgrade check |
| `--quiet` | Suppress non-essential output |
| `--verbose` | Enable verbose output |
| `-h, --help` | Print help |
| `-V, --version` | Print version |
Connection-target flags like `--storage-dir` and `--server` are command-specific, not global. Fabro no longer auto-loads `~/.fabro/.env`; persist server-owned credentials with `fabro provider login` / `fabro secret set`, or provide environment variables in the invoking shell.
## Configuration
CLI defaults can be set in `~/.fabro/settings.toml` so you don't have to pass common flags every time:
```toml title="settings.toml"
_version = 1
[cli.exec.model]
provider = "anthropic"
name = "claude-opus-4-6"
[cli.exec.agent]
permissions = "read-write"
[cli.output]
format = "text"
[run.model]
name = "claude-sonnet-4-5"
[cli.target]
type = "http"
url = "https://fabro.example.com/api/v1"
```
`[cli.exec]` config applies to `fabro exec`. `[run.model]` sets the default workflow model/provider for commands like `fabro run` and `fabro preflight`. `[cli.target]` stores connection info for commands that can target a remote Fabro server.
`fabro model` uses `[cli.target]` by default when no explicit `--storage-dir` is passed. `fabro exec` remains a local session unless you pass `--server`, even if `[cli.target]` is configured.
Explicit `http(s)://...` targets are always treated as remote servers. They do not inherit identity from a local daemon, a local storage dir, or `~/.fabro/dev-token`. For remote URLs, use `fabro auth login --server ...` or a stored CLI auth session.
CLI flags always override `settings.toml` values, which override hardcoded defaults.
{/* generated:cli */}
## `fabro`
```bash
fabro [OPTIONS] [COMMAND]
```
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro approve` | Approve pending workflow runs |
| `fabro archive` | Mark terminal runs as archived (reviewed, no further action needed). Archived runs are hidden from default listings |
| `fabro artifact` | Inspect and copy run artifacts (screenshots, reports, traces) |
| `fabro ask` | Ask Fabro a read-only question about a run |
| `fabro attach` | Attach to a running or finished workflow run |
| `fabro auth` | Manage CLI authentication state |
| `fabro completion` | Generate shell completions |
| `fabro create` | Create a workflow run (allocate run dir, persist spec) |
| `fabro deny` | Deny pending workflow runs |
| `fabro discord` | Open the Discord community in the browser |
| `fabro docs` | Open the docs website in the browser |
| `fabro doctor` | Check environment and integration health |
| `fabro dump` | Export a run's durable state to a directory |
| `fabro events` | View the event log of a workflow run |
| `fabro fork` | Fork a workflow run from an earlier checkpoint into a new run |
| `fabro graph` | Render a workflow graph as SVG |
| `fabro inspect` | Show detailed information about a workflow run |
| `fabro install` | Set up the Fabro environment (LLMs, certs, GitHub) |
| `fabro logs` | View the raw worker tracing log of a workflow run |
| `fabro mcp` | Model Context Protocol server |
| `fabro model` | List and test LLM models |
| `fabro parent` | Manage run parent links |
| `fabro pr` | Pull request operations |
| `fabro preflight` | Validate run configuration without executing |
| `fabro provider` | Provider operations |
| `fabro repo` | Repository commands |
| `fabro resume` | Resume an interrupted workflow run |
| `fabro rewind` | Rewind a workflow run to an earlier checkpoint |
| `fabro rm` | Remove one or more workflow runs |
| `fabro run` | Launch a workflow run |
| `fabro sandbox` | Sandbox operations (cp, ssh, preview) |
| `fabro secret` | Manage server-owned secrets |
| `fabro server` | Server operations |
| `fabro settings` | Inspect effective settings |
| `fabro start` | Start a created workflow run on the server |
| `fabro steer` | Steer a running agent mid-execution |
| `fabro system` | System maintenance commands |
| `fabro unarchive` | Restore archived runs to their prior terminal status |
| `fabro uninstall` | Uninstall Fabro from this machine |
| `fabro upgrade` | Upgrade fabro to the latest version |
| `fabro validate` | Validate a workflow |
| `fabro variable` | Manage server-owned variables |
| `fabro version` | Show client and server version information |
| `fabro wait` | Block until a workflow run completes |
| `fabro workflow` | Workflow operations |
### `fabro approve`
Approve pending workflow runs
```bash
fabro approve [OPTIONS] <RUNS>...
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUNS` | Run IDs or workflow names to approve |
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro archive`
Mark terminal runs as archived (reviewed, no further action needed). Archived runs are hidden from default listings
```bash
fabro archive [OPTIONS] <RUNS>...
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUNS` | Run IDs or workflow names to archive |
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro artifact`
Inspect and copy run artifacts (screenshots, reports, traces)
```bash
fabro artifact [OPTIONS] <COMMAND>
```
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro artifact cp` | Copy artifacts from a workflow run |
| `fabro artifact list` | List artifacts for a workflow run |
#### `fabro artifact cp`
Copy artifacts from a workflow run
```bash
fabro artifact cp [OPTIONS] <SOURCE> [DEST]
```
#### Arguments
| Name | Description |
| --- | --- |
| `SOURCE` | Source: RUN_ID (all artifacts) or RUN_ID:path (specific artifact) |
| `DEST` | Destination directory (defaults to current directory)<br />Default: `.` |
#### Options
| Option | Description |
| --- | --- |
| `--node <node>` | Filter to artifacts from a specific node |
| `--retry <retry>` | Filter to artifacts from a specific retry attempt |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--tree` | Preserve {node_slug}/retry_{N}/ directory structure |
#### `fabro artifact list`
List artifacts for a workflow run
```bash
fabro artifact list [OPTIONS] <RUN_ID>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN_ID` | Run ID (or prefix) |
#### Options
| Option | Description |
| --- | --- |
| `--node <node>` | Filter to artifacts from a specific node |
| `--retry <retry>` | Filter to artifacts from a specific retry attempt |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro ask`
Ask Fabro a read-only question about a run
```bash
fabro ask [OPTIONS] --prompt <PROMPT> <RUN>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN` | Run ID prefix or workflow name |
#### Options
| Option | Description |
| --- | --- |
| `--model <model>` | Optional model name |
| `-p, --prompt <prompt>` | Question to ask |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro attach`
Attach to a running or finished workflow run
```bash
fabro attach [OPTIONS] <RUN>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN` | Run ID prefix or workflow name |
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro auth`
Manage CLI authentication state
```bash
fabro auth [OPTIONS] <COMMAND>
```
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro auth login` | Log in to a Fabro server |
| `fabro auth logout` | Log out from a Fabro server |
| `fabro auth status` | Show offline CLI auth status |
#### `fabro auth login`
Log in to a Fabro server
```bash
fabro auth login [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--dev-token <dev_token>` | Log in with a dev-token instead of browser OAuth |
| `--no-browser` | Print the browser URL instead of opening it automatically |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--timeout <timeout>` | Timeout in seconds waiting for the browser flow to complete<br />Default: `300` |
#### `fabro auth logout`
Log out from a Fabro server
```bash
fabro auth logout [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--all` | Log out from every stored server |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
#### `fabro auth status`
Show offline CLI auth status
```bash
fabro auth status [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro completion`
Generate shell completions
```bash
fabro completion [OPTIONS] <SHELL>
```
#### Arguments
| Name | Description |
| --- | --- |
| `SHELL` | Shell to generate completions for<br />Values: `bash`, `elvish`, `fish`, `powershell`, `zsh` |
### `fabro create`
Create a workflow run (allocate run dir, persist spec)
```bash
fabro create [OPTIONS] <WORKFLOW>
```
#### Arguments
| Name | Description |
| --- | --- |
| `WORKFLOW` | Path to a .fabro workflow file or .toml task config |
#### Options
| Option | Description |
| --- | --- |
| `--auto-approve` | Auto-approve all human gates |
| `-d, --detach` | Run the workflow in the background and print the run ID |
| `--dry-run` | Execute with simulated LLM backend |
| `--environment <environment>` | Named environment for agent tools |
| `--goal <goal>` | Override the workflow goal (available as {{ goal }} in prompts) |
| `--goal-file <goal_file>` | Read the workflow goal from a file |
| `--label <key=value>` | Attach a label to this run (repeatable, format: KEY=VALUE) |
| `--model <model>` | Override default LLM model |
| `--parent <run>` | Link this run to an existing orchestration parent run |
| `--preserve-sandbox` | Keep the sandbox alive after the run finishes (for debugging) |
| `--provider <provider>` | Override default LLM provider |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `-I, --input <key=value>` | Override a workflow input value (repeatable, format: KEY=VALUE) |
| `-v, --verbose` | Enable verbose output |
### `fabro deny`
Deny pending workflow runs
```bash
fabro deny [OPTIONS] <RUNS>...
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUNS` | Run IDs or workflow names to deny |
#### Options
| Option | Description |
| --- | --- |
| `--reason <reason>` | Reason for denying execution |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro discord`
Open the Discord community in the browser
```bash
fabro discord [OPTIONS]
```
### `fabro docs`
Open the docs website in the browser
```bash
fabro docs [OPTIONS]
```
### `fabro doctor`
Check environment and integration health
```bash
fabro doctor [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `-v, --verbose` | Show detailed information for each check |
### `fabro dump`
Export a run's durable state to a directory
```bash
fabro dump [OPTIONS] --output <OUTPUT> <RUN>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN` | Run ID prefix or workflow name |
#### Options
| Option | Description |
| --- | --- |
| `-o, --output <output>` | Output directory (must not exist or be empty) |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro events`
View the event log of a workflow run
```bash
fabro events [OPTIONS] <RUN>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN` | Run ID prefix or workflow name (most recent run) |
#### Options
| Option | Description |
| --- | --- |
| `-f, --follow` | Follow event output |
| `-p, --pretty` | Formatted colored output with rendered assistant text |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--since <since>` | Events since timestamp or relative (e.g. "42m", "2h", "2026-01-02T13:00:00Z") |
| `-n, --tail <tail>` | Lines from end (default: all) |
### `fabro fork`
Fork a workflow run from an earlier checkpoint into a new run
```bash
fabro fork [OPTIONS] <RUN_ID> [TARGET]
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN_ID` | Run ID (or unambiguous prefix) |
| `TARGET` | Target checkpoint: node name, node@visit, or @ordinal (omit to fork from latest) |
#### Options
| Option | Description |
| --- | --- |
| `--list` | Show the checkpoint timeline instead of forking |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro graph`
Render a workflow graph as SVG
```bash
fabro graph [OPTIONS] <WORKFLOW>
```
#### Arguments
| Name | Description |
| --- | --- |
| `WORKFLOW` | Path to the .fabro workflow file, .toml task config, or project workflow name |
#### Options
| Option | Description |
| --- | --- |
| `--allow-invalid` | Render even when workflow validation reports errors |
| `-d, --direction <direction>` | Graph layout direction (overrides the DOT file's rankdir)<br />Values: `lr`, `tb` |
| `--format <format>` | Output format<br />Values: `svg`<br />Default: `svg` |
| `-o, --output <output>` | Output file path (defaults to stdout) |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro inspect`
Show detailed information about a workflow run
```bash
fabro inspect [OPTIONS] <RUN>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN` | Run ID prefix or workflow name (most recent run) |
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro install`
Set up the Fabro environment (LLMs, certs, GitHub)
```bash
fabro install [OPTIONS] [COMMAND]
```
#### Options
| Option | Description |
| --- | --- |
| `--storage-dir <storage_dir>` | Local storage directory (default: ~/.fabro/storage) |
| `--web-url <web_url>` | Base URL for the web UI (used for OAuth callback URLs and generated settings)<br />Default: `http://127.0.0.1:32276` |
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro install github` | Configure GitHub integration (token or GitHub App) |
#### `fabro install github`
Configure GitHub integration (token or GitHub App)
```bash
fabro install github [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--owner <owner>` | GitHub App owner: `personal` or `org:<slug>` (app only, requires --non-interactive) |
| `--strategy <strategy>` | GitHub authentication strategy (requires --non-interactive)<br />Values: `token`, `app` |
### `fabro logs`
View the raw worker tracing log of a workflow run
```bash
fabro logs [OPTIONS] <RUN>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN` | Run ID prefix or workflow name (most recent run) |
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `-n, --tail <tail>` | Lines from end (default: all) |
### `fabro mcp`
Model Context Protocol server
```bash
fabro mcp [OPTIONS] <COMMAND>
```
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro mcp config` | Print MCP client configuration JSON |
| `fabro mcp init` | Configure an MCP client to launch Fabro |
| `fabro mcp start` | Start the Fabro MCP server over stdio |
#### `fabro mcp config`
Print MCP client configuration JSON
```bash
fabro mcp config [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--storage-dir <storage_dir>` | Local storage directory (default: ~/.fabro/storage) |
#### `fabro mcp init`
Configure an MCP client to launch Fabro
```bash
fabro mcp init [OPTIONS] <AGENT>
```
#### Arguments
| Name | Description |
| --- | --- |
| `AGENT` | Values: `claude`, `cursor`, `windsurf` |
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--storage-dir <storage_dir>` | Local storage directory (default: ~/.fabro/storage) |
#### `fabro mcp start`
Start the Fabro MCP server over stdio
```bash
fabro mcp start [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--storage-dir <storage_dir>` | Local storage directory (default: ~/.fabro/storage) |
### `fabro model`
List and test LLM models
```bash
fabro model [OPTIONS] [COMMAND]
```
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro model list` | List available models |
| `fabro model test` | Test model availability by sending a simple prompt |
#### `fabro model list`
List available models
```bash
fabro model list [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `-p, --provider <provider>` | Filter by provider |
| `-q, --query <query>` | Search for models matching this string |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
#### `fabro model test`
Test model availability by sending a simple prompt
```bash
fabro model test [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--deep` | Run a multi-turn tool-use test (catches reasoning round-trip bugs) |
| `-j, --jobs <jobs>` | Number of model tests to run concurrently in bulk mode<br />Default: `4` |
| `-m, --model <model>` | Test a specific model |
| `-p, --provider <provider>` | Filter by provider |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro parent`
Manage run parent links
```bash
fabro parent [OPTIONS] <COMMAND>
```
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro parent link` | Link or replace a run's orchestration parent |
| `fabro parent unlink` | Unlink a run from its orchestration parent |
#### `fabro parent link`
Link or replace a run's orchestration parent
```bash
fabro parent link [OPTIONS] <CHILD_RUN> <PARENT_RUN>
```
#### Arguments
| Name | Description |
| --- | --- |
| `CHILD_RUN` | Child run selector |
| `PARENT_RUN` | Parent run selector |
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
#### `fabro parent unlink`
Unlink a run from its orchestration parent
```bash
fabro parent unlink [OPTIONS] <CHILD_RUN>
```
#### Arguments
| Name | Description |
| --- | --- |
| `CHILD_RUN` | Child run selector |
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro pr`
Pull request operations
```bash
fabro pr [OPTIONS] <COMMAND>
```
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro pr close` | Close a pull request |
| `fabro pr create` | Create a pull request from a completed run |
| `fabro pr link` | Link or replace the GitHub pull request associated with a run |
| `fabro pr merge` | Merge a pull request |
| `fabro pr unlink` | Unlink the pull request associated with a run |
| `fabro pr view` | View pull request details |
#### `fabro pr close`
Close a pull request
```bash
fabro pr close [OPTIONS] <RUN_ID>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN_ID` | Run ID or prefix |
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
#### `fabro pr create`
Create a pull request from a completed run
```bash
fabro pr create [OPTIONS] <RUN_ID>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN_ID` | Run ID or prefix |
#### Options
| Option | Description |
| --- | --- |
| `-f, --force` | Create PR even if the run status is not succeeded/partially_succeeded |
| `--model <model>` | LLM model for generating PR description |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
#### `fabro pr link`
Link or replace the GitHub pull request associated with a run
```bash
fabro pr link [OPTIONS] <RUN_ID> <URL>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN_ID` | Run ID or prefix |
| `URL` | GitHub pull request URL to associate with the run |
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
#### `fabro pr merge`
Merge a pull request
```bash
fabro pr merge [OPTIONS] <RUN_ID>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN_ID` | Run ID or prefix |
#### Options
| Option | Description |
| --- | --- |
| `--method <method>` | Merge method: merge, squash, or rebase<br />Values: `merge`, `squash`, `rebase`<br />Default: `squash` |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
#### `fabro pr unlink`
Unlink the pull request associated with a run
```bash
fabro pr unlink [OPTIONS] <RUN_ID>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN_ID` | Run ID or prefix |
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
#### `fabro pr view`
View pull request details
```bash
fabro pr view [OPTIONS] <RUN_ID>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN_ID` | Run ID or prefix |
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro preflight`
Validate run configuration without executing
```bash
fabro preflight [OPTIONS] <WORKFLOW>
```
#### Arguments
| Name | Description |
| --- | --- |
| `WORKFLOW` | Path to a .fabro workflow file or .toml task config |
#### Options
| Option | Description |
| --- | --- |
| `--environment <environment>` | Named environment for agent tools |
| `--goal <goal>` | Override the workflow goal (available as {{ goal }} in prompts) |
| `--goal-file <goal_file>` | Read the workflow goal from a file |
| `--model <model>` | Override default LLM model |
| `--provider <provider>` | Override default LLM provider |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `-I, --input <key=value>` | Override a workflow input value (repeatable, format: KEY=VALUE) |
| `-v, --verbose` | Enable verbose output |
### `fabro provider`
Provider operations
```bash
fabro provider [OPTIONS] <COMMAND>
```
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro provider login` | Log in to an LLM provider |
#### `fabro provider login`
Log in to an LLM provider
```bash
fabro provider login [OPTIONS] --provider <PROVIDER>
```
#### Options
| Option | Description |
| --- | --- |
| `--api-key-stdin` | Read an API key from stdin instead of prompting |
| `--provider <provider>` | LLM provider to authenticate with |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro repo`
Repository commands
```bash
fabro repo [OPTIONS] <COMMAND>
```
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro repo deinit` | Remove .fabro/ project directory |
| `fabro repo init` | Initialize a new project |
#### `fabro repo deinit`
Remove .fabro/ project directory
```bash
fabro repo deinit [OPTIONS]
```
#### `fabro repo init`
Initialize a new project
```bash
fabro repo init [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro resume`
Resume an interrupted workflow run
```bash
fabro resume [OPTIONS] <RUN>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN` | Run ID or unambiguous prefix |
#### Options
| Option | Description |
| --- | --- |
| `-d, --detach` | Run in the background and print the run ID |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro rewind`
Rewind a workflow run to an earlier checkpoint
```bash
fabro rewind [OPTIONS] <RUN_ID> [TARGET]
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN_ID` | Run ID (or unambiguous prefix) |
| `TARGET` | Target checkpoint: node name, node@visit, or @ordinal (omit with --list) |
#### Options
| Option | Description |
| --- | --- |
| `--list` | Show the checkpoint timeline instead of rewinding |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro rm`
Remove one or more workflow runs
```bash
fabro rm [OPTIONS] <RUNS>...
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUNS` | Run IDs or workflow names to remove |
#### Options
| Option | Description |
| --- | --- |
| `-f, --force` | Force removal of active runs |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro run`
Launch a workflow run
```bash
fabro run [OPTIONS] <WORKFLOW>
```
#### Arguments
| Name | Description |
| --- | --- |
| `WORKFLOW` | Path to a .fabro workflow file or .toml task config |
#### Options
| Option | Description |
| --- | --- |
| `--auto-approve` | Auto-approve all human gates |
| `-d, --detach` | Run the workflow in the background and print the run ID |
| `--dry-run` | Execute with simulated LLM backend |
| `--environment <environment>` | Named environment for agent tools |
| `--goal <goal>` | Override the workflow goal (available as {{ goal }} in prompts) |
| `--goal-file <goal_file>` | Read the workflow goal from a file |
| `--label <key=value>` | Attach a label to this run (repeatable, format: KEY=VALUE) |
| `--model <model>` | Override default LLM model |
| `--parent <run>` | Link this run to an existing orchestration parent run |
| `--preserve-sandbox` | Keep the sandbox alive after the run finishes (for debugging) |
| `--provider <provider>` | Override default LLM provider |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `-I, --input <key=value>` | Override a workflow input value (repeatable, format: KEY=VALUE) |
| `-v, --verbose` | Enable verbose output |
### `fabro sandbox`
Sandbox operations (cp, ssh, preview)
```bash
fabro sandbox [OPTIONS] <COMMAND>
```
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro sandbox cp` | Copy files to/from a run's sandbox |
| `fabro sandbox preview` | Get a preview URL for a port on a run's sandbox |
| `fabro sandbox ssh` | SSH into a run's sandbox |
#### `fabro sandbox cp`
Copy files to/from a run's sandbox
```bash
fabro sandbox cp [OPTIONS] <SRC> <DST>
```
#### Arguments
| Name | Description |
| --- | --- |
| `SRC` | Source: `<run-id>:<path>` or local path |
| `DST` | Destination: `<run-id>:<path>` or local path |
#### Options
| Option | Description |
| --- | --- |
| `-r, --recursive` | Recurse into directories |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
#### `fabro sandbox preview`
Get a preview URL for a port on a run's sandbox
```bash
fabro sandbox preview [OPTIONS] <RUN> <PORT>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN` | Run ID or prefix |
| `PORT` | Port number |
#### Options
| Option | Description |
| --- | --- |
| `--open` | Open URL in browser (implies --signed) |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--signed` | Generate a signed URL (embeds auth token, no headers needed) |
| `--ttl <ttl>` | Signed URL expiry in seconds (default 3600, requires --signed)<br />Default: `3600` |
#### `fabro sandbox ssh`
SSH into a run's sandbox
```bash
fabro sandbox ssh [OPTIONS] <RUN>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN` | Run ID or prefix |
#### Options
| Option | Description |
| --- | --- |
| `--print` | Print the SSH command instead of connecting |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--ttl <ttl>` | SSH access expiry in minutes (default 60)<br />Default: `60` |
### `fabro secret`
Manage server-owned secrets
```bash
fabro secret [OPTIONS] <COMMAND>
```
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro secret list` | List secret names |
| `fabro secret rm` | Remove a secret |
| `fabro secret set` | Set a secret value |
#### `fabro secret list`
List secret names
```bash
fabro secret list [OPTIONS]
```
#### `fabro secret rm`
Remove a secret
```bash
fabro secret rm [OPTIONS] <KEY>
```
#### Arguments
| Name | Description |
| --- | --- |
| `KEY` | Name of the secret to remove |
#### `fabro secret set`
Set a secret value
```bash
fabro secret set [OPTIONS] <KEY> [VALUE]
```
#### Arguments
| Name | Description |
| --- | --- |
| `KEY` | Name of the secret |
| `VALUE` | Value to store (omit to enter interactively) |
#### Options
| Option | Description |
| --- | --- |
| `--description <description>` | Optional human-readable description |
| `--type <type>` | Secret storage type<br />Values: `token`, `file`<br />Default: `token` |
| `--value-stdin` | Read the secret value from stdin |
### `fabro server`
Server operations
```bash
fabro server [OPTIONS] <COMMAND>
```
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro server restart` | Stop and restart the HTTP API server |
| `fabro server start` | Start the HTTP API server |
| `fabro server status` | Show server status |
| `fabro server stop` | Stop the HTTP API server |
#### `fabro server restart`
Stop and restart the HTTP API server
```bash
fabro server restart [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--bind <bind>` | Address to bind to (IP or IP:port for TCP, or path containing / for Unix socket) |
| `--config <config>` | Path to server config file (default: ~/.fabro/settings.toml) |
| `--environment <environment>` | Named environment for agent tools |
| `--foreground` | Run in the foreground instead of daemonizing |
| `--max-concurrent-runs <max_concurrent_runs>` | Maximum number of concurrent run executions |
| `--model <model>` | Override default LLM model |
| `--no-web` | Disable the embedded web UI, browser auth routes, and web-only helper endpoints |
| `--provider <provider>` | Override default LLM provider |
| `--storage-dir <storage_dir>` | Local storage directory (default: ~/.fabro/storage) |
| `--timeout <timeout>` | Seconds to wait for graceful shutdown before SIGKILL<br />Default: `10` |
| `--watch-web` | Run `bun run dev` in apps/fabro-web to watch/recompile web assets (debug only) |
| `--web` | Enable the embedded web UI and browser auth routes |
#### `fabro server start`
Start the HTTP API server
```bash
fabro server start [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--bind <bind>` | Address to bind to (IP or IP:port for TCP, or path containing / for Unix socket) |
| `--config <config>` | Path to server config file (default: ~/.fabro/settings.toml) |
| `--environment <environment>` | Named environment for agent tools |
| `--foreground` | Run in the foreground instead of daemonizing |
| `--max-concurrent-runs <max_concurrent_runs>` | Maximum number of concurrent run executions |
| `--model <model>` | Override default LLM model |
| `--no-web` | Disable the embedded web UI, browser auth routes, and web-only helper endpoints |
| `--provider <provider>` | Override default LLM provider |
| `--storage-dir <storage_dir>` | Local storage directory (default: ~/.fabro/storage) |
| `--watch-web` | Run `bun run dev` in apps/fabro-web to watch/recompile web assets (debug only) |
| `--web` | Enable the embedded web UI and browser auth routes |
#### `fabro server status`
Show server status
```bash
fabro server status [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--json` | Output as JSON |
| `--storage-dir <storage_dir>` | Local storage directory (default: ~/.fabro/storage) |
#### `fabro server stop`
Stop the HTTP API server
```bash
fabro server stop [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--storage-dir <storage_dir>` | Local storage directory (default: ~/.fabro/storage) |
| `--timeout <timeout>` | Seconds to wait for graceful shutdown before SIGKILL<br />Default: `10` |
### `fabro settings`
Inspect effective settings
```bash
fabro settings [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro start`
Start a created workflow run on the server
```bash
fabro start [OPTIONS] <RUN>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN` | Run ID prefix or workflow name |
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro steer`
Steer a running agent mid-execution
```bash
fabro steer [OPTIONS] <RUN> [TEXT]
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN` | Run ID prefix to steer |
| `TEXT` | Steer message text (omit when --text-stdin is used) |
#### Options
| Option | Description |
| --- | --- |
| `--interrupt` | Cancel the in-flight LLM stream / tool calls and deliver the message as the next user turn (default: append to the steering queue) |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--text-stdin` | Read steer text from stdin instead of a positional arg |
### `fabro system`
System maintenance commands
```bash
fabro system [OPTIONS] <COMMAND>
```
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro system df` | Show disk usage |
| `fabro system events` | Stream run events from the server |
| `fabro system info` | Show server runtime information |
| `fabro system prune` | Delete old workflow runs |
| `fabro system repair` | Inspect and repair durable server data |
#### `fabro system df`
Show disk usage
```bash
fabro system df [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--storage-dir <storage_dir>` | Local storage directory (default: ~/.fabro/storage) |
| `-v, --verbose` | Show per-run breakdown |
#### `fabro system events`
Stream run events from the server
```bash
fabro system events [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--run-id <run_ids>` | Filter by run ID (repeatable) |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--storage-dir <storage_dir>` | Local storage directory (default: ~/.fabro/storage) |
#### `fabro system info`
Show server runtime information
```bash
fabro system info [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--storage-dir <storage_dir>` | Local storage directory (default: ~/.fabro/storage) |
#### `fabro system prune`
Delete old workflow runs
```bash
fabro system prune [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--before <before>` | Only include runs started before this date (YYYY-MM-DD prefix match) |
| `--label <key=value>` | Filter by label (KEY=VALUE, repeatable, AND semantics) |
| `--older-than <duration>` | Only prune runs older than this duration (e.g. 24h, 7d). Default: 24h when no explicit filters are set |
| `--orphans` | Include orphan directories (no matching durable run) |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--storage-dir <storage_dir>` | Local storage directory (default: ~/.fabro/storage) |
| `--workflow <workflow>` | Filter by workflow name (substring match) |
| `--yes` | Actually delete (default is dry-run) |
#### `fabro system repair`
Inspect and repair durable server data
```bash
fabro system repair [OPTIONS] <COMMAND>
```
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro system repair runs` | List runs that cannot be loaded from durable storage |
##### `fabro system repair runs`
List runs that cannot be loaded from durable storage
```bash
fabro system repair runs [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--delete` | Preview deleting unreadable runs |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--storage-dir <storage_dir>` | Local storage directory (default: ~/.fabro/storage) |
| `--yes` | Actually delete unreadable runs (default is dry-run) |
### `fabro unarchive`
Restore archived runs to their prior terminal status
```bash
fabro unarchive [OPTIONS] <RUNS>...
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUNS` | Run IDs or workflow names to unarchive |
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro uninstall`
Uninstall Fabro from this machine
```bash
fabro uninstall [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--yes` | Skip confirmation prompt |
### `fabro upgrade`
Upgrade fabro to the latest version
```bash
fabro upgrade [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--dry-run` | Preview what would happen without making changes |
| `--force` | Upgrade even if already on the target version |
| `--prerelease` | Include prereleases (alpha, beta, rc) when selecting the latest version |
### `fabro validate`
Validate a workflow
```bash
fabro validate [OPTIONS] <WORKFLOW>
```
#### Arguments
| Name | Description |
| --- | --- |
| `WORKFLOW` | Path to the .fabro workflow file |
### `fabro variable`
Manage server-owned variables
```bash
fabro variable [OPTIONS] <COMMAND>
```
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro variable get` | Get a variable value |
| `fabro variable list` | List variables |
| `fabro variable rm` | Remove a variable |
| `fabro variable set` | Set a variable value |
#### `fabro variable get`
Get a variable value
```bash
fabro variable get [OPTIONS] <NAME>
```
#### Arguments
| Name | Description |
| --- | --- |
| `NAME` | Name of the variable to get |
#### `fabro variable list`
List variables
```bash
fabro variable list [OPTIONS]
```
#### `fabro variable rm`
Remove a variable
```bash
fabro variable rm [OPTIONS] <NAME>
```
#### Arguments
| Name | Description |
| --- | --- |
| `NAME` | Name of the variable to remove |
#### `fabro variable set`
Set a variable value
```bash
fabro variable set [OPTIONS] <NAME> [VALUE]
```
#### Arguments
| Name | Description |
| --- | --- |
| `NAME` | Name of the variable |
| `VALUE` | Value to store |
#### Options
| Option | Description |
| --- | --- |
| `--description <description>` | Optional human-readable description |
| `--value-stdin` | Read the variable value from stdin |
### `fabro version`
Show client and server version information
```bash
fabro version [OPTIONS]
```
#### Options
| Option | Description |
| --- | --- |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
### `fabro wait`
Block until a workflow run completes
```bash
fabro wait [OPTIONS] <RUN>
```
#### Arguments
| Name | Description |
| --- | --- |
| `RUN` | Run ID prefix or workflow name (most recent run) |
#### Options
| Option | Description |
| --- | --- |
| `--interval <ms>` | Poll interval in milliseconds<br />Default: `1000` |
| `--server <server>` | Fabro server target: http(s) URL or absolute Unix socket path |
| `--timeout <seconds>` | Maximum time to wait in seconds |
### `fabro workflow`
Workflow operations
```bash
fabro workflow [OPTIONS] <COMMAND>
```
#### Subcommands
| Command | Description |
| --- | --- |
| `fabro workflow create` | Create a new workflow |
| `fabro workflow list` | List available workflows |
#### `fabro workflow create`
Create a new workflow
```bash
fabro workflow create [OPTIONS] <NAME>
```
#### Arguments
| Name | Description |
| --- | --- |
| `NAME` | Name of the workflow |
#### Options
| Option | Description |
| --- | --- |
| `-g, --goal <goal>` | Goal description for the workflow |
#### `fabro workflow list`
List available workflows
```bash
fabro workflow list [OPTIONS]
```
{/* /generated:cli */}