SOLWYN
Commands

keys

List, create, rotate and revoke API keys, remove a project from a key, and hand the stored key to an SDK

keys manages the account's API keys and hands the key stored on this computer to an SDK. A key belongs to the account and holds a list of projects; every app names its project with SOLWYN_PROJECT. See API keys.

list, create, rotate, revoke and remove-project need a Solwyn login: an API key can't manage keys. create, rotate, revoke and remove-project each need a one-time browser approval and the owner or admin role. env needs no login: it reads the key stored on this computer for the selected project.

A key is shown once, when it is created or rotated, unless it is stored on this computer instead. Listing never shows key material.

The CLI creates a key for one project. Only the dashboard can add another project to a key (Settings > API keys). solwyn keys add-project exits 2 and prints that dashboard link.

keys list

List the account's live keys and their projects, and mark the projects whose key is stored on this computer.

Terminal
solwyn keys list
solwyn --json keys list

The JSON form (solwyn.keys-list.v1) carries each key's id, name, key_prefix, scope, created_via, created_by, created_at, expires_at, last_used_at, rotation_grace_until, status (active, grace or expired) and projects (each with id, name, budget_mode and dedicated_keys_only), plus stored_here, the projects this computer holds the key for. used and limit give the account's key count against its plan limit (-1 is unlimited).

Contract
Authlogin
Exit codes0 success · 1 generic/API · 3 auth
JSON schemasolwyn.keys-list.v1

keys create

Create a key for one project. With --store-key it is stored on this computer for that project and nothing secret is printed; otherwise it is shown once, with export lines.

Terminal
solwyn keys create [--project PROJECT] [--name NAME] [--scope full|read_only] [--store-key]
OptionDefaultPurpose
--project, -pthe selected projectProject name or proj_ id for the key.
--namethe project's nameKey name.
--scopefullread_only keys can read but not check budget or record spend.
--store-keyStore the new key on this computer for the project.
Terminal
$ solwyn keys create --project checkout-bot --store-key
Field                                                Value
ID                    6f1d0c9e-0000-4000-8000-0000000000f1
Name                                          checkout-bot
Key prefix                      solwyn_sk_cdcdcdcdcdcdcdcd
Scope                                                 full
Status                                              active
Projects                                      checkout-bot
Created via                                            cli
Expires                               2027-11-04T10:12:00Z
Rotation grace until                                     -
Stored                                                 yes

Without --store-key, a panel shows the full key once, followed by export SOLWYN_API_KEY='...' and export SOLWYN_PROJECT='proj_...' lines. In JSON output the key is the key field. Store it before you close the terminal; it can't be shown again.

Creating a key counts against the account's key limit. Past it, the API answers 402 with api_key_limit_reached; revoke a key or upgrade.

Contract
Authlogin (browser approval)
Exit codes0 success · 1 generic/API · 2 usage · 3 auth or storage · 6 approval
JSON schemasolwyn.keys-create.v1

keys rotate

Create a replacement that holds the same projects and reveal it once. The old key keeps working for a grace window so you can cut over without downtime.

Terminal
solwyn keys rotate <key_id> [--grace-seconds INT] [--scope full|read_only] [--yes]
OptionDefaultPurpose
KEY_IDrequiredId of the key to rotate, from keys list.
--grace-secondsserver defaultSeconds the old key keeps working, 0 through 604800 (seven days). 0 stops it at once.
--scopekeep currentScope for the replacement.
--yesAcknowledge the displayed effects without prompting.

When this computer stores the key, the stored copy is replaced and no secret is printed. Otherwise the replacement is shown once:

Terminal
$ solwyn keys rotate 6f1d0c9e-0000-4000-8000-000000000001 --grace-seconds 345600 --yes
Field                                                Value
ID                    6f1d0c9e-0000-4000-8000-0000000000f1
Name                                          checkout-bot
Key prefix                      solwyn_sk_cdcdcdcdcdcdcdcd
Scope                                                 full
Status                                              active
Projects                                      checkout-bot
Created via                                            cli
Expires                               2027-11-04T10:12:00Z
Rotation grace until                                     -
Replaced key          6f1d0c9e-0000-4000-8000-000000000001
Old key works until                   2026-11-08T10:12:00Z
Stored                                                  no
╭─────────────────────── One-time replacement API key ───────────────────────╮
│ solwyn_sk_cdcd…                                                            │
╰────────────────────────────────────────────────────────────────────────────╯

The panel prints the full key (64 hexadecimal characters after solwyn_sk_), shown here truncated. In JSON output it is the key field. The replacement expires one year after the rotation. With --grace-seconds 0, apps still using the old key on a hard-limit project have their AI calls blocked at once.

Contract
Authowner/admin login (browser approval)
Exit codes0 success · 1 generic/API · 2 usage or confirmation · 3 auth · 5 not found · 6 approval
JSON schemasolwyn.keys-rotate.v1

keys revoke

Revoke a key now, without a replacement. Use it when a key is compromised and you have already rotated, or when you retire a key for good.

Terminal
solwyn keys revoke <key_id> [--yes]

KEY_ID is the key's id from keys list; never pass key material. The command also deletes this computer's stored copies of the key.

Terminal
$ solwyn keys revoke 6f1d0c9e-0000-4000-8000-000000000001 --yes
Field                                                      Value
Key ID                      6f1d0c9e-0000-4000-8000-000000000001
Revoked                                                     true
Removed from this computer         proj_8a8a8a8a8a8a8a8a8a8a8a8a

Every app using the key stops reporting to Solwyn at once. On projects with a hard limit, or any hard cap on a model, provider, agent run or tag, their AI calls are blocked. On alert-only projects with no hard cap, their calls keep running, but Solwyn stops seeing that spend.

Contract
Authowner/admin login (browser approval)
Exit codes0 success · 1 generic/API · 2 usage or confirmation · 3 auth · 5 not found · 6 approval
JSON schemasolwyn.keys-revoke.v1

keys remove-project

Take a project away from a key. The key keeps its other projects.

Terminal
solwyn keys remove-project <key_id> --project PROJECT [--yes]

Apps using that key with SOLWYN_PROJECT set to that project stop making AI calls until they get a new key. A key keeps at least one project; revoke it instead of removing the last.

Contract
Authowner/admin login (browser approval)
Exit codes0 success · 1 generic/API · 2 usage or confirmation · 3 auth · 5 not found · 6 approval
JSON schemasolwyn.keys-remove-project.v1

rotate, revoke and remove-project show their effects on stderr, then require confirmation or --yes. Without a TTY and without --yes, they exit 2 before any request; declining, EOF and Ctrl-C send nothing. After an uncertain write, check keys list before you retry.

keys env

Print export lines for the key stored on this computer for the selected project, so an SDK can read SOLWYN_API_KEY and SOLWYN_PROJECT. The key stays in the CLI's credential store, and the hand-off creates no other file holding it.

Terminal
(solwyn_env="$(solwyn --format table keys env)" && eval "$solwyn_env" && exec python app.py)

Type or copy it as one line. This is the form solwyn keys env --help prints, with <command> in place of python app.py.

On success, keys env prints to stdout and nothing to stderr:

export SOLWYN_API_KEY='solwyn_sk_a1a1...a1a1'
export SOLWYN_PROJECT='checkout-bot'

SOLWYN_PROJECT is the value from .solwyn.env when the repository has one, else the project as you gave it. A third line exports SOLWYN_API_URL when the CLI's API URL is not the default.

Use it as above:

  • Run the app in a subshell. The parentheses keep the key and the exports inside the subshell, and exec hands them to the one command. Your shell never holds the key, so it can't reach a later command.
  • Nothing runs when the read fails. The && stops at the first failure. With no stored key for the project, keys env exits 3 with api_key_not_stored and prints its error on stderr: No API key for <project> is stored on this computer. Run solwyn keys create --project <project> --store-key. An eval of the command substitution outside a subshell hides that failure and runs your app without a key, and when the read succeeds it leaves the key exported in your shell.
  • --format table names the format the eval expects. Since 0.5.1, keys env prints export lines unless --json or --format json is on its own command line. SOLWYN_FORMAT=json and config format = "json" never apply to it. Never eval JSON output: the eval fails, and a shell such as zsh repeats the whole failing word, key included, in its error.

The project comes from --project, SOLWYN_PROJECT or the repository's .solwyn.env, in that order (see Choosing the project). If .solwyn.env names one project and --project or SOLWYN_PROJECT another, keys env exits 2 with project_mismatch before it prints anything. With a login, it turns a project name into an id through that login; without one, it matches the names of the keys stored here. It never reads SOLWYN_API_KEY and never writes .env or any other file. When the credential store itself can't be used, it exits 3 with credential_storage_failed and says what to fix. See Storage errors.

With --json or --format json on the command line, it returns solwyn.keys-env.v2: names, export (the lines), api_url, and project (selector and id).

Contract
Authlocal (the stored key; with a login, one project lookup)
Exit codes0 success · 2 usage or project mismatch · 3 no stored key or account unresolved
JSON schemasolwyn.keys-env.v2
  • Scoped login: API keys, choosing the project, where credentials are stored, and what full versus read_only allows
  • projects create: create a project and its first key
  • Dashboard: API keys: the same keys in the browser, plus adding a project to a key
  • Scripting: JSON envelopes and the exit-code contract

On this page