> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airun.me/llms.txt
> Use this file to discover all available pages before exploring further.
# Executable Markdown
> Turn markdown files into AI-powered scripts with shebang support
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:
```markdown theme={null}
#!/usr/bin/env ai
Analyze this codebase and summarize the architecture.
```
**Make it executable and run:**
```bash theme={null}
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:
```markdown Works - no flags theme={null}
#!/usr/bin/env ai
Summarize this project.
```
```markdown Works - with -S flag theme={null}
#!/usr/bin/env -S ai --aws --opus
Analyze this code using AWS Bedrock with Opus.
```
```markdown FAILS - missing -S theme={null}
#!/usr/bin/env ai --aws --opus
# Error: env treats "ai --aws --opus" as a single command
```
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`:
```markdown theme={null}
#!/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`:
```markdown theme={null}
#!/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`:
```markdown theme={null}
#!/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`:
```markdown theme={null}
#!/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`:
```markdown theme={null}
#!/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:
```bash theme={null}
cat data.json | ./analyze-stdin.md
```
### Script with Variables
From `examples/summarize-topic.md`:
```markdown theme={null}
#!/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:
```bash theme={null}
./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:
```markdown theme={null}
#!/usr/bin/env ai
Analyze the test coverage in this codebase.
```
**Automation scripts** that need to write files or run commands require permission flags:
```markdown --skip (common) theme={null}
#!/usr/bin/env -S ai --skip
Run the test suite and fix any failing tests.
```
```markdown --bypass (composable) theme={null}
#!/usr/bin/env -S ai --bypass
Run the linter and auto-fix all issues.
```
```markdown --allowedTools (granular) theme={null}
#!/usr/bin/env -S ai --allowedTools 'Bash(npm test)' 'Read'
Run tests and report results. Do not modify files.
```
`--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):
| Priority | Source | Example |
| --------------- | -------------- | ------------------------------------- |
| **1 - Highest** | CLI flags | `ai --aws --opus script.md` |
| **2** | Shebang flags | `#!/usr/bin/env -S ai --ollama --low` |
| **3** | Saved defaults | `ai --aws --opus --set-default` |
| **4 - Lowest** | Auto-detection | Current Claude subscription |
**Example precedence in action:**
Given a script with this shebang:
```markdown theme={null}
#!/usr/bin/env -S ai --ollama --low
Analyze this code.
```
```bash theme={null}
./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`:
```bash theme={null}
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:
```markdown theme={null}
#!/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:
```bash theme={null}
chmod +x script.md
./script.md
```
Uses shebang flags exactly as written.
```bash theme={null}
ai script.md
ai --aws script.md # Override provider
```
CLI flags override shebang flags.
```bash theme={null}
cat script.md | ai
curl -fsSL https://example.com/script.md | ai
```
Shebang flags are still honored even when piped.
## Combining with Other Features
Shebang scripts work seamlessly with other AIRun features:
**Provider switching:**
```markdown theme={null}
#!/usr/bin/env -S ai --aws --opus
```
**Live streaming:**
```markdown theme={null}
#!/usr/bin/env -S ai --live --skip
```
**Agent teams:**
```markdown theme={null}
#!/usr/bin/env -S ai --team --opus
```
**Custom models:**
```markdown theme={null}
#!/usr/bin/env -S ai --ollama --model qwen3-coder
```
Chain scripts together and process data streams
Switch between cloud providers and models