Skip to main content
The simplest possible AIRun script. This example shows the basic shebang syntax and how to make a markdown file executable.

​
The Script

#!/usr/bin/env -S ai --haiku
Say hello and briefly explain what you can do.
This is the complete script from examples/hello.md. It’s only 2 lines!

​
How It Works

​
The Shebang Line

#!/usr/bin/env -S ai --haiku
This line tells your system how to run the file:
  • #!/usr/bin/env - Standard Unix shebang for finding executables in PATH
  • -S - Essential flag that allows passing arguments (like --haiku) to the command
  • ai - The AIRun command
  • --haiku - Use the fastest, cheapest model tier (perfect for simple tasks)
You must use -S when passing flags in a shebang. Without it, env treats ai --haiku as a single command name and fails.Works: #!/usr/bin/env -S ai --haikuFails: #!/usr/bin/env ai --haiku

​
The Prompt

Everything after the shebang is your prompt: 
Say hello and briefly explain what you can do.
No special syntax needed - just write what you want the AI to do.

​
Running the Script

​
Method 1: Make it executable and run directly

# Make the file executable
chmod +x hello.md

# Run it
./hello.md
The shebang tells your system to use ai --haiku to execute the file.

​
Method 2: Run with the ai command

# Shebang flags are still honored
ai hello.md

​
Method 3: Override the model

# Use Sonnet instead of Haiku (CLI overrides shebang)
ai --sonnet hello.md

# Use a different provider
ai --aws --opus hello.md
Flag precedence: CLI flags > shebang flags > saved defaultsRunning ai --sonnet hello.md overrides the --haiku in the shebang.

​
Why Use Haiku?

This script uses --haiku because:
  • Fastest - Haiku responds in milliseconds
  • Cheapest - Lowest cost per token
  • Sufficient - Simple text generation doesn’t need Opus
Model selection guide:
TaskModel
Simple text, greetings, summaries--haiku
Code analysis, test running--sonnet
Complex reasoning, architecture design--opus

​
Creating Your Own

Create a new script: 
cat > greet.md << 'EOF'
#!/usr/bin/env -S ai --haiku
Write a friendly greeting and tell me a fun fact about AI.
EOF

chmod +x greet.md
./greet.md

​
Read-Only by Default

This script doesn’t need any permission flags because it only generates text. It cannot:
  • Write files
  • Run commands
  • Modify your system
For scripts that need to take actions, see:

​
Next Steps

Code Analysis

Analyze codebases without modifying anything

Variables

Add customizable parameters to scripts

Test Automation

Run commands and report results

Scripting Guide

Complete guide to executable markdown