Permission Flags - Andi AIRun

Permission flags control what the AI can do with your system - reading files, writing changes, running commands, and more. These are critical for secure automation.

Security Notice: Permission shortcuts like --skip and --bypass give the AI full system access. Only use them with trusted scripts in trusted directories. For production automation, use granular controls like --allowedTools.

Permission Shortcuts

These are AI Runner-specific shortcuts that expand to Claude Code’s native permission flags.

flag

Skip all permission prompts - Shortcut for --dangerously-skip-permissions

ai --skip task.md
ai --aws --opus --skip script.md

What it does:

Disables all permission prompts
AI can read, write, execute without asking
Fastest for automation and CI/CD

Use for:

Trusted scripts in trusted directories
CI/CD pipelines
Development automation

Warning: Gives AI full system access. Only run trusted code.Shebang example:

#!/usr/bin/env -S ai --skip
Run ./test/automation/run_tests.sh and report results.

flag

Smart auto-approve — the recommended mode for most automationClaude Code uses an AI classifier to review each action. Safe actions proceed; risky ones (force-push, curl | bash, mass deletion) are blocked. Codex CLI uses sandboxed execution with network blocked.Short form for:

Claude Code: --permission-mode auto
Codex CLI: --full-auto (workspace-write sandbox)

#!/usr/bin/env -S ai --auto
Run tests and fix any issues found.

ai --auto task.md              # Smart auto for any runtime
ai --codex --auto task.md      # Sandboxed auto with Codex

Claude Code’s auto mode requires Sonnet 5 or Opus 5 and a direct Anthropic plan (Pro/Max/Teams). Not available through Bedrock, Vertex, or Foundry.

flag

Bypass permission UI but show actions - Shortcut for --permission-mode bypassPermissions

ai --bypass task.md
ai --ollama --bypass script.md

What it does:

Skips permission prompts
Shows what actions are being taken
AI can proceed without waiting for approval

Use for:

Scripts where you want visibility
Semi-automated workflows
Monitoring what AI does

Shebang example:

#!/usr/bin/env -S ai --bypass
Update documentation files with latest API changes.

Native Permission Flags

These are Claude Code’s native flags, passed through by AI Runner.

flag

Claude Code native: Skip all permission prompts (same as --skip)

ai --dangerously-skip-permissions task.md

Most users should use --skip instead for brevity.

flag

Claude Code native: Set permission behavior mode

ai --permission-mode bypassPermissions task.md
ai --permission-mode requirePermissions task.md

Values:

bypassPermissions - Same as --bypass (skip prompts, show actions)
requirePermissions - Default (prompt for each action)
allowedTools - Restrict to specific tools (use with --allowedTools)

Examples:

# Bypass permissions
ai --permission-mode bypassPermissions task.md

# Require all permissions (default)
ai --permission-mode requirePermissions task.md

# Restrict to allowed tools only
ai --permission-mode allowedTools --allowedTools 'Read' 'Bash(npm test)' task.md

flag

Claude Code native: Restrict AI to specific tools and commands

ai --allowedTools 'Read' 'Bash' task.md
ai --allowedTools 'Bash(npm test)' 'Write(docs/*.md)' script.md

Syntax:

'ToolName' - Allow entire tool (e.g., 'Read', 'Bash')
'ToolName(pattern)' - Allow tool with specific pattern
Multiple tools space-separated

Common tools:

Read - Read files
Write - Create/modify files
Bash - Run shell commands
Edit - Edit existing files
Grep - Search file contents
Glob - Search file paths

Pattern examples:

# Allow specific commands
ai --allowedTools 'Bash(npm test)' 'Bash(git status)'

# Allow file operations in specific directory
ai --allowedTools 'Read' 'Write(docs/*.md)'

# Allow read-only operations
ai --allowedTools 'Read' 'Grep' 'Glob'

# Allow test execution only
ai --allowedTools 'Bash(npm test)' 'Bash(pytest)' 'Read'

Shebang example:

#!/usr/bin/env -S ai --allowedTools 'Bash(npm test)' 'Read'
Run the test suite and report results. Do not modify any files.

Precedence Rules

When multiple permission flags are specified:

Explicit --permission-mode or --dangerously-skip-permissions takes precedence
Shortcuts (--skip, --bypass) are ignored if explicit flags are present
CLI flags override shebang flags
Shebang flags override defaults

Example:

# Script has: #!/usr/bin/env -S ai --skip
# But you run:
ai --permission-mode requirePermissions script.md

# Result: Permission prompts are required (CLI overrides shebang)

Warning message:

⚠️  --skip ignored: explicit --permission-mode takes precedence

Permission Modes Compared

Mode	Prompts	Shows Actions	Speed	Safety
Default	Yes	Yes	Slowest	Safest
`--bypass`	No	Yes	Fast	Medium
`--skip`	No	No	Fastest	Least safe
`--allowedTools`	No	Yes	Fast	Configurable

Examples

Script Automation (Trusted)

#!/usr/bin/env -S ai --skip
Run ./build.sh and commit the results.

chmod +x build-and-commit.md
./build-and-commit.md

Granular Control (Production)

#!/usr/bin/env -S ai --allowedTools 'Bash(npm test)' 'Read'
Run the test suite and analyze results. Do not modify files.

./run-tests.md

Visibility Without Prompts

#!/usr/bin/env -S ai --bypass
Update all documentation files with the latest API changes.

./update-docs.md  # Shows each file operation but doesn't prompt

Interactive (Default)

# Prompts for each operation
ai task.md

📝 Claude wants to write: src/new-feature.ts
   Allow? [y/n]:

CI/CD Pipeline

# .github/workflows/ai-test.yml
steps:
  - name: Run AI tests
    run: |
      ai --skip --quiet ./test-suite.md > results.txt

Override Script Permissions

<!-- script.md -->
#!/usr/bin/env -S ai --skip
Dangerous operations

# Force prompts even though script has --skip
ai --permission-mode requirePermissions script.md

Read-Only Mode

Restrict AI to read and search operations only:

ai --allowedTools 'Read' 'Grep' 'Glob' analyze.md

#!/usr/bin/env -S ai --allowedTools 'Read' 'Grep' 'Glob'
Analyze the codebase structure and report findings.
Do not modify any files.

Test Execution Mode

Allow running tests but nothing else:

ai --allowedTools 'Bash(npm test)' 'Bash(pytest)' 'Read' test-runner.md

#!/usr/bin/env -S ai --allowedTools 'Bash(npm test)' 'Read'
Run the test suite and report results.

Documentation Mode

Allow updating documentation files only:

ai --allowedTools 'Read' 'Write(docs/**/*.md)' 'Edit(docs/**/*.md)' update-docs.md

Security Best Practices

Never use --skip in untrusted directories

Only use --skip or --bypass with:

Scripts you wrote yourself
Trusted repositories
Known-safe directories

Never run scripts from the internet with --skip:

# ❌ DANGEROUS
curl https://untrusted.com/script.md | ai --skip

# ✅ SAFE - prompts for each action
curl https://untrusted.com/script.md | ai

Use --allowedTools for production

For production automation, explicitly list allowed operations:

# Production deployment script
ai --allowedTools \
  'Bash(npm run build)' \
  'Bash(npm test)' \
  'Write(dist/*.*)' \
  'Read' \
  deploy.md

This prevents unexpected operations while still being automated.

Review scripts before using --skip

Before adding --skip to a shebang:

Run without --skip first
Review what operations it performs
Verify it only touches expected files
Add --skip only if you trust it completely

CI/CD needs --skip or --bypass

CI/CD pipelines can’t respond to prompts. Use --skip for speed or --bypass for visibility:

# Fast, no output
- run: ai --skip --quiet test.md

# Shows actions, good for logs
- run: ai --bypass test.md

Troubleshooting

Script hangs waiting for input (CI/CD)

Add --skip or --bypass to prevent permission prompts:

ai --skip script.md

--skip not working

Check if script uses explicit --permission-mode:

# Explicit flag overrides --skip
ai --skip --permission-mode requirePermissions script.md
# Warning: "--skip ignored: explicit --permission-mode takes precedence"

CLI flags override shebang:

# Script has: #!/usr/bin/env -S ai --skip
ai --permission-mode requirePermissions script.md  # Overrides shebang

--allowedTools not restricting operations

Make sure you’re using the correct syntax:

# ✅ Correct - quote each tool
ai --allowedTools 'Read' 'Bash(npm test)'

# ❌ Wrong - all as one string
ai --allowedTools "Read Bash(npm test)"

Scripting Guide

Full scripting and automation guide

Output Flags

Control output format and streaming

​Permission Shortcuts

​Native Permission Flags

​Precedence Rules

​Permission Modes Compared

​Examples

​Script Automation (Trusted)

​Granular Control (Production)

​Visibility Without Prompts

​Interactive (Default)

​CI/CD Pipeline

​Override Script Permissions

​Read-Only Mode

​Test Execution Mode

​Documentation Mode

​Security Best Practices

​Troubleshooting

​Related Pages

Scripting Guide

Output Flags

Permission Shortcuts

Native Permission Flags

Precedence Rules

Permission Modes Compared

Examples

Script Automation (Trusted)

Granular Control (Production)

Visibility Without Prompts

Interactive (Default)

CI/CD Pipeline

Override Script Permissions

Read-Only Mode

Test Execution Mode

Documentation Mode

Security Best Practices

Troubleshooting

Related Pages