# --max-budget-usd Flag

> It stops claude -p when the spend hits a dollar cap.

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** claude --max-budget-usd, Spend cap

## Think of it like

It is like you take five dollars to the fair. When it is gone, you go home.

## Definition

--max-budget-usd stops claude -p once the spend reaches a dollar amount you set. The spend is Claude Code's own estimate, so it can differ from your bill. Spend by subagents counts too. A step that is already running can take the total past the cap, so leave some room.

## Example

Jack runs Claude over a hundred repos at night. Each run gets --max-budget-usd 2, so one repo that goes wrong cannot eat the whole night's budget.

## Example code

```bash
claude -p --max-budget-usd 5 "Write tests for utils.py"
```

Stop once the estimate reaches five dollars.

## Why it matters

Unattended runs can cost more than you expect. A cap puts a limit on each one.

## Common mistake

Treating it as a hard wall. The last step can pass the cap, and the estimate is not your bill.

## Three principles

- **Dollars, estimated.** Not the bill.
- **Subagents count.** Toward the cap.
- **Leave room.** It can pass it.

## Related terms

- [--max-turns Flag](https://learn.benibix.com/term/ai/max-turns-flag)
- [Non-Interactive Mode](https://learn.benibix.com/term/ai/non-interactive-mode)
- [Subagent](https://learn.benibix.com/term/ai/subagent)

## Told apart from

- [--max-turns vs --max-budget-usd](https://learn.benibix.com/compare/max-turns-flag-vs-max-budget-usd-flag): People think --max-turns and --max-budget-usd are two ways to set the same limit. They count different things. --max-turns counts rounds: each time Claude acts and reads the result is one turn. --max-budget-usd counts dollars, using Claude Code's own estimate. A run with few turns can still cost a lot if each turn reads big files. A cheap run can still take many turns. Set both on unattended runs.

## Taught in

- [Print Mode Output Flags](https://learn.benibix.com/learn/ai-claude-code-commands/print-mode-output-flags): Claude Code Commands, 14/17

![Three limits on a print mode run: turns, dollars, and permission prompts nobody can answer.](https://learn.benibix.com/diagrams/flag-limits.svg)

---

Source: https://learn.benibix.com/term/ai/max-budget-usd-flag
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-16
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
