SOLWYN

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.

config.toml
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"):

PlatformPath
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:

KeyEnvironment overrideDefaultMeaning
api_urlSOLWYN_API_URLhttps://api.solwyn.aiSolwyn Cloud API base URL
formatSOLWYN_FORMATtableDefault output format — table or json
credential_storeSOLWYN_CREDENTIAL_STOREautoWhere 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:

config.toml
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 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, 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.

On this page