> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Budget Handling

> Stop praisonai CLI runs cleanly when an agent hits its budget cap

When a `praisonai` CLI run goes over its budget, you get a clean error message and exit-code `1` — no Python traceback.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "CLI Budget Guard"
        CLI[🖥️ CLI] --> Agent[🤖 Agent]
        Agent --> LLM[💰 LLM Call]
        LLM --> Check{💸 Over Budget?}
        Check -->|No| Continue[✅ Continue]
        Check -->|Yes| Handler[🛡️ CLI Handler]
        Handler --> Message[📝 Clean Message]
        Handler --> Exit[🚪 Exit 1]
    end
    
    classDef cli fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef agent fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff
    classDef error fill:#8B0000,stroke:#7C90A0,color:#fff
    
    class CLI cli
    class Agent,LLM agent
    class Check check
    class Continue success
    class Handler,Message,Exit error
```

## Quick Start

<Steps>
  <Step title="Set a Budget in Your Agent">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, ExecutionConfig

    agent = Agent(
        name="Researcher",
        instructions="Research the topic the user asks about",
        execution=ExecutionConfig(max_budget=1.00)  # USD cap
    )

    agent.start()  # or run via the praisonai CLI
    ```
  </Step>

  <Step title="Run via CLI">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai "Research the history of AI"
    ```

    If the run goes over `$1.00`, the CLI prints (in red):

    ```
    Budget limit exceeded: Agent 'Researcher' exceeded budget: $1.0042 >= $1.0000.
    Hint: set budget via execution=ExecutionConfig(max_budget=1.00) on your Agent.
    ```

    …and exits with code `1`.
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI
    participant Agent
    participant LLM
    
    User->>CLI: praisonai "task"
    CLI->>Agent: agent.start(prompt)
    Agent->>LLM: API call
    LLM-->>Agent: Response + cost
    Agent-->>Agent: Check budget
    
    alt Budget OK
        Agent-->>CLI: Success
        CLI-->>User: Results
    else Budget Exceeded
        Agent->>Agent: Raise BudgetExceededError
        CLI->>CLI: Catch exception
        CLI->>CLI: Print clean message
        CLI->>User: Exit code 1
    end
```

The `praisonai` CLI wraps every `agent.start(...)` / `agent.chat(...)` call in a budget handler. When the agent raises `BudgetExceededError`, the CLI:

1. Prints a single-line, red, rich-formatted message including the actionable hint.
2. Exits with code `1` so shell scripts and CI can detect the failure.

This works across **every** CLI display mode: `silent` (`-qq`), `quiet` (`-q`), `verbose` (`-v`), `debug` (`-vv`), `--output jsonl`, `--output json`, `--output flow`, `--output editor`, and default.

***

## Using the Exit Code in CI / Scripts

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
if ! praisonai "Research AI trends"; then
    echo "Run failed (likely over budget)"
    exit 1
fi
```

Exit code reference:

| Exit code | Meaning                                              |
| --------- | ---------------------------------------------------- |
| `0`       | Success                                              |
| `1`       | `BudgetExceededError` (or other handled fatal error) |

***

## Why isn't there a `max_budget=` shortcut on Agent?

By design. Per AGENTS.md §5.3 (Parameter Consolidation), execution-related knobs live on `ExecutionConfig`, not as new top-level `Agent.__init__` parameters. This keeps the `Agent` constructor small and discoverable. The CLI's error message points users to the **one** correct place to set a budget:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
Agent(execution=ExecutionConfig(max_budget=1.00))
```

***

## Catching the error in your own code

If you embed `praisonaiagents` directly (not via the CLI), you can catch the same exception:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, ExecutionConfig
from praisonaiagents.errors import BudgetExceededError

agent = Agent(
    name="Writer",
    instructions="Write articles",
    execution=ExecutionConfig(max_budget=0.50)
)

try:
    agent.start("Write about climate change")
except BudgetExceededError as e:
    print(f"{e.agent_name} spent ${e.total_cost:.4f} (cap: ${e.max_budget:.4f})")
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Set a budget cap early">
    Without `max_budget`, a runaway agent can rack up costs unbounded. Pick a cap based on a few un-budgeted dev runs.
  </Accordion>

  <Accordion title="Use the exit code in automation">
    The graceful exit means CI detects the failure cleanly — no need to grep tracebacks.
  </Accordion>

  <Accordion title="Don't look for a top-level max_budget= on Agent">
    There isn't one. Use `execution=ExecutionConfig(max_budget=...)` — that's the only supported pattern.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Budget Management" icon="wallet" href="/concepts/budget">
    Full SDK API for budgets, cost tracking, and `on_budget_exceeded` actions
  </Card>

  <Card title="Execution Configuration" icon="gear" href="/configuration/agent-config">
    All execution settings including retries, timeouts, and rate limits
  </Card>
</CardGroup>