Permissions - PraisonAI

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

Quick Start

Run with interactive approval

praisonai --approval console run "Check git status"

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

Persist with always

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

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

Flag	Mode	Behaviour
`--approval console`	`DEFAULT`	Prompt for sensitive tools
`--approval plan`	`PLAN`	Block write, edit, delete, bash, shell
`--plan` (shortcut)	`PLAN`	Alias for `--approval plan`. Read-only — write, edit, delete, bash, shell are denied. Cannot be combined with `--approval`, `--allow`, `--deny`, or `--permission-default`.
`--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"

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

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 — does not authorise `.env`/private keys — see Secret-File Read Gate
`read:*.env`	`.env` reads — required to opt in past the Secret-File Read Gate
`read:*.pem`	Reads of PEM private keys — gated by default
`read:id_rsa`	Reads of SSH private keys — gated by default
`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.

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"

Allowing read:*.env lets an agent forward the contents of .env to the model provider. Only opt in for trusted CI/workflows, and prefer a persistent approval or per-agent scope over a project-wide rule. See Secret-File Read Gate.

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.

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

​Quick Start

​Approval prompt

​CLI approval modes

​Read-only mode shortcut

​Non-interactive mode

​Subcommands

​list

​allow

​deny

​ask

​remove

​reset

​export

​import

​Rule patterns

​external_dir: patterns

​Opt in to reading .env

​Project storage

​Best practices

​Related

Single-Source Config

Command-Aware Permissions

Declarative Permissions

Interactive Tool Approval

Permission Modes

Workspace Boundary

Quick Start

Approval prompt

CLI approval modes

Read-only mode shortcut

Non-interactive mode

Subcommands

`list`

`allow`

`deny`

`ask`

`remove`

`reset`

`export`

`import`

Rule patterns

external_dir: patterns

Opt in to reading `.env`

Project storage

Best practices

Related