SOLWYN
Commands

login / logout / whoami

Log in through your browser, store an API key, revoke the login and clear stored credentials, and inspect the current identity

solwyn login pairs the CLI with your browser and stores a scoped CLI login in the credential store: the OS keychain on macOS and Windows, a private 0600 file on Linux. solwyn login --with-key stores an API key instead, and solwyn login --no-store prints a login for SOLWYN_TOKEN without storing it. Keys are never accepted as command-line arguments or echoed.

For what a login can and can't do, approvals, the credential order, SOLWYN_AUTH and the stores' tradeoffs, see Scoped login.

login

Terminal
solwyn login [--scope read|read,contain] [--label <name>] [--wait <seconds>] [--continue] [--with-key] [--store auto|keyring|file] [--no-store]
OptionTypeDefaultPurpose
--scopestringread,containScopes to request: read, or read,contain.
--labelstringshort hostnameName for this login in the dashboard and in credentials list.
--waitseconds, 0 or more600 with a terminal, else 90How long to wait for browser approval. 0 starts the login and returns.
--continuebooleanfalseResume waiting for the login started earlier.
--with-keybooleanfalseRead an API key from a hidden prompt or stdin, check it with Solwyn for the selected project, and store it for that project, instead of logging in. Needs a project: --project, SOLWYN_PROJECT or .solwyn.env.
--storeauto | keyring | fileplatform defaultWhere to store credentials. Saved to config as credential_store (auto removes the setting) before the login runs, and nothing is copied between stores. SOLWYN_CREDENTIAL_STORE overrides config, and a conflicting --store is a usage error.
--no-storebooleanfalsePrint the new login token once on stdout, for SOLWYN_TOKEN, and store nothing. Can't be combined with --with-key, --continue, --store or --wait 0.
Contract
Authnone
Exit codes0 success · 1 generic/API · 2 usage · 3 auth, denied, expired or credential storage · 6 still waiting for browser approval
JSON schemasolwyn.login.v2; with --no-store, solwyn.login.token.v1

login prints a URL and a short code on stderr. Open the URL, sign in or sign up, verify your email if asked, check that the page shows the same code, and approve. The CLI never opens a browser itself, so SSH sessions and agent sandboxes work the same way. It polls at the interval the server asks for, and slows down when the server asks it to.

When the wait ends first, login keeps the pending code in the credential store and exits 6 with error code login_pending. Its detail carries user_code, verification_uri, verification_uri_complete and expires_at. After approving, run solwyn login --continue, which uses the same --wait rules. It checks the stored login first: when it is already approved, it does not show the page and code again; while it is still pending, it shows them once. The code expires after 10 minutes; --continue then exits 3 with login_expired. A denied login exits 3 with login_denied. Ctrl-C keeps the pending code too.

With --no-store nothing is kept, so there is nothing to continue. When the wait ends first it exits 3 with login_not_approved; run solwyn login --no-store again and approve it in the browser.

The login expires after 30 days and is never renewed. Run solwyn login again then. Login stores the credential and its label, scopes, expiry, account, email and role in the credential store for this API URL, and says where (Stored in; store and location in JSON). It deletes 0.3.0's session-token entries where the keyring is in use. Only the user code is printed; the credential never is, except by --no-store. See Where credentials are stored.

--with-key checks the key's shape (solwyn_sk_ followed by 64 lowercase hexadecimal characters), then checks it with Solwyn for the selected project, and stores it for that project's proj_ id. A refusal exits with the server's code, such as project_not_found or api_key_expired, and stores nothing. An invalid value never appears in an error message or a log. Storing a key in the credentials file says so and adds that CI and agents should prefer SOLWYN_API_KEY from a secret manager. Use keys env to hand a stored key to an SDK.

Never pass a key as an argument. solwyn login --with-key reads the key from a hidden prompt, or from stdin when input is piped, so nothing lands in your shell history or the process table.

Examples

Log in through the browser:

Terminal
$ 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.
Raising a cap, changing enforcement mode, pausing rules, keys, billing and team changes need your approval in the browser each time.
Field                              Value
Authentication                     login
Account                     Acme (owner)
Email                  alice@example.com
Label                         dev-laptop
Scope                      read, contain
Expires                       2026-11-29
Stored in   file (/home/alice/.local/share/solwyn/credentials.json)

Start a login for an agent to relay, then finish it after you approve:

Terminal
solwyn --json login --wait 0
solwyn login --continue

Ask for read only, with a label:

Terminal
solwyn login --scope read --label build-box

Store an API key from a hidden prompt:

Terminal
$ solwyn --project checkout-bot login --with-key
API key:
Field                                                  Value
Authentication                                   project_key
Project         checkout-bot (proj_8a8a8a8a8a8a8a8a8a8a8a8a)
Key ID                  6f1d0c9e-0000-4000-8000-000000000001
Stored in                                            keyring

Pipe an API key from a secret store, for CI:

Terminal
SOLWYN_PROJECT=checkout-bot solwyn login --with-key < solwyn.key

Keep credentials in the file even on macOS or Windows:

Terminal
solwyn login --store file

Mint a read-only login for CI or a cloud agent. The token goes to stdout once, and nothing is stored:

Terminal
solwyn login --label ci --scope read --no-store

Put it in your secret store and pass it as SOLWYN_TOKEN. Without --json, stdout is the bare token. With --json, stdout is a solwyn.login.token.v1 document, a different shape from solwyn.login.v2: it adds token and has no auth_type, store or location, because nothing is stored. The metadata fields are redacted like any other output; only token is printed in full.

{"schema":"solwyn.login.token.v1","token":"solwyn_cli_<64 hexadecimal characters>","credential_id":"6c1f2a90-0000-4000-8000-000000000001","label":"ci","scope":["read"],"expires_at":"2026-11-29T14:03:11Z","account_id":"a1","account_name":"Acme","email":"ada@example.com","role":"owner"}

A note on stderr names the label, scopes and expiry, and says nothing was stored. The login appears in credentials list under its label. See CI, containers and agents.

logout

Revoke every login stored for this API, then clear this API's stored credentials from both the credentials file and the keychain: the login, a pending login and every stored API key, plus CLI 0.3.0's old keyring entries. Logout is the one exception to store isolation: it checks both stores whatever --store or SOLWYN_CREDENTIAL_STORE says, while holding the credential lock, and it revokes before it deletes.

Terminal
$ solwyn logout
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.
Credentials                                                         Status
file (/home/alice/.local/share/solwyn/credentials.json)            cleared
keyring (the system keyring (Secret Service))                  not checked
login                                                              revoked

The table has one row per store, then a login row when a login was found. A store shows cleared, or not checked when no keyring backend is usable from this session and the keyring isn't the store in use (for example headless Linux). When a checked store keeps anything, logout prints no table: it fails with logout_incomplete (below), and the per-store report is only in that error's detail.

With --json, solwyn.logout.v1 reports cleared, revoked (null when no login was found), logins_found, and stores. Each store has store, location, status (cleared, unavailable, unreachable or unread), cleared and kept, the entries it kept. The top-level cleared covers only the stores that were checked, so an unavailable keyring has "cleared":false of its own while the top level can still be true:

{"schema":"solwyn.logout.v1","cleared":true,"revoked":true,"logins_found":1,"stores":[{"store":"file","location":"/home/alice/.local/share/solwyn/credentials.json","status":"cleared","cleared":true,"kept":[]},{"store":"keyring","location":"the system keyring (Secret Service)","status":"unavailable","cleared":false,"kept":[]}]}
Contract
Authlocal (none)
Exit codes0 success · 2 usage · 3 credential storage, or credentials kept
JSON schemasolwyn.logout.v1

When a checked store is unreachable (a delete failed or wasn't confirmed by a read, or the keyring is the store in use and has no usable backend) or unread (an entry or the credentials file couldn't be read, including a keychain read that timed out), logout exits 3 with logout_incomplete. When one store has both, unreachable wins:

Error [logout_incomplete]: Logout kept credentials it could not reach or read: /home/alice/.local/share/solwyn/credentials.json (unread).
Hint: Unlock or repair that store and run solwyn logout again. Nothing that could not be read was deleted or revoked.

The error's detail carries the same solwyn.logout.v1 report, so a script can see which store kept what ("kept":["credentials file"] for a credentials file that couldn't be read). An entry that couldn't be read is never revoked or deleted. If the credential lock can't be taken (a timeout, or a lock file that is a symbolic link or can't be opened), logout fails earlier with credential_storage_failed and detail: null. See Log out for each status.

Each revoke is one attempt with a 5-second limit. If one fails, logout says so, clears the stored credentials anyway and exits 0; revoke the login in the dashboard under Settings, CLI logins. Logout doesn't revoke API keys or a SOLWYN_TOKEN login, and doesn't touch SOLWYN_TOKEN or SOLWYN_API_KEY; unset them separately. When SOLWYN_TOKEN is set, logout says it was not revoked. To end only the login and keep the stored API key, run solwyn credentials revoke --current.

whoami

Show the credential in use and the identity behind it.

Terminal
$ solwyn whoami
Field                                                              Value
Credential      CLI login dev-laptop (read, contain), expires 2026-11-29
Authentication                                                     login
Source                                                              file
Stored in       file (/home/alice/.local/share/solwyn/credentials.json)
User                                                       Alice Example
Email                                                  alice@example.com
Email verified                                                       yes
Tier                                                          production
Account ID                                                      acct_123
Role                                                               admin
Seats                                                                3/5
Project                           proj_0123456789abcdef01234567 (my-agent)

With an API key, whoami reports the credential source and configured project, with no network call and never the key material:

Terminal
$ solwyn whoami
Field                                   Value
Credential                  API key (environment)
Authentication                    project_key
Source                            environment
Stored in         environment (SOLWYN_API_KEY)
Configured project  proj_0123456789abcdef01234567
Contract
Authany
Exit codes0 success · 1 generic/API · 2 usage · 3 auth
JSON schemasolwyn.whoami.v1

Source is keyring, file or environment, and Stored in names the store and path. Tier is one of free, production, team, or scale. Role is owner, admin, or member, the role that decides which changes you may make. See whoami for the JSON fields.

  • Scoped login: what a login can do, approvals, credential order and storage
  • credentials: list and revoke your CLI logins
  • keys: create keys, hand a stored key to an SDK, or rotate or revoke a leaked one
  • projects: create a project and store its first key
  • SDK quickstart: use an API key and SOLWYN_PROJECT from the Python SDK

On this page