fabro/docs/reference/cli.mdx

---
title: "CLI Reference"
description: "Arc command-line interface reference"
---

## Global options

These flags apply to all subcommands:

| Flag | Description |
|---|---|
| `--no-dotenv` | Skip loading `.env` file |
| `--debug` | Enable DEBUG-level logging (default is INFO) |
| `-h, --help` | Print help |
| `-V, --version` | Print version |

Arc loads environment variables from `.env` in the current directory and `~/.arc/.env` (unless `--no-dotenv` is set).

## Configuration

CLI defaults can be set in `~/.arc/cli.toml` so you don't have to pass common flags every time:

```toml title="cli.toml"
[exec]
provider = "anthropic"
model = "claude-opus-4-6"
permissions = "read-write"
output_format = "text"

[llm]
model = "claude-sonnet-4-5"
```

CLI flags always override `cli.toml` values, which override hardcoded defaults.

---

## `arc run`

Launch a workflow from a `.dot` workflow file or `.toml` task config.

```bash
arc run <WORKFLOW>
arc run run.toml
arc run --run-branch arc/run/abc123
```

| Argument / Flag | Description |
|---|---|
| `<WORKFLOW>` | Path to a `.dot` workflow file or `.toml` task config. Not required when using `--run-branch`. |
| `--run-dir <DIR>` | Run output directory |
| `--dry-run` | Execute with a simulated LLM backend |
| `--preflight` | Validate run configuration without executing |
| `--auto-approve` | Auto-approve all human gates |
| `--resume <FILE>` | Resume from a checkpoint file |
| `--run-branch <BRANCH>` | Resume from a git run branch (reads checkpoint and graph from metadata branch) |
| `--model <MODEL>` | Override default LLM model |
| `--provider <PROVIDER>` | Override default LLM provider |
| `-v, --verbose` | Enable verbose output |
| `--sandbox <SANDBOX>` | Sandbox for agent tools: `local`, `docker`, `daytona`, or `exe` |
| `--label <KEY=VALUE>` | Attach a label to this run (repeatable) |
| `--goal <GOAL>` | Override the workflow goal (exposed as `$goal` in prompts) |
| `--goal-file <FILE>` | Read the goal from a file instead of inline text |
| `--no-retro` | Skip retro generation after the run |
| `--ssh` | Create SSH access to the sandbox (Daytona or exe.dev) and print the connection command |
| `--preserve-sandbox` | Keep the sandbox alive after the run finishes (for debugging) |

<Note>
`--preflight` conflicts with `--resume`, `--run-branch`, and `--dry-run`. `--run-branch` conflicts with `--resume`.
</Note>

## `arc ps`

List workflow runs stored in `~/.arc/runs`.

```bash
arc ps
arc ps --workflow deploy --label env=prod
arc ps --json
```

| Flag | Description |
|---|---|
| `--before <DATE>` | Only show runs started before this date (YYYY-MM-DD prefix match) |
| `--workflow <NAME>` | Filter by workflow name (substring match) |
| `--label <KEY=VALUE>` | Filter by label (repeatable, AND semantics) |
| `--orphans` | Include orphan directories (no `manifest.json`) |
| `--json` | Output as JSON |

## `arc system prune`

Delete old workflow runs. Dry-run by default — pass `--yes` to actually delete.

```bash
arc system prune --before 2026-01-01
arc system prune --before 2026-01-01 --yes
arc system prune --orphans --yes
```

| Flag | Description |
|---|---|
| `--before <DATE>` | Only prune runs started before this date (YYYY-MM-DD prefix match) |
| `--workflow <NAME>` | Filter by workflow name (substring match) |
| `--label <KEY=VALUE>` | Filter by label (repeatable, AND semantics) |
| `--orphans` | Include orphan directories (no `manifest.json`) |
| `--yes` | Actually delete (default is dry-run) |

---

## `arc exec`

Run an agentic coding session. The agent operates in the current directory using file, search, and shell tools.

```bash
arc exec "Add input validation to the signup form"
arc exec "Fix the failing test" --provider openai --model gpt-5.2-codex
arc exec "Refactor the auth module" --permissions full --auto-approve
```

| Argument / Flag | Description | Default |
|---|---|---|
| `<PROMPT>` | Task prompt (required) | — |
| `--provider <PROVIDER>` | LLM provider | `anthropic` |
| `--model <MODEL>` | Model name | Per provider (see below) |
| `--permissions <LEVEL>` | Permission level: `read-only`, `read-write`, or `full` | `read-write` |
| `--auto-approve` | Skip interactive prompts; deny tools outside permission level | — |
| `--debug` | Print LLM request/response debug info to stderr | — |
| `--verbose` | Print full LLM request/response JSON to stderr | — |
| `--skills-dir <DIR>` | Directory containing skill files (overrides default discovery) | — |
| `--output-format <FORMAT>` | Output format: `text` (human-readable) or `json` (NDJSON event stream) | `text` |
| `--mode <MODE>` | `standalone` (default) or `server` — in server mode, routes through the Arc API's `/completions` endpoint | `standalone` |
| `--server-url <URL>` | Arc API server URL (overrides `server.base_url` from `cli.toml`) | — |

Permission levels control which tools are auto-approved: `read-only` allows read tools (`read_file`, `grep`, `glob`, `list_dir`) and subagent tools; `read-write` adds write tools (`write_file`, `edit_file`, `apply_patch`); `full` allows all tools including shell commands. Tools outside the permission level are either interactively prompted (if a TTY is present) or denied (with `--auto-approve`). See [default models by provider](/core-concepts/models#default-models).

---

## `arc llm prompt`

Send a one-shot prompt to an LLM. Accepts a prompt as an argument, via stdin, or both (stdin is prepended).

```bash
arc llm prompt "Explain quicksort in one paragraph"
echo "Summarize this:" | arc llm prompt
arc llm prompt "Translate to French" -m claude-sonnet-4-5 -o temperature=0.3
arc llm prompt -S '{"type":"object","properties":{"name":{"type":"string"}}}' "Extract the name from: John Smith"
```

| Argument / Flag | Description |
|---|---|
| `[PROMPT]` | The prompt text (also accepts stdin) |
| `-m, --model <MODEL>` | Model to use |
| `-s, --system <SYSTEM>` | System prompt |
| `--no-stream` | Do not stream output |
| `-u, --usage` | Show token usage |
| `-S, --schema <SCHEMA>` | JSON schema for structured output (inline JSON string) |
| `-o, --option <KEY=VALUE>` | Generation options: `temperature`, `max_tokens`, `top_p`, or provider-specific keys |

## `arc llm chat`

Start an interactive multi-turn chat session. In server mode, the session is backed by the Arc server's session endpoints.

```bash
arc llm chat
arc llm chat -m claude-opus-4-6 -s "You are a helpful coding assistant"
arc llm chat --mode server
```

| Flag | Description |
|---|---|
| `-m, --model <MODEL>` | Model to use |
| `-s, --system <SYSTEM>` | System prompt |
| `--mode <MODE>` | `standalone` (default) or `server` — in server mode, routes through the Arc API |

---

## `arc model list`

List available LLM models from the built-in catalog. Running `arc model` with no subcommand also lists models.

```bash
arc model list
arc model list -p anthropic
arc model list -q sonnet
arc model list --mode server
```

| Flag | Description |
|---|---|
| `-p, --provider <PROVIDER>` | Filter by provider |
| `-q, --query <QUERY>` | Search for models matching this string (checks ID, display name, and aliases) |
| `--mode <MODE>` | `standalone` (default) or `server` — in server mode, fetches the catalog from the Arc API |

## `arc model test`

Test model availability by sending a simple prompt to each model and reporting the result.

```bash
arc model test
arc model test -p anthropic
arc model test -m claude-sonnet-4-5
```

| Flag | Description |
|---|---|
| `-p, --provider <PROVIDER>` | Filter by provider |
| `-m, --model <MODEL>` | Test a specific model |

---

## `arc serve`

Start the HTTP API server that exposes the [REST API](/api-reference) for launching and managing workflow runs.

```bash
arc serve
arc serve --port 8080 --host 0.0.0.0
arc serve --sandbox daytona --max-concurrent-runs 4
```

| Flag | Description | Default |
|---|---|---|
| `--port <PORT>` | Port to listen on | `3000` |
| `--host <HOST>` | Host address to bind to | `127.0.0.1` |
| `--model <MODEL>` | Override default LLM model | — |
| `--provider <PROVIDER>` | Override default LLM provider | — |
| `--dry-run` | Execute with simulated LLM backend | — |
| `--sandbox <SANDBOX>` | Sandbox for agent tools: `local`, `docker`, `daytona`, or `exe` | — |
| `--max-concurrent-runs <N>` | Maximum number of concurrent run executions | — |
| `--config <PATH>` | Path to server config file | `~/.arc/server.toml` |

Demo mode is per-request: send the `X-Arc-Demo: 1` header to get static demo data with auth disabled.

If no LLM provider API keys are configured, the server automatically falls back to dry-run mode.

---

## `arc cp`

Copy files between a run's sandbox and the local filesystem. The run must have a persisted sandbox record (Daytona, exe.dev, or a preserved local/Docker sandbox).

```bash
arc cp <run-id>:/path/in/sandbox ./local-dir     # download
arc cp ./local-file <run-id>:/path/in/sandbox     # upload
arc cp -r <run-id>:/output ./results              # recursive download
```

| Argument / Flag | Description |
|---|---|
| `<SRC>` | Source: `<run-id>:<path>` for sandbox, or a local path |
| `<DST>` | Destination: `<run-id>:<path>` for sandbox, or a local path |
| `-r, --recursive` | Recurse into directories |

Run IDs support prefix matching — you can use the first few characters instead of the full ID.

## `arc pr create`

Create a GitHub pull request from a completed workflow run. Uses the run's persisted manifest, conclusion, and diff. Requires a [GitHub App](/integrations/github) to be configured.

```bash
arc pr create <run-id>
arc pr create <run-id> --model claude-opus-4-6
```

| Argument / Flag | Description |
|---|---|
| `<RUN_ID>` | Run ID or prefix (required) |
| `--model <MODEL>` | LLM model for generating the PR description |

The run must have completed successfully (or with partial success) and have a `final.patch` with changes.

---

## `arc system df`

Show disk usage of Arc's data directory, including run logs, worktrees, server logs, and databases.

```bash
arc system df
arc system df -v
```

| Flag | Description |
|---|---|
| `-v, --verbose` | Show per-run breakdown |

## `arc validate`

Validate a workflow file without executing it. Reports errors and warnings. Accepts both `.dot` workflow files and `.toml` run configs.

```bash
arc validate workflow.dot
arc validate run.toml
```

| Argument | Description |
|---|---|
| `<WORKFLOW>` | Path to a `.dot` workflow file or `.toml` run config (required) |

## `arc parse`

Parse a DOT file and print its AST as JSON. Useful for debugging workflow definitions.

```bash
arc parse workflow.dot
```

| Argument | Description |
|---|---|
| `<WORKFLOW>` | Path to the `.dot` workflow file (required) |

---

## `arc init`

Initialize a new Arc project in the current git repository. Creates an `arc.toml` project config and a sample `hello` workflow.

```bash
arc init
```

The command must be run inside a git repository. It creates:
- `arc.toml` — project configuration with comments and a link to docs
- `arc/workflows/hello/workflow.dot` — a simple greeting workflow
- `arc/workflows/hello/workflow.toml` — run config for the hello workflow

## `arc diff`

Show the diff from a workflow run. Displays the `final.patch` for completed runs, or connects to the sandbox for a live diff from in-progress runs.

```bash
arc diff <run-id>
arc diff <run-id> --node work
arc diff <run-id> --stat
```

| Argument / Flag | Description |
|---|---|
| `<RUN>` | Run ID or prefix (required) |
| `--node <NODE>` | Show diff for a specific node instead of the full run |
| `--stat` | Show diffstat instead of full patch (live diffs only) |

Output is colorized when writing to a terminal.

## `arc ssh`

SSH into a Daytona sandbox from a completed or in-progress run. Creates temporary SSH credentials and connects directly, or prints the command with `--print`.

```bash
arc ssh <run-id>
arc ssh <run-id> --print
arc ssh <run-id> --ttl 120
```

| Argument / Flag | Description |
|---|---|
| `<RUN>` | Run ID or prefix (required) |
| `--ttl <MINUTES>` | SSH credential expiry in minutes (default: 60) |
| `--print` | Print the SSH command instead of connecting |

See [SSH Access](/human-tools/ssh-access) for more details on SSH workflows.

## `arc preview`

Generate a preview URL for a port exposed by a Daytona sandbox. Useful for accessing web servers, dev tools, or APIs running inside the sandbox.

```bash
arc preview <run-id> <port>
arc preview <run-id> 3000 --signed
arc preview <run-id> 3000 --open
```

| Argument / Flag | Description |
|---|---|
| `<RUN>` | Run ID or prefix (required) |
| `<PORT>` | Port number to preview (required) |
| `--signed` | Generate a signed URL (self-contained, no headers needed) |
| `--ttl <SECONDS>` | Signed URL expiry in seconds (default: 3600, requires `--signed`) |
| `--open` | Open the URL in a browser (implies `--signed`) |

Without `--signed`, the command prints the URL, token, and a `curl` example. See [Preview](/human-tools/preview) for more details.

---

## `arc doctor`

Check environment and integration health. Verifies system dependencies, API keys, and optional services. Probes live services (LLM providers, sandbox, GitHub App) by default.

```bash
arc doctor
arc doctor -v
arc doctor --dry-run
```

| Flag | Description |
|---|---|
| `-v, --verbose` | Show detailed information for each check |
| `--dry-run` | Skip live service probes (LLM, sandbox, API, web, Brave Search) |

## `arc install`

Interactive setup wizard that walks you through configuring API keys and validating your environment. Runs `arc doctor` with live probes after setup to validate the configuration.

```bash
arc install
```