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.
solwyn projects create [--name <name>] [--budget FLOAT] [--period daily|weekly|monthly] [--mode alert_only|hard_deny] [--scope full|read_only] [--store-key]| Option | Type | Default | Purpose |
|---|---|---|---|
--name | string, ≤ 100 chars | the repository's name | Name for the new project: letters, digits, spaces, ., _ and -. Inside a git repository it defaults to the repository's folder name; elsewhere it is required. |
--budget | float > 0 | 100.0 | Initial budget in USD. |
--period | daily | weekly | monthly | monthly | Initial budget period. |
--mode | alert_only | hard_deny | alert_only | Initial enforcement mode. |
--scope | full | read_only | API default | Scope of the project's first key. Omitted from the request when not passed. |
--store-key | boolean | false | Store the new key on this computer for the project instead of printing it, and write .solwyn.env if the repository has none. |
| Contract | |
|---|---|
| Auth | owner/admin login (project.write) |
| Exit codes | 0 success · 1 generic/API · 2 usage · 3 auth · 6 browser approval required, pending, denied or expired |
| JSON schema | solwyn.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.
$ 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 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.
$ 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 | |
|---|---|
| Auth | login |
| Exit codes | 0 success · 1 generic/API · 2 usage · 3 auth |
| JSON schema | solwyn.projects-list.v1 |
projects show
Show a project, by name or proj_ id.
$ 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:00ZThe 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 | |
|---|---|
| Auth | any (API key or login) |
| Exit codes | 0 success · 1 generic/API · 2 usage · 3 auth · 5 not found |
| JSON schema | solwyn.projects-show.v1 |
projects rename
Rename a project. Owner or admin.
$ 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| Option | Type | Default | Purpose |
|---|---|---|---|
PROJECT_ID | argument | required | The project to rename. Positional — this command does not use the global --project. |
--name | string, ≤ 100 chars | required | The new name. |
| Contract | |
|---|---|
| Auth | login (owner or admin) |
| Exit codes | 0 success · 1 generic/API · 2 usage · 3 auth · 5 not found · 6 browser approval required, pending, denied or expired |
| JSON schema | solwyn.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.
solwyn projects delete <project_id> --yes| Option | Type | Default | Purpose |
|---|---|---|---|
PROJECT_ID | argument | required | The project to archive. Positional. |
--yes | boolean | false | Acknowledge that the deletion is irreversible. Mandatory. |
| Contract | |
|---|---|
| Auth | login (owner or admin) |
| Exit codes | 0 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 schema | solwyn.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.
$ solwyn projects delete proj_89abcdef0123456789abcdef --yes
Type the project name 'staging-bot' to confirm:
Field Value
Project proj_89abcdef0123456789abcdef
Archived true
Removed stored key yesThe 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.
Related
keys: create, rotate or revoke API keys after creationbudget— set limits and enforcement for a project- Projects — the same lifecycle from the dashboard
- SDK quickstart: use an API key from the Python SDK