> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sparkles.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure the CLI

> Set the default harness, model, and effort with flags, environment variables, or repository configuration.

Use a flag for one run, an environment variable for automation, or a Sparkles configuration file for a persistent default.

## Select values for one run

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sparkles \
  --runtime claude \
  --model claude-fable-5 \
  --effort ultracode
```

The relevant flags are:

| Flag        | Purpose                                          |
| ----------- | ------------------------------------------------ |
| `--runtime` | Select `claude`, `codex`, `grok`, or `opencode`  |
| `--model`   | Pass a model identifier accepted by that runtime |
| `--effort`  | Pass a reasoning level accepted by that model    |

The same flags work with a non-interactive turn:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sparkles exec \
  --runtime codex \
  --model gpt-5.6-sol \
  --effort ultra \
  "Fix the failing test"
```

## Configure environment variables

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export SPARKLES_RUNTIME=claude
export SPARKLES_MODEL=claude-fable-5
export SPARKLES_EFFORT=ultracode
```

Environment variables are useful in a shell profile or CI job. Do not use them to store local-agent credentials; the harness continues to own its own authentication.

## Configure a repository

Run `sparkles init` to create a safe committed project configuration and a gitignored local override.

Add defaults to `.sparkles/config.toml`:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
runtime = "claude"
model = "claude-fable-5"
effort = "ultracode"
```

Use `.sparkles/config.local.toml` for machine-specific choices that should not be committed.

## Configuration precedence

Sparkles resolves settings in this order, with later sources winning:

1. Built-in defaults
2. User configuration
3. `.sparkles/config.toml`
4. `.sparkles/config.local.toml`
5. `SPARKLES_*` environment variables
6. Command-line flags

Selections made with `/model` and `/effort` update the current TUI session and apply to the next message. `/agent` starts a fresh local session on the selected harness.

## Confirm the active values

The TUI footer always shows the active harness, model, and effort:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
claude · claude-fable-5 · ultracode effort
```

Use these commands when a requested value is not active:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sparkles --version
sparkles doctor
sparkles --help
```

See [Models and reasoning effort](/cli/models-and-effort) for the supported identifiers and provider-access rules.