Skip to main content
Andi AIRun makes markdown files executable using Unix shebang syntax. Add a shebang line to any markdown file, make it executable, and run it directly as a command.

​
How Shebang Scripts Work

A shebang (#!) at the start of a file tells the operating system which interpreter to use. AIRun uses #!/usr/bin/env ai to run markdown files as AI prompts: 
#!/usr/bin/env ai
Analyze this codebase and summarize the architecture.
Make it executable and run: 
chmod +x task.md
./task.md
The AI reads the prompt from the file and executes it in your current directory, just like running ai task.md.

​
The -S Flag Requirement

Standard env only accepts one argument. If you want to pass flags to ai in your shebang, you must use env -S to split the string into multiple arguments: 
#!/usr/bin/env ai
Summarize this project.
Always use #!/usr/bin/env -S ai when your shebang includes flags like --aws, --skip, or --live.

​
Shebang Examples from the Repository

​
Basic Hello World

From examples/hello.md: 
#!/usr/bin/env -S ai --haiku
Say hello and briefly explain what you can do.
The --haiku flag selects a fast, cost-effective model for simple tasks.

​
Code Analysis

From examples/analyze-code.md: 
#!/usr/bin/env -S ai --sonnet --skip
Summarize the architecture of this codebase. List the main entry points,
key modules, and how data flows through the system.
  • --sonnet: Balanced model for code analysis
  • --skip: Shortcut for --dangerously-skip-permissions — allows the AI to read files without prompting

​
Live Streaming Report

From examples/live-report.md: 
#!/usr/bin/env -S ai --sonnet --skip --live
Explore this repository and write a short summary of what it does,
its key features, and how to get started. Print your findings as you go.
Finally, generate a concise report in markdown format.
The --live flag streams output in real-time as the AI works, showing progress incrementally.

​
Test Automation

From examples/run-tests.md: 
#!/usr/bin/env -S ai --sonnet --skip
Run the test suite for this project. Report which tests passed and which
failed. If any tests fail, explain the root cause.

​
Stdin Processing

From examples/analyze-stdin.md: 
#!/usr/bin/env -S ai --haiku
Analyze the data provided on stdin. Summarize the key points, highlight
anything unusual, and suggest next steps.
Run with piped input: 
cat data.json | ./analyze-stdin.md

​
Script with Variables

From examples/summarize-topic.md: 
#!/usr/bin/env -S ai --haiku
---
vars:
  topic: "machine learning"
  style: casual
  length: short
---
Write a {{length}} summary of {{topic}} in a {{style}} tone.
Override variables from the command line: 
./summarize-topic.md --topic "AI safety" --style formal --length "detailed"

​
Permission Modes for Automation

Read-only scripts (default) can analyze code but won’t modify anything: 
#!/usr/bin/env ai
Analyze the test coverage in this codebase.
Automation scripts that need to write files or run commands require permission flags: 
#!/usr/bin/env -S ai --skip
Run the test suite and fix any failing tests.
--skip and --bypass give the AI full system access. Only run trusted scripts in trusted directories. For granular control, use --allowedTools to specify exactly which operations are allowed.

​
Flag Precedence

When you run a script, flags are resolved in this order (highest priority first):
PrioritySourceExample
1 - HighestCLI flagsai --aws --opus script.md
2Shebang flags#!/usr/bin/env -S ai --ollama --low
3Saved defaultsai --aws --opus --set-default
4 - LowestAuto-detectionCurrent Claude subscription
Example precedence in action: Given a script with this shebang: 
#!/usr/bin/env -S ai --ollama --low
Analyze this code.

./script.md              # Uses Ollama (shebang)
ai script.md             # Uses Ollama (shebang)
ai --aws script.md       # Uses AWS (CLI overrides shebang)
If you’ve also run ai --vertex --set-default: 
ai script.md             # Still uses Ollama (shebang beats saved default)
ai --resume              # Uses Vertex (no script, so default applies)
CLI flags always override shebang flags, and shebang flags always override saved defaults. This lets you keep scripts with sensible defaults while overriding them when needed.

​
Passthrough Flags

AIRun handles its own flags (--aws, --opus, --live, --skip, etc.) and passes unrecognized flags directly to Claude Code: 
#!/usr/bin/env -S ai --skip --chrome --max-turns 10
Navigate to the app and verify the login flow works.
  • --skip: AIRun flag (permission mode)
  • --chrome: Claude Code flag (browser automation)
  • --max-turns 10: Claude Code flag (limit iterations)

​
Running Scripts

There are three ways to run executable markdown: 
chmod +x script.md
./script.md
Uses shebang flags exactly as written.

​
Combining with Other Features

Shebang scripts work seamlessly with other AIRun features: Provider switching: 
#!/usr/bin/env -S ai --aws --opus
Live streaming: 
#!/usr/bin/env -S ai --live --skip
Agent teams: 
#!/usr/bin/env -S ai --team --opus
Custom models: 
#!/usr/bin/env -S ai --ollama --model qwen3-coder

Unix Pipes

Chain scripts together and process data streams

Provider Switching

Switch between cloud providers and models