budget

Poll budget state, run pre-flight guardrail checks, settle reservations, and configure limits

budget has four subcommands, each for a distinct job:

budget status — poll budget state without authorizing spend. Safe to run on a loop.
budget check — reserve budget immediately before one un-instrumented provider call the SDK will not see.
budget confirm — settle a reservation after that call, reporting the tokens it actually used.
budget set — change the limit, period, or enforcement mode.

Poll with status, check immediately before un-instrumented spend, and confirm only a non-null reservation. Calls you make through the Solwyn SDK are already metered — check and confirm are for spend the SDK does not wrap, such as a raw provider call in a script or a CI gate.

budget status

Read the current budget without reserving or authorizing anything.

Terminal

solwyn --project <project_id> budget status [--max-utilization FLOAT]

Option	Type	Default	Purpose
`--max-utilization`	float `0.0`–`100.0`	none	CI deploy gate: exit `4` when utilization is at or above this percentage.

Contract
Auth	any (project key or JWT)
Exit codes	`0` success · `1` generic/API · `2` usage · `3` auth · `4` utilization gate · `5` not found
JSON schema	`solwyn.budget-status.v1`

--max-utilization turns status into a deploy gate: the command still prints the budget, then exits 4 when utilization is at or above the threshold, so a pipeline step can block a rollout that would run over budget.

Terminal

$ solwyn --project proj_abc12345 budget status --max-utilization 90
Field             Value
Project           proj_abc12345
Budget limit      100.00
Current usage     23.47
Remaining budget  76.53
Budget period     monthly
Budget mode       alert_only
Utilization       23.47%
$ echo $?
0

budget check

Reserve budget for one caller-made, un-instrumented provider call. Run it immediately before the call — do not poll with it.

Terminal

solwyn --project <project_id> budget check \
  --estimated-input-tokens <int> --model <name> --provider <provider> \
  [--fallback-provider <provider> --fallback-model <name>]...

Option	Type	Default	Purpose
`--estimated-input-tokens`	integer ≥ 0	required	Estimated input tokens for the pending call.
`--model`	string	required	Primary provider model name.
`--provider`	provider enum	required	Primary provider (`openai`, `anthropic`, `google`, `bedrock`, and the OpenAI-compatible identifiers).
`--fallback-provider`	provider enum	none	A fallback provider, in attempt order; repeat, paired with a fallback model.
`--fallback-model`	string	none	Fallback model aligned with each fallback provider.

Each --fallback-provider must be paired with one --fallback-model in the same order; the counts must match, up to a maximum of eight pairs.

Contract
Auth	project key (a JWT is rejected)
Exit codes	`0` allowed or fail-open · `1` generic/API · `2` usage · `3` auth · `4` budget denial
JSON schema	`solwyn.budget-check.v1`

Read the result before you spend:

allowed: true, reservation_id set — reserved. Make the call, then settle it with budget confirm.
allowed: true, reservation_id: null — fail-open. The check could not reserve (Cloud API unreachable, or a model the API declines to price), so the call is allowed unreserved. The CLI prints fail-open, unreserved — skip confirm to stderr. Make the call and skip confirm.
allowed: false — denied, exit 4. Only a hard_deny budget denies a check. Do not make the call.

Terminal

$ solwyn --project proj_abc12345 budget check \
    --estimated-input-tokens 1500 --model gpt-4o --provider openai
Field             Value
Allowed           yes
Reservation ID    rsv_7f3a9c2e
Project           proj_abc12345
Budget mode       hard_deny
Budget limit      100.00
Current usage     23.47
Remaining budget  76.53
Denied by period  -
Price hints       openai=2.5e-06

budget confirm

Settle one reservation after the call, reporting the tokens it actually consumed. Confirm exactly once, and only when check returned a non-null reservation.

Terminal

solwyn --project <project_id> budget confirm \
  --reservation-id <id> --call-id <id> --model <name> --provider <provider> \
  [token counters...]

Option	Type	Default	Purpose
`--reservation-id`	string	required	Reservation returned by the immediately preceding `check`.
`--call-id`	string	required	Unique identifier for the provider call.
`--model`	string	required	Model that actually served the call.
`--provider`	provider enum	required	Provider that actually served the call.
`--is-provider-fallback`	boolean	`false`	Mark that a fallback provider served the call.
`--provider-region`	string	none	Serving cloud region, when relevant.
`--service-tier`	service-tier enum	none	Provider service tier used (`auto`, `default`, `flex`, `scale`, `priority`, `standard`, `optimized`).
`--is-estimated`	boolean	`false`	Mark the token breakdown as estimated rather than provider-reported.

Eleven token counters carry the usage breakdown. Each is an integer from 0 to 100,000,000, defaulting to 0 — supply only the ones the response reported:

Counter	Counts
`--input-tokens`	Input (prompt) tokens
`--output-tokens`	Output (completion) tokens
`--cached-input-tokens`	Input tokens served from cache
`--cache-creation-5m-tokens`	Cache-creation tokens, 5-minute TTL
`--cache-creation-1h-tokens`	Cache-creation tokens, 1-hour TTL
`--reasoning-tokens`	Reasoning tokens
`--audio-input-tokens`	Audio input tokens
`--audio-output-tokens`	Audio output tokens
`--accepted-prediction-tokens`	Accepted predicted-output tokens
`--rejected-prediction-tokens`	Rejected predicted-output tokens
`--tool-use-input-tokens`	Tool-use input tokens

Contract
Auth	project key (a JWT is rejected)
Exit codes	`0` success · `1` generic/API · `2` usage · `3` auth · `5` reservation not found
JSON schema	`solwyn.budget-confirm.v1`

A successful settle returns no body from the Cloud API; the CLI synthesizes the confirmation from your reservation and call ids. A reservation that has expired or already been consumed exits 5.

Terminal

$ solwyn --project proj_abc12345 budget confirm \
    --reservation-id rsv_7f3a9c2e --call-id 4b1e8a20-1c9d-4f0a-9b7e-2f6c1a3d5e80 \
    --model gpt-4o --provider openai --input-tokens 1487 --output-tokens 352
Field           Value
Reservation ID  rsv_7f3a9c2e
Call ID         4b1e8a20-1c9d-4f0a-9b7e-2f6c1a3d5e80

budget set

Change selected budget settings; every other setting is preserved.

Terminal

solwyn --project <project_id> budget set [--limit FLOAT] [--period daily|weekly|monthly] [--mode alert_only|hard_deny]

Option	Type	Default	Purpose
`--limit`	float > 0	none	Budget limit in USD.
`--period`	`daily` \| `weekly` \| `monthly`	none	Budget period.
`--mode`	`alert_only` \| `hard_deny`	none	Enforcement mode.

At least one of --limit, --period, or --mode is required. Running set with none exits 2.

Contract
Auth	JWT (a project key is rejected)
Exit codes	`0` success · `1` generic/API · `2` usage · `3` auth · `5` not found
JSON schema	`solwyn.budget-set.v1`

Terminal

$ solwyn --project proj_abc12345 budget set --limit 200 --mode hard_deny
Field             Value
Project           proj_abc12345
Budget limit      200.00
Current usage     23.47
Remaining budget  176.53
Budget period     monthly
Budget mode       hard_deny
Sub-period        -
Sub-limit         -
Threshold rules   0
Utilization       11.74%

Exit code 4 — two triggers

Both check and status can exit 4, for different reasons:

budget check exits 4 on a denial — a hard_deny budget refused the reservation.
budget status exits 4 on the --max-utilization gate — utilization reached the threshold you set.

A check denial means "do not spend"; a status gate means "utilization is high." Handle them per command, not by the code alone.

Budget enforcement — how the SDK checks and settles budgets automatically
status — budget plus provider health in one view
Scripting — JSON envelopes and the full exit-code contract

budget status

budget check

budget confirm

budget set

Exit code 4 — two triggers

Related

On this page