Skip to main content
Declarative permissions let you pre-declare which tool calls to allow, deny, or ask about — so unattended CLI/CI runs stay safe without interactive prompts.

​
Quick Start

1

YAML

# agents.yaml
permissions:
  "read:*": allow
  "bash:rm *": deny
  "*": ask

agents:
  assistant:
    role: Assistant
    instructions: Help safely

praisonai run agents.yaml
2

CLI flags

praisonai run "deploy the app" \
  --allow 'read:*' \
  --allow 'bash:git *' \
  --deny 'bash:rm *' \
  --permission-default ask
3

Python

from praisonaiagents import Agent
from praisonaiagents.approval.protocols import ApprovalConfig

agent = Agent(
    name="CI Worker",
    instructions="Run safely in CI",
    approval=ApprovalConfig(permissions={
        "read:*": "allow",
        "bash:rm *": "deny",
    }),
)

​
How It Works

On each tool call, the backend builds a target string (tool_name:arg) and PermissionManager.check() returns allow, deny, or ask. Non-interactive runs honour declared rules; ask without a human present falls back to deny.

​
Pattern Syntax

Patterns use <tool_name>:<arg-glob>:
PatternMeaning
read:*Any read tool call
bash:git *Git shell commands
write:/etc/*Writes under /etc/
Detailed dict form supports is_regex, priority, agent_name, and description: 
permissions:
  "read:*": allow
  "bash:rm *":
    action: deny
    description: Block destructive shell ops
    priority: 100

​
Configuration Surfaces

SurfaceWhereExample
YAMLTop-level or per-agent approval.permissions:"bash:rm *": deny
CLI--allow, --deny, --permissions <file>, --permission-default--deny 'bash:rm *'
PythonApprovalConfig(permissions={...}){"read:*": "allow"}
Precedence: agent-level approval.permissions → top-level YAML permissions: → CLI --allow/--deny (override file) → --permission-default → built-in defaults. Load from file: 
praisonai run agents.yaml --permissions permissions.yaml --deny 'bash:curl *'

​
Common Patterns

Read-only CI runner — --permission-default deny with --allow 'read:*'. Git-only worker — allow bash:git *, deny everything else. Deny destructive commands — baseline "bash:rm *": deny and "write:/etc/*": deny.

​
Best Practices

Use --permission-default deny or "*": deny so undeclared tools are blocked.
Higher-priority rules win — declare bash:git push * before broad bash:*.
Keep permissions.yaml next to agents.yaml in git.
Verify rules before deploying to CI.

Permissions

Programmatic PermissionManager API

Approval

Interactive approval backends

Tool Approval CLI

CLI flags reference