Skip to main content
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.
​
--skip
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.
​
--bypass
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.
​
--dangerously-skip-permissions
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.
​
--permission-mode
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
​
--allowedTools
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:
  1. Explicit --permission-mode or --dangerously-skip-permissions takes precedence
  2. Shortcuts (--skip, --bypass) are ignored if explicit flags are present
  3. CLI flags override shebang flags
  4. 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

ModePromptsShows ActionsSpeedSafety
DefaultYesYesSlowestSafest
--bypassNoYesFastMedium
--skipNoNoFastestLeast safe
--allowedToolsNoYesFastConfigurable

​
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

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
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.
Before adding --skip to a shebang:
  1. Run without --skip first
  2. Review what operations it performs
  3. Verify it only touches expected files
  4. Add --skip only if you trust it completely
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

Add --skip or --bypass to prevent permission prompts:
ai --skip script.md
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
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