Follow Discord
Sweep 22 Oct 2026 · 04:32Z Build v2.1.308 527 read Stable v2.1.308 Latest v2.1.308 Next v2.1.308 Feeds RSS JSON llms.txt llms-full.txt Unofficial
Home / Reference / CLI flags

--max-budget-usd

cli never mined documented JSON

A Claude Code CLI flag, read out of the shipped bundle. No mined inventory carries it: everything below comes from what this site has written about it.

Maximum dollar amount to spend on API calls before stopping (print mode only). Spend from subagents counts toward the cap. When you return to a conversation with --continue or --resume, totals restored from earlier runs don't count toward it. Once spend reaches the cap, spawning another subagent fails with Budget limit reached, and Claude Code stops background subagents that are still running; the cap-enforcement behaviors require Claude Code v2.1.217 or later

Anthropic's own wording. Read off CLI reference, captured 2026-09-26.

First seen — never in a mined build
Last seen — never in a mined build
Builds0 / 149on this box, as of v2.1.308
Written about v2.1.242 first named in a changelog, 24 Aug 2026

In the changelogs

6

Releases whose published page names --max-budget-usd.

  1. v2.1.299
    Headless runs now say why they stopped, including when input ends

    Headless runs now end with a stated reason: the turn limit, the spending limit, or the host closing its input

    found in this entry's text

  2. v2.1.295
    Non-interactive runs set up a new tracker for turn and spending limits

    When Claude Code runs without its interactive screen, it now builds a new tracker from the maximum-turns and maximum-budget limits

    found in this entry's text

  3. v2.1.277
    print --max-budget-usd halt message rewording

    Internal log wording for the --max-budget-usd halt now says 'this run's spend' instead of 'total cost'

    found in this entry's text

  4. v2.1.277
    CLI budget/task-budget argument errors now thrown as a different error class

    Errors for invalid --max-budget-usd or --task-budget values now use a different internal error class, same message

    found in this entry's text

  5. v2.1.246
    Headless runs halt at the spend cap and stop background agents

    Headless runs now stop at your spend cap and shut down background agents instead of spending on.

    named in this entry, found in this entry's text

  6. v2.1.242
    New modelPricing managed setting bills usage at contracted rates

    Organizations can bill your reported spend at contracted rates everywhere costs appear.

    found in this entry's text

First cited

1

The earliest release whose published evidence quoted --max-budget-usd was v2.1.277, 18 Sep 2026. That is the oldest release this project wrote about it, so it is a floor on the name's age and not the release that introduced it. It is not a presence reading: which builds carried the name is the table below.

ReleaseDateThe span that was quoted
v2.1.27718 Sep 2026--max-budget-usd must be a positive number greater than 0

Presence across releases

0

The miner has never read a build containing this name. It is here because a changelog entry of ours names it, which is evidence that it existed and not evidence of which releases carried it. The inventory starts at v2.1.138 and everything older than that was never mined.

Read out of the published npm bundle release by release, and out of Anthropic's own documentation as this site captured it. Nothing on this page is a description anybody here wrote about what the CLI flag does. All CLI flags.

Feedback