Verified Claude Code
Cap script spend with --max-budget-usd, but leave headroom
What it does
--max-budget-usd only works with -p. In our test a 0.05 USD cap was exceeded on the very first turn (cold prompt cache, ~0.105 USD) and the run ended as an error with no result. Leave headroom for the first-turn cache cost.
How
claude -p "..." --output-format json --max-budget-usd 0.5
is_error: true in the result means the cap was hit.
How much to trust this
| Applies to | ≥ 2.0.28 |
|---|---|
| Verified | Oct 17, 2026 · v2.1.296 · tested locally 本机实测：0.05 美元上限在第一轮被突破（花费约 0.105，is_error=true） |
| Depends on | --max-budget-usd-p |
| Source | https://code.claude.com/docs/en/cli-reference (official_docs) |