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
Choice [o/s/a/n] (n):

The four keys choose how long the approval lasts — [o] once, [s] this session (in-memory), [a] always (persisted), [n] no. See Interactive Tool Approval for the full scope semantics.

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)

The CLI flag bypass maps to PermissionMode.BYPASS, whose value is bypass_permissions.

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

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"

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.

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

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

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:

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:

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

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.

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:

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

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 and Declarative Permissions for details.

Best practices

Commit rules.json for team alignment

Share .praisonai/permissions/rules.json so everyone gets the same allow/deny defaults.

Never use bypass in production

--approval bypass skips every check. Reserve it for fully trusted local sandboxes.

Use plan for exploration

--approval plan blocks writes and shell commands while you inspect a codebase.

Broaden patterns with wildcards

Use bash:git * instead of one-off rules so related commands stay covered.

Related

Single-Source Config

Declare permissions in .praisonai/config.yaml

Command-Aware Permissions

Compound command decomposition and evasion blocking

Declarative Permissions

All permission surfaces — YAML, CLI, Python

Interactive Tool Approval

User-facing approval experience

Permission Modes

Mode reference for agents and CLI

Workspace Boundary

Gate shell and file access outside your project root