Configuration

The CLI keeps a small TOML file for your defaults. It holds exactly three non-secret keys, and it never holds credentials — API keys and login tokens live in your operating system's keychain, not on disk. Anything the config file sets, a flag or an environment variable can override for a single command.

api_url = "https://api.solwyn.ai"
default_project = "proj_0123456789abcdef01234567"
format = "table"

Where the file lives

The location follows platform convention via platformdirs — config.toml inside user_config_dir("solwyn"):

The directory and file are created the first time you write a value. Writes are atomic — the CLI stages a temporary file, syncs it, and replaces the config in one step under a cross-process lock, so a concurrent write or an interrupted one never leaves a half-written file. The lock is a persistent sibling file, config.toml.lock; it is normal to see it next to the config. Unknown keys are ignored on read, so downgrading the CLI never breaks on a key a newer version wrote.

A malformed file is a different matter. Every ordinary command stops with Could not load configuration. and exit 2; init reports config_load_failed and exits 1. Only doctor continues on defaults, so it is the command to run while you repair or remove the file.

The three keys

These are the only keys the CLI models. Each has a matching environment variable and a default:

The output key is format, and its only values are table and json. See Scripting and CI for what each format does.

Four more environment variables affect the CLI but have no config key, because they carry per-invocation values rather than defaults: SOLWYN_API_KEY (a project key, see Authentication), SOLWYN_AGENT_RUN_ID and SOLWYN_TAGS (run attribution for budget check, confirm, and record, see budget), and SOLWYN_CHANNEL_SECRET (a notification-channel credential, see channels).

api_url must be a credential-free absolute http or https URL. The CLI rejects a value that carries a username or password, a query string, a fragment, a backslash, or whitespace — a base_url is never a place to smuggle a secret. A port is fine. Point it at a self-hosted deployment or a local API during development:

api_url = "http://localhost:8000"

How each value resolves

Every value resolves on its own, highest priority first:

Reading and writing the file

The config command group manages the file for you, so you rarely edit the TOML by hand:

• solwyn config list — prints every key as key=value.
• solwyn config get <key> — prints a single value.
• solwyn config set <key> <value> — validates and persists one key atomically.

Only the three keys above are accepted; any other key is a usage error. These commands emit plain text and ignore the global output flags — solwyn config get format prints the bare value, never a JSON object, and the root options are not even validated ahead of a config subcommand. Full reference: solwyn config.

Two commands write this file for you. init stores the selected project as default_project and records api_url only when it differs from the default, so a fresh file may legitimately hold a single key. projects delete clears default_project when it named the project just archived.

doctor and whoami report where each value came from — flag, environment, config, or fallback — so you can see why a given URL or project was chosen.

Related

• Scripting and CI — output formats, JSON schemas, and exit codes
• Authentication — credential storage and resolution
• SDK configuration reference — the Python SDK's settings, separate from the CLI