approvals
Approve in the browser the changes a CLI login can't make on its own, and inspect an approval
A Solwyn login with the default read and contain scopes can read, stop agent runs and lower the primary budget cap on its own. Every other change needs a one-time approval in the browser, bound to that exact request. An agent can ask for one; only you, signed in to the dashboard, can approve it. A read-only login needs an approval for stopping runs and lowering caps too. Your account role still applies.
$ solwyn budget set --limit 1000000 --mode alert_only
This change needs your approval in the browser:
https://app.solwyn.ai/approve/0b7d2c4e-...
Change the budget for project checkout
Budget limit: 1000.00 -> 1000000.00 (raises the cap)
Enforcement: hard_deny -> alert_only (weakens enforcement)
Waiting for approval... (expires in 10 minutes, Ctrl-C to stop)
Approved. Applying the change.The command then prints its normal output. While it waits, the CLI checks the approval every 3 seconds. The global --approval-wait SECONDS option sets how long; the default is 600 seconds when stdin and stderr are terminals, else 90 seconds. --approval-wait 0 asks for the approval and returns at once. Once approved, the CLI re-sends the identical request once (the same method, URL bytes and body bytes) with the approval attached. It never re-sends without the approval and never retries a second time.
Exit 6
Every outcome other than success exits 6, and nothing else is sent:
| Error code | Meaning |
|---|---|
approval_pending | The wait ended first. The error prints the exact command to run after approving (also in detail.retry_command and detail.retry_argv). |
approval_denied | You denied the change in the browser. |
approval_expired | The approval expired. Run the command again to request a new one. |
approval_invalid | The attached approval was not usable. mismatch means the request changed since it was approved, for example because the state a command reads changed. Run the command again. |
approval_limit_reached | Five approvals are already pending for this login. |
A failure after the approved request was sent keeps its normal exit code; for example, rate_limited exits 1. The CLI never re-sends a request that carries an approval, so you see the real error, with the hint "This approval may have been used; if a retry reports it consumed, request a new one." Whether it was used depends on where the request failed; see When an approval is spent.
The retry command
When the wait ends first, the error names the exact command to re-run, for example:
$ solwyn --approval-wait 0 plan upgrade --tier team --interval year --yes
...
Hint: After approving, run: solwyn --approval 0b7d2c4e-0000-4000-8000-000000000003 plan upgrade --tier team --interval year --yes --client-request-id 6f1c2a90-0000-4000-8000-000000000001detail.retry_command is POSIX shell syntax (quoted with shlex.join) for bash, zsh and similar shells. On Windows, and from any automation, run detail.retry_argv directly: it is the same command as an argument list, with solwyn first, so nothing needs shell quoting.
That command repeats only what you typed, plus every value the CLI generated for the request, pinned as an explicit flag: plan upgrade's --client-request-id, and an absolute --until time for a relative snooze such as --until +2h. Re-running it rebuilds the same request bytes, so the approval matches. The approval hand-off stores nothing: no request body, secret or prepared request is written anywhere. If you change any argument, the request differs, the server answers approval_invalid with reason mismatch, and you run the command again to request a new approval.
Secrets never appear in the command. When the original run read one (--secret-stdin, --config-stdin or SOLWYN_CHANNEL_SECRET), the hint says to supply it the same way again; init asks you to enter the same project name and budget again. Positional arguments follow --, so a value such as --help or -x stays a value.
If init --run-cap creates the project and then waits on the approval for the run cap, re-running init cannot finish the job. The retry command is the remaining step instead, for the created project:
solwyn --approval 0b7d2c4e-0000-4000-8000-000000000003 --project proj_0123456789abcdef01234567 budget rule add --type runaway_run --spend 5.0 --mode hard_denyWhen an approval is spent
Approvals are single use and expire 5 minutes after you approve them. A failed approved request doesn't always spend one:
- Rate limits. The route's rate limit runs before an approval is asked for or used, so a
429spends nothing. projects createandkeys rotate. The approval is spent only when the change commits. A plan refusal (402), a rate limit or another refusal before the change leaves it approved until it expires, so the same command with--approval IDcan still use it.- Every other change. The approval is spent before the change runs, so a later validation error (
422) or plan refusal (402) uses it up. Run the command again to request a new one. - Unclear outcomes, such as a
503or a lost connection: the approval may have been used. Run the retry command once more. If the server answersapproval_invalidwith reasonconsumed, request a new approval.
The global --approval ID option attaches an approval to the first change request of that invocation. Read-only requests such as plan change's estimate are skipped, so the approval reaches the change itself.
MCP tools never wait. A tool that needs an approval returns an error with the code approval_required and the approval URL, for a human to open. See mcp.
approvals status
Show one of your approvals and, with --wait, poll until a decision.
solwyn approvals status <approval_id> [--wait SECONDS]| Option | Type | Default | Purpose |
|---|---|---|---|
APPROVAL_ID | argument | required | The approval ID. |
--wait | integer ≥ 0 | 0 | Seconds to wait for a decision. 0 shows it now. |
$ solwyn approvals status 0b7d2c4e-0000-4000-8000-000000000003
Field Value
ID 0b7d2c4e-0000-4000-8000-000000000003
Status pending
Title Change the budget for project checkout
Action budget.update
Reasons raises_cap
Budget limit 1000.00 -> 1000000.00
Expires 2026-10-30T14:30:00+00:00{"schema":"solwyn.approval.v1","id":"0b7d2c4e-0000-4000-8000-000000000003","status":"pending","action":"budget.update","title":"Change the budget for project checkout","reasons":["raises_cap"],"changes":[{"field":"limit_usd","label":"Budget limit","before":"1000.00","after":"1000000.00","effect":"raises_cap"}],"created_at":"2026-10-30T14:20:00Z","expires_at":"2026-10-30T14:30:00Z"}--wait polls every 3 seconds until a decision or the wait ends. Denied and expired approvals exit 6 with approval_denied or approval_expired; an approval still pending after --wait exits 6 with approval_pending. You can read only your own approvals.
solwyn approvals status 0b7d2c4e-0000-4000-8000-000000000003 --wait 120
solwyn --approval 0b7d2c4e-0000-4000-8000-000000000003 budget set --limit 2000| Contract | |
|---|---|
| Auth | login (only your own approvals) |
| Exit codes | 0 shown · 1 generic/API · 2 usage · 3 auth · 5 not found · 6 denied, expired, or still pending after --wait |
| JSON schema | solwyn.approval.v1 |
Related
- Scoped login: what a CLI login can do on its own, and how long it lasts
credentials: list and revoke your CLI logins- Scripting: the exit-code contract, including exit
6