SOLWYN
Commands

projects

Create, list, inspect, rename, and archive Solwyn projects from the CLI

projects has five subcommands. list requires a Solwyn login; create, rename and delete require an owner/admin login with project.write, and each needs a one-time browser approval. show accepts either credential with project access. With only an API key, a login-only subcommand exits 3 before any request.

projects create

Create a project and capture its first API key exactly once. That key holds only this project.

Terminal
solwyn projects create [--name <name>] [--budget FLOAT] [--period daily|weekly|monthly] [--mode alert_only|hard_deny] [--scope full|read_only] [--store-key]
OptionTypeDefaultPurpose
--namestring, ≤ 100 charsthe repository's nameName for the new project: letters, digits, spaces, ., _ and -. Inside a git repository it defaults to the repository's folder name; elsewhere it is required.
--budgetfloat > 0100.0Initial budget in USD.
--perioddaily | weekly | monthlymonthlyInitial budget period.
--modealert_only | hard_denyalert_onlyInitial enforcement mode.
--scopefull | read_onlyAPI defaultScope of the project's first key. Omitted from the request when not passed.
--store-keybooleanfalseStore the new key on this computer for the project instead of printing it, and write .solwyn.env if the repository has none.
Contract
Authowner/admin login (project.write)
Exit codes0 success · 1 generic/API · 2 usage · 3 auth · 6 browser approval required, pending, denied or expired
JSON schemasolwyn.projects-create.v1

The new API key is revealed exactly once, in a panel below the metadata. Save it before you close the terminal. It cannot be retrieved again. Pass --store-key to store it on this computer for the project (the OS keychain on macOS and Windows, a private 0600 file on Linux), in which case it is stored rather than printed. If storing fails, the command exits 3 and never falls back to displaying the key. Without --store-key, export SOLWYN_API_KEY=... and export SOLWYN_PROJECT=... lines follow the panel.

Terminal
$ solwyn projects create --name my-agent --budget 50 --mode hard_deny
Field                                         Value
ID                    proj_21c50805b553b7a40e48394a
Name                                       my-agent
Budget limit                                  50.00
Budget period                               monthly
Budget mode                               hard_deny
Created                        2026-07-10T12:30:00Z
Key ID         6f1d0c9e-0000-4000-8000-0000000000c1
Key prefix               solwyn_sk_abababababababab
Scope                                          full
Key expires                    2027-07-10T12:30:00Z
╭───────────────────────────── One-time API key ─────────────────────────────╮
│ solwyn_sk_abab…                                                            │
╰────────────────────────────────────────────────────────────────────────────╯
export SOLWYN_API_KEY='solwyn_sk_abab…'
export SOLWYN_PROJECT='my-agent'

The panel prints the full key (solwyn_sk_ followed by 64 hexadecimal characters), shown here truncated. In JSON output it is the key field. Give it to the Python SDK or the TypeScript SDK as SOLWYN_API_KEY, with SOLWYN_PROJECT beside it, or store it with solwyn --project my-agent login --with-key.

With --store-key, no panel is printed; the table shows Stored true instead, and the JSON payload carries "stored": true in place of key. Inside a git repository with no .solwyn.env, it also writes one naming the project:

.solwyn.env
# Solwyn project for this repo. Not a secret: commit this file.
SOLWYN_PROJECT="my-agent"

With only the retired SOLWYN_PROJECT_ID set, projects create exits 2 with usage_error before it creates anything when the name would come from the repository or --store-key is passed. An existing .solwyn.env is never overwritten; if it names another project, the command says .solwyn.env already names <other>; not changed. Then solwyn keys env hands the key and the project to your app. See Choosing the project.

A project created with --mode hard_deny accepts only keys dedicated to it, so its key can't be widened to reach other projects. A read_only first key can read budgets and costs but cannot run budget check; pick full for a key an agent or the SDK will spend with. See Key scopes. Creating a project counts its key against the account's key limit (402 api_key_limit_reached past it).

Creation requires Core's project.write permission (owner/admin). A member is refused with exit 3. Creation also needs a one-time browser approval. The CLI prints the approval URL and waits; when the wait ends first, it exits 6 and prints the exact retry command to run after you approve. With --store-key, the key goes to the credential store only when the approved request succeeds. The creation request is never automatically retried or replayed; inspect projects after an uncertain response before deliberately trying again.

projects list

List every project your login can reach.

Terminal
$ solwyn projects list
ID             Name         Budget  Period   Mode        Created
proj_0123456789abcdef01234567  my-agent     100.00  monthly  alert_only  2026-06-01T09:00:00Z
proj_89abcdef0123456789abcdef  staging-bot   25.00  daily    hard_deny   2026-06-14T16:45:00Z
Contract
Authlogin
Exit codes0 success · 1 generic/API · 2 usage · 3 auth
JSON schemasolwyn.projects-list.v1

projects show

Show a project, by name or proj_ id.

Terminal
$ solwyn --project proj_0123456789abcdef01234567 projects show
Field          Value
ID             proj_0123456789abcdef01234567
Name           my-agent
Budget limit   100.00
Budget period  monthly
Budget mode    alert_only
Created        2026-06-01T09:00:00Z

The project comes from --project, SOLWYN_PROJECT or the repository's .solwyn.env. See Choosing the project. Under an API key, a response for any other project is rejected.

Contract
Authany (API key or login)
Exit codes0 success · 1 generic/API · 2 usage · 3 auth · 5 not found
JSON schemasolwyn.projects-show.v1

projects rename

Rename a project. Owner or admin.

Terminal
$ solwyn projects rename proj_0123456789abcdef01234567 --name billing-agent
Field          Value
ID             proj_0123456789abcdef01234567
Name           billing-agent
Budget limit   100.00
Budget period  monthly
Budget mode    alert_only
Created        2026-06-01T09:00:00Z
OptionTypeDefaultPurpose
PROJECT_IDargumentrequiredThe project to rename. Positional — this command does not use the global --project.
--namestring, ≤ 100 charsrequiredThe new name.
Contract
Authlogin (owner or admin)
Exit codes0 success · 1 generic/API · 2 usage · 3 auth · 5 not found · 6 browser approval required, pending, denied or expired
JSON schemasolwyn.projects-rename.v1

If the repository's .solwyn.env names the old name, the CLI updates it and says Updated <path> to <new name>. If the file changes while the CLI is updating it, the other change is kept, the CLI says so (Did not update <path>: it changed while the CLI was updating it, ...) and the rename still exits 0; check the file names the project you want. It then prints Apps that set SOLWYN_PROJECT=<old> will fail at their next start. Update SOLWYN_PROJECT or use the proj_ id. Running apps keep working, because the SDKs pin the proj_ id when they validate.

A blank or over-long name exits 2 before any request. A member-role login is refused with exit 3 and a hint to check your role with solwyn whoami.

projects delete

Irreversibly archive a project. Keys stop reaching it in the same transaction, and a key left with no project is revoked. Owner or admin.

Terminal
solwyn projects delete <project_id> --yes
OptionTypeDefaultPurpose
PROJECT_IDargumentrequiredThe project to archive. Positional.
--yesbooleanfalseAcknowledge that the deletion is irreversible. Mandatory.
Contract
Authlogin (owner or admin)
Exit codes0 success · 1 generic/API · 2 usage or confirmation · 3 auth, or the stored key could not be deleted · 5 not found · 6 browser approval required, pending, denied or expired
JSON schemasolwyn.projects-delete.v1

Deletion has two gates:

--yes is required. Without it the command exits 2 with confirmation_required before resolving a credential or touching the network.

On a terminal, type the project name. The CLI fetches the project and prompts, hidden, Type the project name '<name>' to confirm. A mismatch exits 2 with confirmation_failed and nothing is deleted. In a non-interactive shell, --yes alone suffices.

Terminal
$ solwyn projects delete proj_89abcdef0123456789abcdef --yes
Type the project name 'staging-bot' to confirm:
Field                                      Value
Project            proj_89abcdef0123456789abcdef
Archived                                    true
Removed stored key                           yes

The project becomes unavailable immediately; every SDK or CLI call that names it starts failing with project_not_found. The CLI also deletes this computer's stored key for the project. If that local cleanup fails, the deletion has still happened: the command exits 3 with credential_storage_failed.

  • keys: create, rotate or revoke API keys after creation
  • budget — set limits and enforcement for a project
  • Projects — the same lifecycle from the dashboard
  • SDK quickstart: use an API key from the Python SDK

On this page