> ## 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.

# Tool Approval

> Control tool execution approval in PraisonAI CLI

The PraisonAI CLI includes a safety system that requires human approval before executing potentially dangerous tools. This page explains how to control this behavior.

## Overview

Certain tools are marked with risk levels and require approval before execution:

| Risk Level   | Tools                                                 | Default Behavior |
| ------------ | ----------------------------------------------------- | ---------------- |
| **CRITICAL** | `execute_command`, `kill_process`, `execute_code`     | Always prompts   |
| **HIGH**     | `write_file`, `delete_file`, `move_file`, `copy_file` | Always prompts   |
| **MEDIUM**   | `evaluate`, `crawl`, `scrape_page`                    | Always prompts   |
| **LOW**      | (none by default)                                     | Always prompts   |

## YAML Configuration

Configure approval settings in your YAML configuration file using the `approval:` block:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
approval:
  enabled: true                    # bool, default false
  backend: "console"               # console | slack | telegram | discord | webhook | http | agent | auto | none
  approve_all_tools: false         # bool, default false
  timeout: 60                      # float seconds, default null (no timeout); accepts "none"
  approve_level: "high"            # low | medium | high | critical, default null
  guardrails: "..."                # optional guardrail description
```

### Shorthand Forms

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
approval: true                # → enabled, console backend
approval: false               # → disabled
approval: slack               # → enabled, slack backend
approval: null                # → disabled
```

### Legacy YAML Aliases (Backward Compatible)

| Legacy key         | New key             |
| ------------------ | ------------------- |
| `backend_name`     | `backend`           |
| `all_tools`        | `approve_all_tools` |
| `approval_timeout` | `timeout`           |

Primary keys win when both are present.

### Validation

Unknown keys now raise `ValueError` with the list of allowed keys — silent typos no longer pass through undetected.

### CLI ⇄ YAML ⇄ Python Mapping

All three surfaces use the same unified configuration:

| CLI flag                   | YAML key                  | Python field                          |
| -------------------------- | ------------------------- | ------------------------------------- |
| `--trust`                  | N/A (use `backend: auto`) | `backend="auto"`, `enabled=True`      |
| `--approval <backend>`     | `backend: <backend>`      | `backend="<backend>"`, `enabled=True` |
| `--approve-all-tools`      | `approve_all_tools: true` | `approve_all_tools=True`              |
| `--approval-timeout <sec>` | `timeout: <sec>`          | `timeout=<sec>`                       |
| `--approve-level <level>`  | `approve_level: <level>`  | `approve_level="<level>"`             |
| `--guardrail "<text>"`     | `guardrails: "<text>"`    | `guardrails="<text>"`                 |

***

## Auto-Approve All Tools (`--trust`)

Use the `--trust` flag to auto-approve all tool executions without prompting:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "hello world" --trust
```

<Frame>
  <img src="https://mintcdn.com/praisonai/2OBv0nvWLwS-3tNQ/docs/cli/tool-approval-trust-mode-auto-approves-all-t.gif?s=0532a0993731def96833673783b48d6a" alt="Trust mode auto-approves all tools example" width="1497" height="1104" data-path="docs/cli/tool-approval-trust-mode-auto-approves-all-t.gif" />
</Frame>

### Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Auto-approve all tools (use with caution!)
praisonai "run ls -la command" --trust
```

**Output:**

```
⚠️  Trust mode enabled - all tool executions will be auto-approved
Tools used: execute_command
[directory listing...]
```

<Warning>
  The `--trust` flag bypasses all safety prompts. Only use this when you trust the AI's actions completely, such as in controlled environments or for testing.
</Warning>

## Level-Based Approval (`--approve-level`)

Use `--approve-level` to auto-approve tools up to a specific risk level:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Auto-approve low, medium, and high risk tools
# Still prompt for critical tools
praisonai "write to file and run command" --approve-level high
```

**Available levels:**

* `low` - Only auto-approve low risk tools
* `medium` - Auto-approve low and medium risk tools
* `high` - Auto-approve low, medium, and high risk tools
* `critical` - Auto-approve all tools (same as `--trust`)

### Examples

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Auto-approve only low risk tools
praisonai "task" --approve-level low

# Auto-approve up to medium risk
praisonai "task" --approve-level medium

# Auto-approve up to high risk (prompt for critical)
praisonai "task" --approve-level high

# Auto-approve everything (same as --trust)
praisonai "task" --approve-level critical
```

## Approval Backend (`--approval`)

Use `--approval` to route tool approvals to a specific backend — Slack, Telegram, Discord, a webhook, or more:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Route approvals to Slack
praisonai "deploy to production" --approval slack

# Route approvals to Telegram
praisonai "delete old logs" --approval telegram

# Auto-approve everything (same as --trust)
praisonai "run tests" --approval auto

# Interactive console prompt (default)
praisonai "clean up files" --approval console
```

### Available Backends

| Value      | Backend                                   | Required Env Vars                         |
| ---------- | ----------------------------------------- | ----------------------------------------- |
| `console`  | Interactive terminal prompt (default)     | —                                         |
| `slack`    | Slack Block Kit message + reply polling   | `SLACK_BOT_TOKEN`, `SLACK_CHANNEL`        |
| `telegram` | Telegram inline keyboard + polling        | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`  |
| `discord`  | Discord embed + text reply polling        | `DISCORD_BOT_TOKEN`, `DISCORD_CHANNEL_ID` |
| `webhook`  | POST to HTTP endpoint + poll for decision | `APPROVAL_WEBHOOK_URL`                    |
| `http`     | Local web dashboard (browser-based)       | —                                         |
| `agent`    | Delegate to an AI reviewer agent          | —                                         |
| `auto`     | Auto-approve all (same as `--trust`)      | —                                         |
| `none`     | Disable approval entirely                 | —                                         |

### Works With All CLI Commands

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Direct prompt
praisonai "task" --approval slack

# Run command
praisonai run "task" --approval telegram

# Chat / TUI
praisonai chat --approval discord
```

<Tip>
  For full configuration of each backend (timeouts, polling intervals, custom parameters), see [Approval Protocol](/features/approval-protocol).
</Tip>

***

## Default Behavior (No Flags)

Without any flags, the CLI will prompt for approval on all dangerous tools:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "run a shell command to list files"
```

**Output:**

```
╭─ 🔒 Tool Approval Required ──────────────────────────────────────────────────╮
│ Function: execute_command                                                    │
│ Risk Level: CRITICAL                                                         │
│ Arguments:                                                                   │
│   command: ls -la                                                            │
╰──────────────────────────────────────────────────────────────────────────────╯
Do you want to execute this critical risk tool? [y/n] (n):
```

## Programmatic Control

You can also control approval behavior programmatically:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.approval import (
    set_approval_callback,
    ApprovalDecision,
    remove_approval_requirement,
    add_approval_requirement
)

# Option 1: Auto-approve all tools
def auto_approve(function_name, arguments, risk_level):
    return ApprovalDecision(approved=True, reason="Auto-approved")

set_approval_callback(auto_approve)

# Option 2: Level-based approval
def level_approve(function_name, arguments, risk_level):
    levels = {"low": 1, "medium": 2, "high": 3, "critical": 4}
    if levels.get(risk_level, 4) <= levels["high"]:
        return ApprovalDecision(approved=True)
    return ApprovalDecision(approved=False, reason="Too risky")

set_approval_callback(level_approve)

# Option 3: Remove approval requirement for specific tool
remove_approval_requirement("execute_command")

# Option 4: Add approval requirement for custom tool
add_approval_requirement("my_dangerous_tool", risk_level="high")
```

## Risk Level Reference

### Critical Risk Tools

* `execute_command` - Run shell commands
* `kill_process` - Terminate processes
* `execute_code` - Execute arbitrary code

### High Risk Tools

* `write_file` - Write to files
* `delete_file` - Delete files
* `move_file` - Move/rename files
* `copy_file` - Copy files
* `execute_query` - Database queries

### Medium Risk Tools

* `evaluate` - Evaluate expressions
* `crawl` - Web crawling
* `scrape_page` - Web scraping

## Best Practices

<Tip>
  **For development/testing:** Use `--trust` for faster iteration when you're actively monitoring the AI's actions.
</Tip>

<Tip>
  **For production scripts:** Use `--approve-level high` to allow file operations but still require approval for shell commands.
</Tip>

<Note>
  The approval system is designed to prevent accidental destructive actions. Consider your use case carefully before bypassing it.
</Note>

## Related Features

<CardGroup cols={2}>
  <Card title="Approval Protocol" icon="shield-check" href="/features/approval-protocol">
    All approval backends (Slack, Telegram, Discord, Webhook, HTTP, Agent)
  </Card>

  <Card title="Sandbox Execution" icon="shield-halved" href="/docs/cli/sandbox-execution">
    Secure isolated command execution
  </Card>

  <Card title="Autonomy Modes" icon="robot" href="/docs/cli/autonomy-modes">
    Control AI autonomy levels
  </Card>

  <Card title="Tool Tracking" icon="wrench" href="/docs/cli/tool-tracking">
    Monitor tool usage
  </Card>
</CardGroup>