Skip to main content
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

The relevant flags are: The same flags work with a non-interactive turn:

​
Configure environment variables

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:
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:
Use these commands when a requested value is not active:
See Models and reasoning effort for the supported identifiers and provider-access rules.