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

# Permissions

> Manage interactive tool-approval rules from the CLI with praisonai permissions

Manage interactive tool-approval rules from the CLI — `praisonai permissions` lists, adds, removes, and shares your project's approval rules.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[Agent] --> B[Tool Call]
    B --> C{Permission Check}
    C -->|Rule match| D[Allow / Deny]
    C -->|No rule| E[Prompt User]
    E --> F[Allow / Deny / Persist]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class A agent
    class B tool
    class C,E check
    class D,F result
```

## Quick Start

<Steps>
  <Step title="Run with interactive approval">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai --approval console run "Check git status"
    ```

    When a sensitive tool runs, you see the approval prompt.
  </Step>

  <Step title="Persist with Always allow">
    Press `A` at the prompt to write a rule to `.praisonai/permissions/rules.json`.
  </Step>

  <Step title="Re-run without prompting">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai --approval console run "Check git status again"
    ```

    Matching rules are applied automatically.
  </Step>
</Steps>

## Approval prompt

```
⚠ Tool Approval Required
Tool: bash(command='git status')
Risk: medium
Agent: researcher

Options:
  [a] Allow once
  [A] Always allow (persist rule)
  [d] Deny
  [D] Always deny (persist rule)

Your choice:
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant U as User
    participant CLI as CLI
    participant PM as PermissionManager
    participant D as Disk

    CLI->>PM: check(target, agent)
    alt Rule matches
        PM-->>CLI: ALLOW / DENY
    else No rule
        CLI->>U: Show prompt
        U-->>CLI: a / A / d / D
        opt A or D
            CLI->>PM: add_rule(pattern)
            PM->>D: rules.json
        end
    end
```

## CLI approval modes

| Flag                      | Mode           | Behaviour                              |
| ------------------------- | -------------- | -------------------------------------- |
| `--approval console`      | `DEFAULT`      | Prompt for sensitive tools             |
| `--approval plan`         | `PLAN`         | Block write, edit, delete, bash, shell |
| `--approval accept-edits` | `ACCEPT_EDITS` | Auto-approve edit/write tools          |
| `--approval bypass`       | `BYPASS`       | Skip all checks (dangerous)            |

<Tip>
  The CLI flag `bypass` maps to `PermissionMode.BYPASS`, whose value is `bypass_permissions`.
</Tip>

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai --approval plan run "Explore the codebase"
praisonai --approval accept-edits run "Refactor utils.py"
```

## Non-interactive mode

| Option                        | Type | Default | Description                             |
| ----------------------------- | ---- | ------- | --------------------------------------- |
| `--yes` / `-y`                | flag | off     | Skip prompts; approval defaults to deny |
| `PRAISONAI_NON_INTERACTIVE=1` | env  | unset   | Same as `--yes` for CI and scripts      |

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai --yes --approval console run "Deploy check"
PRAISONAI_NON_INTERACTIVE=1 praisonai --approval console run "Deploy check"
```

## Subcommands

### `list`

List all permission rules in the current project.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai permissions list
```

### `allow`

Add an ALLOW rule.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai permissions allow "bash:git *" --description "Allow git"
```

| Option          | Type   | Default    | Description                     |
| --------------- | ------ | ---------- | ------------------------------- |
| `--agent`       | string | all agents | Scope rule to one agent         |
| `--description` | string | auto       | Human-readable label            |
| `--priority`    | int    | `100`      | Higher values are checked first |

### `deny`

Add a DENY rule.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai permissions deny "bash:rm *" --priority 200
```

| Option          | Type   | Default    | Description                     |
| --------------- | ------ | ---------- | ------------------------------- |
| `--agent`       | string | all agents | Scope rule to one agent         |
| `--description` | string | auto       | Human-readable label            |
| `--priority`    | int    | `100`      | Higher values are checked first |

### `ask`

Add an ASK rule (always prompt).

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai permissions ask "bash:*" --agent researcher
```

| Option          | Type   | Default    | Description                     |
| --------------- | ------ | ---------- | ------------------------------- |
| `--agent`       | string | all agents | Scope rule to one agent         |
| `--description` | string | auto       | Human-readable label            |
| `--priority`    | int    | `50`       | Higher values are checked first |

### `remove`

Remove a rule by ID prefix (from `list` output).

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai permissions remove a1b2c3d4
```

### `reset`

Delete all rules and approvals (requires confirmation).

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai permissions reset
```

### `export`

Print rules as JSON to stdout.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai permissions export > rules.json
```

### `import`

Import rules from a JSON file.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai permissions import rules.json
```

## Rule patterns

Patterns use `tool_name:argument_pattern` glob syntax:

| Pattern                | Matches                                                          |
| ---------------------- | ---------------------------------------------------------------- |
| `bash:git *`           | All git bash commands                                            |
| `bash:ls *`            | ls commands                                                      |
| `read:*`               | All read tool calls                                              |
| `write:*.env`          | Writes to `.env` files                                           |
| `write:/etc/*`         | Truncating redirections to `/etc/` (e.g. `cat foo > /etc/hosts`) |
| `external_dir:/data/*` | Access to `/data/` when `workspace_root` is set                  |
| `external_dir:*`       | All out-of-workspace access (use with deny to hard-block)        |

### external\_dir: patterns

When `workspace_root` is set on `PermissionManager`, any path that resolves outside the root emits an `external_dir:<parent>/*` sub-target defaulting to **ask**. Use the CLI to pre-authorise or hard-block these:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Allow a specific external data directory
praisonai permissions allow "external_dir:/data/*" --description "Shared data volume"

# Hard-block all out-of-workspace access (no prompt, immediate deny)
praisonai permissions deny "external_dir:*" --description "Lock down external filesystem"
```

See [Workspace Boundary](/docs/features/workspace-boundary) for full details on what triggers the gate and how to configure it.

<Note>
  Compound shell commands (`&&`, `;`, `|`, subshells, `$(...)`) are decomposed and each operation is checked against your rules. A `deny` on `bash:rm *` blocks `cd /tmp && rm -rf x` and `echo $(rm -rf x)`. See [Command-Aware Permissions](/docs/features/command-aware-permissions).
</Note>

When you choose `[A]` or `[D]`, the CLI auto-generates patterns — for example `bash:git *` for git commands, or `tool_name:*` as the default.

## Project storage

Rules and session approvals are stored under the current working directory:

| File                                    | Purpose                         | Commit to git?         |
| --------------------------------------- | ------------------------------- | ---------------------- |
| `.praisonai/permissions/rules.json`     | Persistent allow/deny rules     | Yes — share team rules |
| `.praisonai/permissions/approvals.json` | Per-developer session approvals | No — local only        |

<Note>
  Rules can also be declared directly in `.praisonai/config.yaml` under the `permissions:` key — no CLI commands needed. Both approaches are fully supported and can be used together. See [Single-Source Config](/docs/features/single-source-config) and [Declarative Permissions](/docs/features/declarative-permissions) for details.
</Note>

## Best practices

<AccordionGroup>
  <Accordion title="Commit rules.json for team alignment">
    Share `.praisonai/permissions/rules.json` so everyone gets the same allow/deny defaults.
  </Accordion>

  <Accordion title="Never use bypass in production">
    `--approval bypass` skips every check. Reserve it for fully trusted local sandboxes.
  </Accordion>

  <Accordion title="Use plan for exploration">
    `--approval plan` blocks writes and shell commands while you inspect a codebase.
  </Accordion>

  <Accordion title="Broaden patterns with wildcards">
    Use `bash:git *` instead of one-off rules so related commands stay covered.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Single-Source Config" icon="gear" href="/docs/features/single-source-config">
    Declare permissions in .praisonai/config.yaml
  </Card>

  <Card title="Command-Aware Permissions" icon="shield-halved" href="/docs/features/command-aware-permissions">
    Compound command decomposition and evasion blocking
  </Card>

  <Card title="Declarative Permissions" icon="shield-halved" href="/docs/features/declarative-permissions">
    All permission surfaces — YAML, CLI, Python
  </Card>

  <Card title="Interactive Tool Approval" icon="shield-check" href="/docs/features/interactive-approval">
    User-facing approval experience
  </Card>

  <Card title="Permission Modes" icon="shield" href="/docs/features/permission-modes">
    Mode reference for agents and CLI
  </Card>

  <Card title="Workspace Boundary" icon="shield-halved" href="/docs/features/workspace-boundary">
    Gate shell and file access outside your project root
  </Card>
</CardGroup>