budget
The convox budget command group manages an app's monthly budget cap, the
atCapAction enforcement, and recovery from a cap fire.
For the operational guide see Budget Caps; for the schema reference see the convox.yml budget block.
budget show
Print the current budget config and runtime state for an app.
Usage
convox budget show <app>
Examples
$ convox budget show myapp
Monthly cap 250.00 USD
Spend 134.65 USD (53.86%)
At-cap action auto-shutdown
Breaker clear
State idle
budget set
Set or update the budget config in convox.yml-equivalent shape. Equivalent
to editing the manifest and redeploying, but applied without a redeploy.
Usage
convox budget set <app> [--monthly-cap N] [--alert-at N]
[--at-cap-action ACTION] [--pricing-adjustment N]
Examples
$ convox budget set myapp --monthly-cap 500 --at-cap-action auto-shutdown
Setting budget for myapp... OK
Prerequisite: cost tracking must be enabled
budget set rejects with HTTP 422 when the rack parameter
cost_tracking_enable is false and you supply any enforcement-bearing
field (--monthly-cap, --alert-at, --at-cap-action). Without the
accumulator running, those fields would persist as unenforced config —
the loud rejection replaces a silent no-op. Set the rack parameter first:
$ convox rack params set cost_tracking_enable=true
# wait ~3 min for apply, then:
$ convox budget set myapp --monthly-cap 500 --at-cap-action auto-shutdown
Updates that touch only --pricing-adjustment are not gated; the pricing
multiplier modifies the displayed model output and does not require the
accumulator. See
Cost tracking prerequisite
for the full rationale and AWS-only-functional scope. Recovery operations
(budget clear, budget reset) remain available regardless of cost-tracking
state.
budget clear
Remove the budget config for an app. The app continues running with no cap,
no threshold, and no auto-shutdown — equivalent to omitting the budget block
from convox.yml.
Usage
convox budget clear <app>
budget reset
Acknowledge a cap breach and re-enable deploys. Clears the breaker AND, when
invoked after :fired, restores replicas from the persisted shutdown-state
annotation. Preserves flap-suppress carry-over by default;
--force-clear-cooldown is additive and forces past the 24-hour
flap-prevention cooldown.
Usage
convox budget reset <app> [--force-clear-cooldown]
Examples
$ convox budget reset myapp
Resetting budget for myapp... OK
Breaker cleared.
$ convox budget reset myapp --force-clear-cooldown
Resetting budget for myapp (force-clearing flap-suppress cooldown)... OK
See Force-clear cooldown for when to use the flag.
budget cap raise
Raise the monthly cap. Atomic with breaker-clear when the new cap is above
current spend. Alias for budget set --monthly-cap.
Usage
convox budget cap raise <app> --monthly-cap-usd N
Examples
$ convox budget cap raise myapp --monthly-cap-usd 500
Raising monthly cap to 500.00 USD... OK
Breaker cleared.
After :fired (post-shutdown), cap-raise clears the breaker but does NOT
restart already-shutdown services. Run convox budget reset myapp to
restore replicas from the persisted shutdown-state annotation. See
Cap raise.
budget simulate-shutdown
Dry-run an auto-shutdown plan without modifying the app. Emits the
:simulated audit event so operators can rehearse the failure path.
Usage
convox budget simulate-shutdown <app>
Examples
$ convox budget simulate-shutdown myapp
Simulating auto-shutdown for myapp...
Plan (largest-cost order):
worker (eligible)
api (eligible)
web (excluded — neverAutoShutdown)
OK
budget dismiss-recovery
Dismiss the sticky recovery banner that displays after an auto-shutdown recovers. Equivalent to clicking "Dismiss" in the Console banner.
Usage
convox budget dismiss-recovery <app>
Examples
$ convox budget dismiss-recovery myapp
Dismissing recovery banner for myapp... OK
The dismiss is per-app, not per-user; once dismissed by any user the banner hides for everyone viewing that app. See Webhook Signing for the audit event semantics.
See Also
- Budget Caps — operational guide
- Cost Tracking — how spend is computed
- convox.yml budget block — schema reference
- cost CLI — cost breakdown
