---
title: "CLI Configuration"
description: "Configure default settings for the Arc CLI with cli.toml"
---

Arc loads CLI defaults from `~/.arc/cli.toml` so you don't have to pass common flags every time. The file is optional — if it doesn't exist, built-in defaults are used.

## File location

The default path is `~/.arc/cli.toml`. Arc silently skips loading if the file is missing.

## Precedence

CLI flags always take the highest priority:

1. **CLI flags** — always win
2. **`cli.toml`** — used when no flag is provided
3. **Built-in defaults** — used when neither flag nor config is set

## Full example

```toml title="cli.toml"
verbose = true
mode = "server"

[server]
base_url = "https://arc.example.com:3000"

[server.tls]
cert = "~/.arc/tls/client.crt"
key = "~/.arc/tls/client.key"
ca = "~/.arc/tls/ca.crt"

[exec]
provider = "anthropic"
model = "claude-opus-4-6"
permissions = "read-write"
output_format = "text"

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

[log]
level = "info"

[git.author]
name = "arc-bot"
email = "arc-bot@company.com"

[pull_request]
enabled = true

[mcp_servers.filesystem]
type = "stdio"
command = ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
startup_timeout_secs = 15
tool_timeout_secs = 90

[mcp_servers.filesystem.env]
NODE_ENV = "production"

[mcp_servers.sentry]
type = "http"
url = "https://mcp.sentry.dev/mcp"

[mcp_servers.sentry.headers]
Authorization = "Bearer sk-xxx"
```

All fields are optional. You can include just the sections and keys you want to override.

## `verbose`

Enable verbose output by default for `arc run start` and `arc doctor`, without passing `-v` every time.

| Value | Description |
|---|---|
| `true` | Verbose output on by default |
| `false` | Normal output (default) |

The `-v` / `--verbose` CLI flag always takes effect regardless of this setting.

## `[exec]` section

Defaults for `arc exec` sessions.

| Key | Description | Values | Default |
|---|---|---|---|
| `provider` | LLM provider | `"anthropic"`, `"openai"`, `"gemini"`, etc. | `"anthropic"` |
| `model` | Model name | Any model ID from `arc model list` | Per provider |
| `permissions` | Tool permission level | `"read-only"`, `"read-write"`, `"full"` | `"read-write"` |
| `output_format` | Output format | `"text"`, `"json"` | `"text"` |

### Permission levels

- **`read-only`** — auto-approves 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 interactively prompted (if a TTY is present) or denied (with `--auto-approve`).

### Output formats

- **`text`** — human-readable terminal output
- **`json`** — NDJSON event stream

## `[llm]` section

Defaults for `arc llm prompt` and `arc llm chat`.

| Key | Description | Values | Default |
|---|---|---|---|
| `model` | Model name | Any model ID from `arc model list` | Per provider |

<Note>
The `[llm]` section only sets the default model. Use `[exec]` to configure provider, permissions, and output format for `arc exec`.
</Note>

## `[log]` section

Configure the default log level. Precedence: `ARC_LOG` env var > `--debug` flag > `[log]` level > `"info"`.

| Key | Description | Values | Default |
|---|---|---|---|
| `level` | Log level | `"error"`, `"warn"`, `"info"`, `"debug"`, `"trace"` | `"info"` |

## `[git]` section

### `[git.author]`

Customize the git author identity used for checkpoint commits. Overrides the server default when set.

| Key | Description | Default |
|---|---|---|
| `name` | Git author name | `"arc"` |
| `email` | Git author email | `"arc@local"` |

## `mode`

Controls whether commands run in-process or delegate to a running Arc API server.

| Value | Description |
|---|---|
| `"standalone"` | Execute locally (default) |
| `"server"` | Delegate to an Arc API server |

Override with the `--mode` CLI flag:

```bash
arc --mode server models list
```

## `[server]` section

Configuration for server mode.

| Key | Description | Default |
|---|---|---|
| `base_url` | Server URL | `"http://localhost:3000"` |

Override the URL with the `--server-url` CLI flag:

```bash
arc --mode server --server-url https://arc.example.com:3000 models list
```

### `[server.tls]` section

Optional mTLS configuration for authenticating with the server. When present, the CLI presents a client certificate during the TLS handshake.

| Key | Description |
|---|---|
| `cert` | Path to client certificate PEM file |
| `key` | Path to client private key PEM file |
| `ca` | Path to CA certificate PEM file (to verify the server) |

Paths support `~/` expansion. Example:

```toml title="cli.toml"
[server.tls]
cert = "~/.arc/tls/client.crt"
key = "~/.arc/tls/client.key"
ca = "~/.arc/tls/ca.crt"
```

## `[pull_request]`

Enable auto-PR globally so workflows open a GitHub pull request on successful completion — even when running with a `.dot` file instead of a `run.toml`.

```toml title="cli.toml"
[pull_request]
enabled = true
```

| Key | Description | Default |
|---|---|---|
| `enabled` | Automatically create a PR after successful runs | `false` |

Precedence: `run.toml` > `cli.toml` > `server.toml` > built-in default (`false`).

## `[mcp_servers]` section

Configure [MCP servers](/agents/mcp) to connect to during `arc exec` sessions. Each server is a named TOML table under `[mcp_servers]`. MCP servers can also be configured per-workflow in [run config TOML](/execution/run-configuration#mcp_servers).

### Stdio transport

Spawn a local process and communicate over stdin/stdout:

```toml title="cli.toml"
[mcp_servers.filesystem]
type = "stdio"
command = ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
startup_timeout_secs = 15
tool_timeout_secs = 90

[mcp_servers.filesystem.env]
NODE_ENV = "production"
```

| Key | Description | Default |
|---|---|---|
| `type` | Must be `"stdio"` | — |
| `command` | Array: executable + arguments | — |
| `env` | Additional environment variables for the child process | `{}` |
| `startup_timeout_secs` | Max seconds for the MCP handshake | `10` |
| `tool_timeout_secs` | Max seconds for a single tool call | `60` |

### HTTP transport

Connect to a remote MCP server over Streamable HTTP:

```toml title="cli.toml"
[mcp_servers.sentry]
type = "http"
url = "https://mcp.sentry.dev/mcp"

[mcp_servers.sentry.headers]
Authorization = "Bearer sk-xxx"
```

| Key | Description | Default |
|---|---|---|
| `type` | Must be `"http"` | — |
| `url` | The MCP server endpoint URL | — |
| `headers` | Optional HTTP headers (e.g., for authentication) | `{}` |
| `startup_timeout_secs` | Max seconds for the MCP handshake | `10` |
| `tool_timeout_secs` | Max seconds for a single tool call | `60` |

### Sandbox transport

Run an MCP server inside the workflow's sandbox and connect via preview URL. Only available with remote sandbox providers ([Daytona](/integrations/daytona)) that support port previews. Typically configured in [run config TOML](/execution/run-configuration#mcp_servers) rather than `cli.toml`.

```toml title="run.toml"
[mcp_servers.playwright]
type = "sandbox"
command = ["npx", "@playwright/mcp@latest", "--port", "3100", "--headless"]
port = 3100
startup_timeout_secs = 60
tool_timeout_secs = 120
```

| Key | Description | Default |
|---|---|---|
| `type` | Must be `"sandbox"` | — |
| `command` | Array: the command to run inside the sandbox | — |
| `port` | Port the server listens on inside the sandbox | — |
| `env` | Additional environment variables for the server process | `{}` |
| `startup_timeout_secs` | Max seconds for startup + MCP handshake | `10` |
| `tool_timeout_secs` | Max seconds for a single tool call | `60` |

See [MCP — Sandbox transport](/agents/mcp#sandbox) for how Arc launches and connects to sandbox MCP servers.