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.

Quick Start

1. Run with interactive approval

   praisonai --approval console run "Check git status"

   When a sensitive tool runs, you see the approval prompt.

2. Persist with always

   Press a at the prompt to write a persistent allow-rule to approvals.json.

3. Re-run without prompting

   praisonai --approval console run "Check git status again"

   Matching rules are applied automatically.

Approval prompt

🔒 Tool Approval Required
Function: execute_command
Risk Level: MEDIUM
Agent: researcher
Arguments:
  command: git status

Allow execute_command?  [o] once   [s] this session   [a] always (bash:git status *)   [n] no   [d] deny & redirect
Choice [o/s/a/n/d] (n):

The five keys choose how long the approval lasts:

• [o] once — consumed after this exact call; a second matching call re-prompts
• [s] session — kept in memory for this process
• [a] always — persisted to ~/.praisonai/permissions/ and reused across runs
• [n] no — deny once
• [d] deny & redirect — deny, then type what the agent should do instead at the What should the agent do instead? follow-up; the guidance steers the next turn

See Interactive Tool Approval for the full scope semantics.

CLI approval modes

praisonai --approval plan run "Explore the codebase"
praisonai --approval accept-edits run "Refactor utils.py"

Read-only mode shortcut

--plan on praisonai run and praisonai code is a discoverable shortcut for --approval plan.

praisonai run  --plan "Explore the codebase"
praisonai code --plan "Draft a migration plan"

Both wrap --approval plan (PermissionMode.PLAN) — the underlying enforcement is unchanged. --plan cannot be combined with --approval, --allow, --deny, or --permission-default (and on code, not with --no-safe / --dangerously-skip-approval); contradictory combinations exit 1. See Permission Modes.

Non-interactive mode

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.

praisonai permissions list

allow

Add an ALLOW rule.

praisonai permissions allow "bash:git *" --description "Allow git"

deny

Add a DENY rule.

praisonai permissions deny "bash:rm *" --priority 200

ask

Add an ASK rule (always prompt).

praisonai permissions ask "bash:*" --agent researcher

remove

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

praisonai permissions remove a1b2c3d4

reset

Delete all rules and approvals (requires confirmation).

praisonai permissions reset

export

Print rules as JSON to stdout.

praisonai permissions export > rules.json

import

Import rules from a JSON file.

praisonai permissions import rules.json

Rule patterns

Patterns use tool_name:argument_pattern glob syntax:

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:

# 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 for full details on what triggers the gate and how to configure it.

Opt in to reading .env

Reading .env/private keys defaults to ask even with a broad read:* allow. Teams who genuinely need credential-file reads opt in with a secret-specific rule:

# Allow reading .env files (secret-specific — a broad read:* won't do)
praisonai permissions allow "read:*.env" --description "CI reads .env"

When you choose [a] always, the CLI auto-generates a scoped pattern — for example bash:git status * for a git subcommand, or tool:<tool_name> as the default.

Project storage

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

Best practices

Related