projects
Create, list, inspect, rename, and archive Solwyn projects from the CLI
projects has five subcommands. list requires JWT; create, rename and delete require owner/admin JWT with project.write. show accepts either credential with project access. Run a JWT-only subcommand under a project key and it exits 3 before any request, with a hint that depends on where the key came from.
projects create
Create a project and capture its first API key exactly once.
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 | required | Name for the new project. |
--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 in the OS keychain instead of printing it. |
| Contract | |
|---|---|
| Auth | owner/admin JWT (project.write) |
| Exit codes | 0 success · 1 generic/API · 2 usage · 3 auth |
| JSON schema | solwyn.projects-create.v1 |
The new project 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 write it straight to your OS keychain, in which case it is stored rather than printed. If the keychain write fails, the command exits 3 and never falls back to displaying the key.
$ solwyn projects create --name my-agent --budget 50 --period monthly
Field Value
ID proj_x1y2z3w4
Name my-agent
Budget limit 50.00
Budget period monthly
Budget mode alert_only
Created 2026-07-11T10:30:00Z
Key prefix sk_proj_a1b2c3d4e5f67890
Scope full
╭─ One-time project key ─╮
│ sk_proj_a1b2c3d4e5f67890… │
╰─────────────────────────╯The panel prints the full key — sk_proj_ followed by 64 hexadecimal characters — shown here truncated. In JSON output it is the key field. Use it as:
SOLWYN_API_KEYfor the CLI (or store it withsolwyn login --with-key)SOLWYN_API_KEY, or theapi_keyconstructor argument, for the Python SDK
With --store-key, no panel is printed; the table shows Stored true instead, and the JSON payload carries "stored": true in place of key. 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.
Creation requires Core's project.write permission (owner/admin). A member is refused with exit 3. 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 | JWT |
| Exit codes | 0 success · 1 generic/API · 2 usage · 3 auth |
| JSON schema | solwyn.projects-list.v1 |
projects show
Show the project selected by the global project context.
$ 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:00ZResolve the project with --project, SOLWYN_PROJECT_ID, or a default_project in your config file. Under a project key, a response for any other project is rejected.
| Contract | |
|---|---|
| Auth | any (project key or JWT) |
| 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 | JWT (owner or admin) |
| Exit codes | 0 success · 1 generic/API · 2 usage · 3 auth · 5 not found |
| JSON schema | solwyn.projects-rename.v1 |
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 and revoke every one of its keys in the same transaction. 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 | JWT (owner or admin) |
| Exit codes | 0 success · 1 generic/API, or local config cleanup failed · 2 usage or confirmation · 3 auth · 5 not found |
| 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
API keys revoked trueThe project becomes unavailable immediately; every SDK or CLI call using one of its keys starts failing with exit 3. Afterwards the CLI clears default_project from your config file if it named the deleted project. If that local cleanup fails, the deletion has still happened: the command exits 1 with project_deleted_config_update_failed and a hint to repair the file or point default_project at a live project.
Related
keys— rotate or revoke a project key after creationbudget— set limits and enforcement for a project- Projects — the same lifecycle from the dashboard
- SDK quickstart — use a project key from the Python SDK