Configuration
The CLI's local config file. Three non-secret keys, where it lives, and how each value resolves.
The CLI keeps a small TOML file for your defaults. It holds exactly three non-secret keys, and it never holds credentials. The project is not one of them: it comes from --project, SOLWYN_PROJECT or the repository's .solwyn.env. API keys and your Solwyn login live in the CLI's credential store, which the credential_store key chooses. Anything the config file sets, a flag or an environment variable can override for a single command.
api_url = "https://api.solwyn.ai"
format = "table"
credential_store = "file"Where the file lives
The location follows platform convention via platformdirs — config.toml inside user_config_dir("solwyn"):
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/solwyn/config.toml |
| Linux | ~/.config/solwyn/config.toml |
| Windows | %LOCALAPPDATA%\solwyn\solwyn\config.toml |
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:
| Key | Environment override | Default | Meaning |
|---|---|---|---|
api_url | SOLWYN_API_URL | https://api.solwyn.ai | Solwyn Cloud API base URL |
format | SOLWYN_FORMAT | table | Default output format — table or json |
credential_store | SOLWYN_CREDENTIAL_STORE | auto | Where credentials are stored: auto, keyring or file. solwyn login --store <mode> writes it (auto removes it). See Where credentials are stored. |
The output key is format, and its only values are table and json. See Scripting and CI for what each format does.
More environment variables affect the CLI but have no config key, because they carry per-invocation values rather than defaults: SOLWYN_TOKEN (a scoped login) and SOLWYN_API_KEY (an API key), SOLWYN_AUTH (which of them user commands use) and SOLWYN_CREDENTIALS_FILE (where the credentials file lives), all covered in Scoped login; 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:
api_url — --api-url flag → SOLWYN_API_URL → config api_url → https://api.solwyn.ai.
Project: --project / -p flag → SOLWYN_PROJECT → SOLWYN_PROJECT in the repository's .solwyn.env. A value is a project name or a proj_ id. If none of these is set and the command needs a project, it exits 2 with project_required. See Choosing the project. A default_project left in config.toml by CLI 0.4.x is ignored and dropped on the next config write, and SOLWYN_PROJECT_ID is no longer read.
Output format: --format (or --json) → SOLWYN_FORMAT → config format → table. keys env reads only the flags: SOLWYN_FORMAT and config format never make it print JSON.
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 askey=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, default_project included, exits 2 with Invalid configuration key. 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.
login --store writes this file for you: it saves its choice as credential_store. The project lives in the repository instead: init --agents and projects create --store-key write .solwyn.env, which you commit.
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.
Credentials never appear in this file. It models non-secret settings only; your API keys and Solwyn login are stored in the credential store: the OS keychain on macOS and Windows, a private 0600 file on Linux. See Scoped login and solwyn keys.
Related
- Scripting and CI — output formats, JSON schemas, and exit codes
- Scoped login: credential storage and resolution
- SDK configuration reference — the Python SDK's settings, separate from the CLI
Scoped login
How the Solwyn CLI logs in through your browser, what a CLI login can and can't do, browser approvals and exit 6, listing and revoking logins, SOLWYN_TOKEN for CI, API keys, credential order and where credentials are stored
Scripting and CI
The CLI's machine contract — two output formats, schema-bearing JSON, frozen exit codes, streaming exceptions, and budget gates for CI.