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
solwyn login pairs the CLI with your browser. The login it stores is scoped: it can read, stop agent runs and lower a budget cap, and every other change waits for your approval in the browser. That makes it safe to hand to a coding agent. The agent can ask for a change. Only you, signed in to the dashboard, can approve it.
The CLI stores credentials in the OS keychain on macOS and Windows, and in a private 0600 file on Linux. See Where credentials are stored. They never go in config files or command-line arguments. The CLI prints a secret only where that is the point of the command:
keys envprints the stored API key for the selected project, as export lines.keys create,keys rotateandprojects createprint a newly issued API key once, unless the key is stored on this computer (--store-key, or a rotated key this computer already holds).webhooks createandwebhooks rotateprint a one-time signing secret.login --no-storeprints a newly issued login token once, forSOLWYN_TOKEN; its metadata is still redacted.
The raw data commands costs export, alerts export and attest return the server's data byte for byte. Everything else, including errors and MCP results, redacts CLI login tokens and device codes.
Log in
$ solwyn login
To log in, open this page in a browser:
https://app.solwyn.ai/device
and enter this code:
KHJC-JKQS
Or open https://app.solwyn.ai/device?user_code=KHJC-JKQS and check that it shows the same code.
The code expires in 10 minutes. You can sign up and verify your email on that page.
Waiting for approval... (Ctrl-C to stop)
Logged in as alice@example.com to account Acme (owner) on dev-laptop.Open the URL, sign in or sign up, and verify your email if the page asks. Check that the page shows the same code, then approve. The CLI never opens a browser itself, so the same flow works over SSH and inside an agent's sandbox, and an agent can relay the URL and code to you.
| Option | Default | Purpose |
|---|---|---|
--scope | read,contain | read asks for read only. Anything else then needs an approval. |
--label | short hostname | The name for this login in the dashboard and in credentials list. |
--wait | 600 seconds with a terminal, else 90 | How long to wait for the browser. 0 starts the login and returns at once. |
--continue | Resume waiting for the login started earlier. | |
--with-key | Store an API key for a project instead. See API keys. |
When the wait ends first, the CLI keeps the pending code in the credential store and exits 6 with error code login_pending. The error's detail carries user_code, verification_uri, verification_uri_complete and expires_at, so an agent can show them to you. After you approve, run solwyn login --continue. It checks the stored login first, so an approved login finishes without showing the page and code again; a login still pending shows them once. A code expires after 10 minutes; --continue then exits 3 with login_expired. A denied login exits 3 with login_denied. This applies to stored logins; login --no-store keeps nothing to resume, so when its wait ends it exits 3 with login_not_approved and you run it again.
solwyn --json login --wait 0
solwyn login --continueWhat a login can do
A login carries two scopes, and your account role still applies on top of them.
| Scope | Allows |
|---|---|
read | Read spend, costs, budgets, alerts, runs, projects, the team and the audit trail. |
contain | Stop agent runs, and lower a project's primary budget cap. |
Everything else needs a one-time approval in the browser, each time:
- raising a cap, or any budget change other than lowering the primary cap
- changing the enforcement mode, for example
hard_denytoalert_only - removing, pausing, resuming or snoozing budget rules and thresholds, and restoring budget defaults
- creating, renaming or deleting projects, and creating, rotating or revoking keys or removing a project from a key
- billing and plan changes, including checkout and the billing portal
- channels, project notification routing, test sends, account alerts and the alert email
- webhooks, tag retirement, account rename, invitations, role changes, removals and
team leave
A login can't meter. budget check, budget confirm and record always use an API key. A login also can't approve its own requests, or do anything only the dashboard does, such as approving a login or a change, or adding a project to an API key.
Approvals and exit 6
A change a login can't make on its own returns an approval URL. The CLI prints it with a summary of the change, then waits:
$ solwyn budget set --limit 1000000 --mode alert_only
This change needs your approval in the browser:
https://app.solwyn.ai/approve/0b7d2c4e-...
Change the budget for project checkout
Budget limit: 1000.00 -> 1000000.00 (raises the cap)
Enforcement: hard_deny -> alert_only (weakens enforcement)
Waiting for approval... (expires in 10 minutes, Ctrl-C to stop)
Approved. Applying the change.Open the URL, check the change, and approve or deny it. Only the user who owns the login can approve its changes. Once you approve, the CLI sends the identical request once more, with the approval attached, and prints the command's normal output.
The global --approval-wait SECONDS option sets how long the CLI waits. The default is 600 seconds when stdin and stderr are terminals, else 90 seconds. --approval-wait 0 returns at once. Every outcome other than success exits 6, and the change is not applied:
| Error code | Meaning |
|---|---|
approval_pending | The wait ended first. The error prints the exact command to run after approving. |
approval_denied | You denied the change. |
approval_expired | The approval expired. Run the command again to request a new one. |
approval_invalid | The approval can't be used. Reason mismatch means the request changed since it was approved. Run the command again. |
approval_limit_reached | Five approvals are already pending for this login. |
The retry command
When the wait ends first, the hint names the command to run after you approve:
$ solwyn --approval-wait 0 projects create --name checkout --budget 50 --mode hard_deny --store-key
This change needs your approval in the browser:
https://app.solwyn.ai/approve/0b7d2c4e-0000-4000-8000-000000000003
Create a project
Waiting for approval... (expires in 10 minutes, Ctrl-C to stop)
Error [approval_pending]: Still waiting for approval 0b7d2c4e-0000-4000-8000-000000000003.
Hint: After approving, run: solwyn --approval 0b7d2c4e-0000-4000-8000-000000000003 projects create --name checkout --budget 50.0 --mode hard_deny --store-keyRun it exactly as printed. It repeats what you typed, adds --approval ID, and pins every value the CLI generated for the request, such as plan upgrade's --client-request-id or an absolute --until time for a relative snooze. Re-running it rebuilds the same request, so the approval matches. Change any argument and the server answers approval_invalid with reason mismatch.
In --json mode the error's detail.retry_command is the same command in POSIX shell syntax, and detail.retry_argv is an argument list with solwyn first. Use retry_argv on Windows and from automation. Secrets never appear in the command. When the first run read one from stdin or SOLWYN_CHANNEL_SECRET, the hint says to supply it the same way again.
An approval is single use and expires 5 minutes after you approve it. Whether a failed approved request spends it depends on where the failure happens:
- Rate limits come first. A
429from the route's rate limit refuses the request before an approval is asked for or used. projects createandkeys rotatespend the approval only when the change commits. A plan refusal (402), a rate limit or another refusal before the change leaves the approval approved until it expires, so the same command with--approval IDcan still use it.- Other changes spend the approval before they run. A validation error (
422) or plan refusal (402) after that means the approval is spent. Run the command again for a new one.
The CLI never re-sends a request that carries an approval. When a request fails after it was sent with one and the outcome is unclear, for example a 503 or a lost connection, the CLI says the approval may have been used. Run the retry command once more: if the server answers approval_invalid with reason consumed, request a new approval.
To check an approval, or wait for your decision from a second terminal:
solwyn approvals status 0b7d2c4e-0000-4000-8000-000000000003 --wait 120MCP tools never wait. A tool that needs an approval returns an error with the approval URL for a person to open. See approvals for the full reference.
List and revoke logins
Each solwyn login creates one CLI login, named by its --label. The list shows each login's ID, label, scopes, creation, last use and expiry, and marks the one this CLI is using. Tokens are never shown.
solwyn credentials list
solwyn credentials revoke 91be7d03
solwyn credentials revoke --currentrevoke takes a login ID or a unique prefix of at least 8 characters. --current revokes the login in use. When that is the stored login, it is also cleared from the credential store, and a stored API key stays. Logins minted with --no-store for SOLWYN_TOKEN appear in the list under their label, and revoking one leaves any stored login alone. Revocation is immediate and needs no approval: the next request with that login fails. Both commands need a login. The dashboard shows the same list under Settings, CLI logins, where you can revoke one too. See credentials.
Resetting your password ends every CLI login. Removing you from the account ends the logins for that account.
Log out
solwyn logoutlogout is the one command that ignores the selected store. Whatever --store or SOLWYN_CREDENTIAL_STORE says, it holds the credential lock and looks for this API's login in both the credentials file and the keychain without changing anything. It revokes every login it can read on the server (one attempt each, 5 seconds), and only then deletes this API's entries, the API key included, and CLI 0.3.0's old entries from both stores. If it is stopped before the delete, every login it hadn't revoked yet is still stored. Each store is reported with a status and a kept list:
| Status | Meaning | Table |
|---|---|---|
cleared | Nothing of this API is left there. | cleared |
unavailable | No keyring backend is usable from this session, and the keyring isn't the store in use, as on headless Linux. The CLI can't tell a machine without a keyring from one this session can't reach, so it claims nothing about it. | not checked |
unreachable | A delete failed. Every delete is checked by reading the entry again, so this includes a delete the store refused, one that didn't answer within 5 seconds, and one that returned while the entry is still there. Also unreachable: no usable keyring backend while the keyring is the store in use. What wasn't deleted was kept. | kept (not reachable) |
unread | An entry couldn't be read. In the keychain: a locked or denied read, no session bus for a resolved Secret Service, no answer within 5 seconds, or a login entry that isn't valid. In the file: a malformed or unreadable credentials file, for example one readable by other users. It was neither revoked nor deleted. | kept (not readable) |
When one store has both a failed delete and an entry it couldn't read, it reports unreachable: a keychain that refuses every read and every delete is unreachable, not unread.
The top-level cleared covers only the stores that were checked: it is true when every store other than an unavailable one is cleared. An unavailable keyring doesn't fail logout: it exits 0 and says on stderr No system keyring is reachable from this session, so it was not checked. If you used --store keyring in a desktop session, run solwyn logout there too.
When a checked store kept something, logout exits 3 with logout_incomplete, Logout kept credentials it could not reach or read: <store> (<status>)., and carries the full report in the error's detail: unlock or repair that store and run solwyn logout again. If the credential lock itself can't be taken (it timed out, is a symbolic link, or couldn't be opened), logout fails before checking either store, with credential_storage_failed and no detail.
If a login was read but its revoke fails, logout says so, still clears it, and exits 0; revoke the login in the dashboard under Settings, CLI logins. See logout for the output. Logout doesn't revoke API keys or a SOLWYN_TOKEN login, and doesn't touch SOLWYN_TOKEN or SOLWYN_API_KEY. To end only the login and keep the API key, run solwyn credentials revoke --current.
Expiry
A login expires 30 days after you approve it and is never renewed. whoami shows the expiry date. After it, commands that need a login fail with exit 3:
Your Solwyn login expired on 2026-11-29.
Hint: Run solwyn login.API keys
An API key belongs to your account and works for the projects listed on it. It has the shape solwyn_sk_ followed by 64 lowercase hexadecimal characters. The SDK uses one, and so do the metering commands. Every use of a key also names the project: SOLWYN_PROJECT, --project, or the repository's .solwyn.env (see Choosing the project). Keys that start with sk_proj_ no longer work.
You get a project's first key when you create it: projects create --store-key stores it on this computer for that project without printing it, and inside a git repository writes .solwyn.env naming the project. keys create --project <name> --store-key adds a key for an existing project. By default the store is the OS keychain on macOS and Windows, and the credentials file on Linux. See Where credentials are stored. The CLI keeps one key per project for each API URL.
solwyn --project checkout-bot login --with-key
echo "$SOLWYN_KEY_FROM_VAULT" | solwyn --project checkout-bot login --with-key
(solwyn_env="$(solwyn --format table keys env)" && eval "$solwyn_env" && exec python app.py)login --with-key reads a key from a hidden prompt on a terminal, or from stdin, and needs a project (--project, SOLWYN_PROJECT or .solwyn.env). It checks the key with Solwyn for that project, then stores it for that project. When the key goes to the credentials file, it says so and adds that CI and agents should prefer SOLWYN_API_KEY from a secret manager. keys env prints export SOLWYN_API_KEY=... and export SOLWYN_PROJECT=... for the stored key, so you can hand both to the SDK without writing a file. Run them in a subshell, as above: the key reaches only the command after exec, and nothing runs when keys env fails, for example with exit 3 when no key is stored for the project. keys env prints JSON only with --json or --format json on its own command line, never because of SOLWYN_FORMAT or config, and JSON output must never be passed to eval. keys env never reads SOLWYN_API_KEY. See keys env.
An API key never asks for an approval. It can do only what an API key may do: read its project, check budget and record spend. It can't change notification settings or anything account-wide.
Keys expire one year after they are created or rotated. Solwyn emails the account's owners 30 and 7 days before. An expired key fails with api_key_expired; rotate it with solwyn keys rotate KEY_ID; solwyn keys list shows the key's id.
Choosing the project
Every command, keys env and the MCP server pick the project the same way: --project, else SOLWYN_PROJECT, else SOLWYN_PROJECT in the repository's .solwyn.env (looked for from the current directory up to the git root). A value is a project name (matched without case) or a proj_ id.
.solwyn.env is written by projects create --store-key and by init --agents. It names the project and holds no secret, so commit it:
# Solwyn project for this repo. Not a secret: commit this file.
SOLWYN_PROJECT="checkout-bot"When .solwyn.env names one project and --project or SOLWYN_PROJECT names another, commands that spend or set up (keys env, login --with-key, the MCP metering tools, init, projects create --store-key, keys create --store-key) exit 2 with project_mismatch before they do anything. The error names both values, and its hint is addressed to a person: The repo's .solwyn.env names checkout-bot. Ask a person to change it if this repo should use another project. Never switch projects to get past a budget limit. Read commands use the value you gave and print the same message and hint as a warning. Changing which project a repository uses is a decision for a person, not for an agent that has hit a limit.
A name is turned into a proj_ id through your login, or, with only a key, through Solwyn's check of that key. Stored keys are only ever picked by that id, so a key for a same-named project in another account is never used. With no login and two stored keys for projects with the same name, the CLI exits 2 with project_ambiguous; use the proj_ id or log in. A renamed project's old name stops working; its proj_ id always works.
SOLWYN_PROJECT_ID and the default_project config key are gone. If SOLWYN_PROJECT_ID is set and nothing else names a project, a command that needs one exits 2 with usage_error, and so do init and projects create (when the name comes from the repository or with --store-key), before they create or store anything: SOLWYN_PROJECT_ID was replaced by SOLWYN_PROJECT (a project name or proj_ id). A default_project left in config.toml is ignored and dropped on the next config write.
Key scopes
Every API key carries a scope: full or read_only. A read_only key satisfies project reads such as status, costs, budget status and runs list, but anything that writes refuses it: budget check, budget confirm, record. The refusal is a 403 with the code read_only_key, exit 3. The SDKs refuse a read-only key outright, because they report spending.
You choose a scope when a key is created: projects create --scope for a project's first key, keys create --scope for another, keys rotate --scope for a replacement. keys list reports each key's scope. Give a read-only key to a dashboard or a monitoring job, and a full key to the SDK and to any agent that runs the budget guardrail loop.
Upgrading from CLI 0.4.x
0.5.0 stores keys per project and drops the old sk_proj_ key on its first credential write, printing Removed an old project key (sk_proj_...). Old keys stopped working; run solwyn keys create --store-key for each repo. Your login is kept. For each repository, run solwyn keys create --project <name> --store-key, and replace SOLWYN_PROJECT_ID with SOLWYN_PROJECT wherever you set it.
Credential order
Each command resolves its credential fresh, in one of two orders:
| Commands | Order |
|---|---|
Metering: budget check (and --batch), budget confirm, record, and the matching MCP tools | SOLWYN_API_KEY, then the stored API key for the selected project. Never a login. |
| Every other command and MCP tool that calls the API | SOLWYN_TOKEN, then the stored login, then SOLWYN_API_KEY, then the stored API key for the selected project. |
The logins come first, so exporting SOLWYN_API_KEY for the SDK doesn't hide them. An invalid SOLWYN_TOKEN is an error, never skipped. An expired stored login counts as absent, because the CLI keeps its expiry locally and moves on to the next credential. SOLWYN_TOKEN carries no local expiry: once it expires, the API rejects it with cli_credential_expired (exit 3) and the command does not fall back to an API key. An empty or invalid SOLWYN_API_KEY still stops fallback to the stored key when the key is next in line. Credentials are stored per API URL, so a login made with --api-url http://localhost:8080 is never sent to https://api.solwyn.ai.
SOLWYN_AUTH overrides the order for user commands:
| Value | Effect |
|---|---|
project_key | Skip both logins and use an API key. |
login | Require SOLWYN_TOKEN or the stored login, with no fallback to a key. |
Any other non-empty value is a usage error (exit 2); an empty value counts as unset. Metering commands ignore the variable and always use an API key.
SOLWYN_AUTH=project_key solwyn budget statusIf nothing resolves, the command exits 3 with authentication_required and the hint Run solwyn login, or set SOLWYN_TOKEN (a login) or SOLWYN_API_KEY (an API key) in the environment., naming the store and path it looked in. A metering command with no API key says Metering needs an API key for the project. Set SOLWYN_API_KEY and SOLWYN_PROJECT, or run solwyn keys create --project PROJECT --store-key.
Where credentials are stored
Everything the CLI stores (the login, a pending login code and an API key) lives in a credential store, kept per API URL, so a login made with --api-url http://localhost:8080 is never sent to https://api.solwyn.ai.
| Platform | Default store (auto) |
|---|---|
| macOS | The macOS Keychain. If it can't be used, for example a locked Keychain over SSH, the command fails; it never falls back to the file. |
| Windows | Windows Credential Manager, with local persistence so it doesn't roam with a domain profile. Over SSH, where it can't persist, the command fails; it never falls back to the file. |
| Linux (desktop, headless, WSL, containers, CI) | The credentials file. |
The credentials file is credentials.json in your user data directory: ~/.local/share/solwyn/ on Linux ($XDG_DATA_HOME/solwyn/ when set to an absolute path; a relative XDG_DATA_HOME, XDG_STATE_HOME or XDG_CONFIG_HOME is ignored and the platform default is used), ~/Library/Application Support/solwyn/ on macOS, and %LOCALAPPDATA%\solwyn\ on Windows. SOLWYN_CREDENTIALS_FILE, an absolute path, moves it. On Linux and macOS the file is 0600, written atomically, and its directory must belong to you: the CLI creates it 0700 and removes group and world access from an existing one. The file is opened without following symbolic links and checked on the open descriptor before it is read.
The file is plaintext, protected only by those permissions. Anything running as you can read it, including backup tools and an AI agent's file tools, and unencrypted backups copy it. A Linux keyring does better at rest: it stores secrets encrypted, and while it is locked, programs can't retrieve them. Once your session unlocks it, though, any program running as you can ask it for a secret (see the GNOME Keyring security FAQ). Linux still defaults to the file because agent hosts and headless sessions often can't reach or unlock a keyring. Codex, for example, starts MCP servers without the session bus the keyring needs, and an SSH or CI session usually has no unlocked keyring at all. If your desktop session has an unlocked keyring that your tools can reach, --store keyring keeps the credential encrypted at rest. What sits in the file is bounded: a login is scoped, expires after 30 days and can be revoked. An API key reaches only the projects listed on it, with a full or read_only scope, and expires one year after it is created or rotated (the account's owners get reminder emails 30 and 7 days before). It can still spend from those projects until then, so storing one in the file says where it went and suggests a secret manager for CI and agents. Keep the credentials directory out of dotfile sync and unencrypted backups. For CI and agents, prefer SOLWYN_API_KEY from a secret manager.
Choosing the store
Every command reads and writes exactly one store: SOLWYN_CREDENTIAL_STORE if it is set, else credential_store in config, else auto. Pending logins (--wait 0) live in that store too, so solwyn login --continue finds them. Stores are never copied or merged: credentials in the store not in use are never read, and only solwyn logout deletes.
| Store | Behavior |
|---|---|
auto | The platform default above. |
keyring | The OS keychain (macOS Keychain, Windows Credential Manager, or the Linux Secret Service or KWallet). Plaintext keyrings.alt backends are refused, global keyring settings are ignored, and each call times out after 5 seconds. |
file | The credentials file only. The keyring is never touched, except by solwyn logout. |
solwyn login --store auto|keyring|file saves the mode to config as credential_store (auto removes the setting) and then logs in to that store. It copies nothing. The mode is saved before the login, so if the login then fails, the new mode stays in config. A --store that conflicts with SOLWYN_CREDENTIAL_STORE is a usage error.
There is no fallback. When the keychain is the store in use (keyring, or auto on macOS and Windows) and it can't be used:
- A write counts only once a read returns the new value. If the write call reports an error but a read then returns the new value, it counts as stored and the command succeeds.
Nothing was storedis said only when a read shows the new value isn't in the keychain: the write call failed and the value is absent, or the keychain silently dropped it (The system keyring did not keep the new value.). The same applies when no keyring backend is usable at all. The command exits3withcredential_storage_failed, naming the keychain and why.- When the outcome can't be known, the error says the write is unconfirmed, never unstored. That covers a write that doesn't answer within 5 seconds, and a write whose checking read also fails: a keychain that refuses reads as well as writes, such as a wholly locked one, or a Secret Service session that drops mid-write. The error says
Could not confirm the write to <keychain>: <reason> It may or may not have been stored. Run solwyn logout to clear this API's stored credentials.After a failed read-back, the reason ends withThe new value could not be read back.It carries the same--store filehint. - In either failure, a browser login that the server already issued is revoked, because its storage wasn't confirmed, and a
--wait 0login shows no code. - Every read fails with
credential_storage_failedtoo, including a read that doesn't answer within 5 seconds. The CLI can't know whether a login is stored, so it doesn't fall through toSOLWYN_API_KEYeither.
Could not write to the macOS Keychain: <reason> Nothing was stored.
Hint: Run solwyn login --store file, or set SOLWYN_CREDENTIAL_STORE=file.A keychain delete, too, counts only once a read finds the entry gone. A failed read adds To use SOLWYN_API_KEY without the keychain, set SOLWYN_AUTH=project_key. On Linux the hint also says that an MCP host must pass DBUS_SESSION_BUS_ADDRESS and XDG_RUNTIME_DIR to the server to keep the keyring. SOLWYN_TOKEN is read before the store, so it works with an unusable keychain. On Linux in auto mode, nothing touches the keyring: no D-Bus probe, no delay.
Leftover credentials. When the keychain is in use but the credentials file still holds credentials for this API, whoami and doctor say so and suggest solwyn logout, which clears both stores. When the file is in use they never probe the keychain.
One lock. Every read and change of stored credentials holds one per-user lock, credentials.lock in your user state directory (~/.local/state/solwyn/ on Linux, $XDG_STATE_HOME/solwyn/ when set to an absolute path), wherever SOLWYN_CREDENTIALS_FILE points. Reads share it and changes hold it alone, so concurrent CLI and MCP processes never interleave. A command that waits more than 10 seconds for it fails with credential_storage_failed. If a keychain write or delete doesn't finish within 5 seconds, the command fails and that process never releases the lock or touches stored credentials again, so the unfinished write can't land after another process has moved on. A one-off command simply exits. A long-running MCP server must be restarted.
A login keeps the store it started with. A browser login resolves its store once, when it starts, and stores the pending code and the final login there. If the store setting changes before the login is stored, for example through solwyn config set credential_store file in another terminal during the browser wait, the command exits 3 with credential_storage_failed, The credential store changed from <old> to <new> while this login was in progress. Nothing was stored., and the new login is revoked. solwyn config set credential_store <mode> and --store change the setting under the exclusive credential lock.
Storage errors
These stop the command with credential_storage_failed (exit 3) and say what to fix:
- the keychain in use can't be read or written (see above)
- the credentials file is readable by other users (the error names the
chmod 600to run), or is owned by another user - the file is a symbolic link, or isn't a regular file: a FIFO or a device is refused at once, without waiting on it (
is not a regular file) - the credentials directory is owned by another user (set
SOLWYN_CREDENTIALS_FILEto a path in a directory you own) - the file isn't a valid Solwyn credentials document, including one that isn't valid JSON or UTF-8, or one with an incomplete login, pending login or API key (move it aside and run
solwyn login) - an API key stored for a project isn't valid. The error says to remove it, store a new key with
solwyn keys create --project <proj_id> --store-key, and, to revoke the old key too, runsolwyn keys revoke KEY_IDwith its id from the dashboard (Settings > API keys) - a stored login, in the file or the keychain, isn't valid. This is an error, never skipped in favor of a stored API key
- the credential lock timed out, is a symbolic link, or couldn't be opened
keys env reports these errors too, instead of saying no key is stored. An unexpected failure storing a browser login revokes it and reports The new login could not be stored.; if that revoke fails too, the error says the login is still active and where to revoke it. An unexpected failure storing a key with --with-key reports The API key could not be stored.
Login, whoami, logout and every missing-credential error name the store and path in use.
Upgrading from CLI 0.3.0
0.3.0 kept its session login (access_token and refresh_token) and an API key (api_key) in the system keyring under the service solwyn-cli. 0.4.0 never reads or sends them, on any platform, and migrates nothing. At a terminal, when a command finds no credential, it checks whether they are still there and says so once: run solwyn login again for the login, and solwyn login --with-key again, or set SOLWYN_API_KEY, for the key. Nothing is checked in file mode or without a terminal, such as in an MCP server or CI. solwyn login deletes the old entries where the keyring is in use, and solwyn logout always deletes them.
What each command requires
Every command's --help states its requirement on the Auth: line.
| Credential | Commands |
|---|---|
| API key only | budget check, budget confirm, record; writes need a full-scope key |
| Login | overview, audit, projects list, keys list, channels list/show, account alert-email show, account phone show, alerts account show/preview, alerts activity/pending, alerts … --account, costs --account, attest --account, team members list, team invites list, plan change --dry-run, credentials, approvals status, and opt-in --with-last-fired reads |
| Login, no approval | runs stop, and budget set when it only lowers the primary cap |
| Login and an approval | Every other write: projects create/rename/delete, keys create/rotate/revoke/remove-project, other budget set changes, budget restore-defaults, budget rule and threshold writes, webhook writes, tags retire, team invites send/resend/revoke, team members set-role/remove, team leave, billing writes, account rename, account alert-email set/clear, channel and account-alert writes, and notification writes and tests made with a login |
| Either | status, whoami, forecast, budget status/uncounted, ordinary budget rules list, rule preview, project costs and analytics, providers, runs list/show, tags list/values, project alert history and export, project attest, notifications show, projects show, plan, plan list |
| Optional | doctor; init runs the browser login when nothing is stored |
| None | login, logout, config, keys env (it reads the stored key; with a login it also looks up the project's id), agent-context, mcp-config; invite show makes a credential-free preview read |
Your account role still applies. Project, key, budget, rule, run-stop, webhook and tag writes, and every invitation command including team invites list, need the owner or admin role. Billing, role changes, account rename, the alert email, channels and account alerts need the owner. An approval never adds rights your role doesn't have.
notifications set and the notification tests need a login: API keys can't change notification settings (403 api_key_not_allowed). notifications set takes an owner or admin login with an approval.
Errors
Authentication and authorization failures exit 3:
| Situation | Code | Hint |
|---|---|---|
| The login is unknown, expired or revoked | cli_credential_invalid, cli_credential_expired, cli_credential_revoked | Run solwyn login. |
| A login-only command resolved an API key | login_required or authentication_required | Run solwyn login, or set SOLWYN_TOKEN, and retry. If SOLWYN_AUTH=project_key is set, unset it. |
| A read-only key attempted a write | read_only_key | Rotate it to a full-scope key with solwyn keys rotate KEY_ID --scope full, or create one with solwyn keys create. |
| The key doesn't reach the selected project, or no project has that name | project_not_found (exit 2) | Check the name, or use the proj_ id. A renamed project's old name stops working. |
| The project only accepts keys dedicated to it | key_not_dedicated | Use a key that holds only this project: solwyn keys create --project <name> --store-key. |
| The key expired, or is unknown or revoked | api_key_expired, api_key_invalid | Rotate it with solwyn keys rotate KEY_ID (solwyn keys list shows the id), or create a new one. |
| An API key tried something only a login may do | api_key_not_allowed | Run solwyn login. |
| Your role can't perform the action | owner_required, admin_required, role_required, permission_required | Your role can't perform this action; use solwyn whoami to inspect it. |
A 402, a plan-tier or quota limit, is not an authorization failure. It exits 1.
If a request fails with account_membership_revoked, logging in again won't help: a login belongs to one account. Create a personal account in the dashboard at app.solwyn.ai/no-account, then run solwyn login.
CLI 0.3.0 and earlier log in with an email and password. The API now refuses that with cli_password_login_retired. Install 0.4.0 or newer with a new requirement, because uv tool upgrade keeps an old ==0.3.0 pin: uv tool install --python 3.11 'solwyn-cli>=0.5.1', pipx install --force 'solwyn-cli>=0.5.1' or python -m pip install --upgrade 'solwyn-cli>=0.5.1'. Then check that solwyn login --help lists --wait, and run solwyn login. See Upgrade from 0.3.0.
CI, containers and agents
Pipelines and cloud agents have no stored login. Give them credentials through the environment, from your secret store:
SOLWYN_TOKENfor reads. A scoped login, so the job never holds a full-scope API key just to read. It expires after 30 days and can be revoked.SOLWYN_API_KEYandSOLWYN_PROJECTfor metering.budget check,budget confirmandrecordalways need an API key, and every key request names its project.
Mint the token once, from your own machine:
solwyn login --label ci --scope read --no-store--no-store runs the browser login and prints the token once on stdout. With --json it prints a solwyn.login.token.v1 document instead of solwyn.login.v2: the token and its metadata, with no auth_type, store or location. See login. Nothing is stored, not even the pending code, so it can't be combined with --with-key, --continue, --store or --wait 0. Put the token in your CI secret store as SOLWYN_TOKEN. It appears in solwyn credentials list under its label. Mint a new one before it expires after 30 days, and revoke the old one with solwyn credentials revoke or in the dashboard.
jobs:
check-budget:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: pip install 'solwyn-cli>=0.5.1'
- run: solwyn budget status
env:
SOLWYN_PROJECT: ${{ vars.SOLWYN_PROJECT }}
SOLWYN_TOKEN: ${{ secrets.SOLWYN_TOKEN }}A job that meters spend needs an API key, because metering never uses a login:
jobs:
reserve-budget:
runs-on: ubuntu-latest
steps:
- run: pip install 'solwyn-cli>=0.5.1'
- run: >-
solwyn budget check
--provider openai --model gpt-4o
--estimated-input-tokens 1200 --estimated-output-tokens 400
env:
SOLWYN_PROJECT: ${{ vars.SOLWYN_PROJECT }}
SOLWYN_API_KEY: ${{ secrets.SOLWYN_API_KEY }}budget check, budget confirm and record need a full-scope key. A read-only key passes every read in a pipeline and then fails the first write with exit 3. See Scripting for the machine contract.
macOS and Windows runners, SSH and sandboxes
On macOS and Windows the default store is the keychain, and there is no fallback to the file. On a CI runner, over SSH, or inside a sandbox, the keychain is often locked or unreachable. Any command that reads stored credentials then fails with credential_storage_failed, even when SOLWYN_API_KEY is set, because the CLI can't tell whether a login is stored. To avoid that:
- Set
SOLWYN_CREDENTIAL_STORE=filein CI and other unattended jobs. The keychain is then never touched, andSOLWYN_TOKENandSOLWYN_API_KEYfrom your secret store work as on Linux. SOLWYN_TOKENis read before any store, so a job with a token never touches the keychain for user commands. Metering commands readSOLWYN_API_KEYfirst, so they don't touch it either while that variable is set.- With only
SOLWYN_API_KEYand the keychain in use, user commands such asbudget statusneedSOLWYN_AUTH=project_keyto skip the stored login. - Over SSH to a Mac, unlock the login keychain first (for example with
security unlock-keychain), or log in withsolwyn login --store file.
jobs:
check-budget:
runs-on: macos-latest
steps:
- run: pip install 'solwyn-cli>=0.5.1'
- run: solwyn budget status
env:
SOLWYN_PROJECT: ${{ vars.SOLWYN_PROJECT }}
SOLWYN_CREDENTIAL_STORE: file
SOLWYN_TOKEN: ${{ secrets.SOLWYN_TOKEN }}Coding agents
A coding agent on your machine uses your login for reads and the API key for metering. On macOS and Windows, its commands and the MCP server it starts need the keychain too. If the agent runs them in a sandbox or session that can't use the keychain, they fail with credential_storage_failed: log in with solwyn login --store file instead, or give a cloud agent SOLWYN_TOKEN and SOLWYN_CREDENTIAL_STORE=file. If a keychain call times out inside a running MCP server, that server stops touching stored credentials until the host restarts it. See Set up Solwyn with your coding agent and Agent integration.
Check your state
solwyn whoamiwhoami names the credential in use first, for example Credential: CLI login dev-laptop (read, contain), expires 2026-11-29, or Credential: API key (environment). With a login it also shows your identity, account, role, seats and projects. See whoami. doctor goes further and probes the API with the resolved credential.
Next steps
login/logout: the command referencecredentialsandapprovals- Configuration: set the API URL and output defaults in
config.toml init: one-command onboarding that logs in and verifies the setupkeys: list, create, rotate and revoke keys, and hand the stored key to your app