Skip to main content

​
Quickstart

Get AIRun running in 5 minutes. This guide will help you install AIRun, create your first executable AI script, and run it.

​
Prerequisites

Before you begin, make sure you have at least one AI runtime installed — Claude Code or Codex CLI. AIRun works with either. 
# Install a runtime (one or both)
curl -fsSL https://claude.ai/install.sh | bash   # Claude Code (Anthropic)
npm install -g @openai/codex                      # Codex CLI (OpenAI)
You need an active Claude subscription or Codex/OpenAI account. AIRun auto-detects which runtime is available.

​
Installation

1

Clone the repository

git clone https://github.com/andisearch/airun.git
cd airun
2

Run the setup script

./setup.sh
The setup script will:
  • Install commands to /usr/local/bin
  • Create ~/.ai-runner/ for configuration
  • Copy a secrets template for API keys
The setup is non-destructive. Your plain claude command always works unchanged.
3

Verify installation

ai --version
You should see the AIRun version number.

​
Your First Executable AI Script

Let’s create a simple executable markdown file that runs as an AI program.
1

Create a markdown file

Create a file called hello.md with the following content:
hello.md
#!/usr/bin/env -S ai --haiku
Say hello and briefly explain what you can do.
The first line is a shebang that tells the system to run this file with AIRun using the Haiku model (fastest and most cost-effective).
2

Make it executable

chmod +x hello.md
3

Run it

./hello.md
The AI will execute your prompt and respond. This uses your Claude subscription by default.
You can also run any markdown file without making it executable:
ai hello.md

​
Example: Piping Data

One of AIRun’s most powerful features is Unix-style piping. Let’s create a script that analyzes data:
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.
The --skip flag is shorthand for --dangerously-skip-permissions, which gives the AI full system access. Only use it in trusted directories with trusted scripts.
Make it executable and run it: 
chmod +x analyze-code.md
./analyze-code.md

​
Example: Script Variables

Create reusable scripts with customizable variables:
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.
Run with defaults or override variables: 
# Use defaults
./summarize-topic.md

# Override variables
./summarize-topic.md --topic "AI safety" --style formal --length detailed

​
Example: Unix Pipes

Pipe data into your AI scripts: 
# Analyze JSON data
cat data.json | ./analyze.md > results.txt

# Summarize git history
git log --oneline -20 | ./summarize-changes.md

# Chain scripts together
./generate-report.md | ./format-output.md > final.txt

​
Switch Providers

Use different AI providers by adding flags: 
# Use local Ollama (free!)
ai --ollama hello.md

# Use AWS Bedrock with Opus
ai --aws --opus hello.md

# Use Google Vertex AI
ai --vertex hello.md

# Use Vercel AI Gateway with a specific model
ai --vercel --model openai/gpt-5.2-codex hello.md
You’ll need to configure your API credentials for cloud providers. See the Installation Guide for details.

​
Available Commands

AIRun installs these commands:
CommandDescription
ai / airunUniversal entry point - run scripts, switch providers
ai updateUpdate AI Runner to the latest version
ai-sessionsView active AI coding sessions
ai-statusShow current configuration and provider status

​
Next Steps

Installation Guide

Detailed installation and configuration instructions

Provider Setup

Configure AWS, Azure, Vertex, and other providers

Examples

More example scripts and use cases

Scripting Guide

Learn advanced scripting patterns and automation

​
Tips

Use #!/usr/bin/env -S for shebangs with flagsStandard env only accepts one argument, so you need -S to pass multiple flags:
#!/usr/bin/env -S ai --aws --opus
Flag precedence: CLI flags > shebang flags > saved defaultsRunning ai --vercel task.md overrides the script’s shebang provider.
Set a default provider
ai --ollama --set-default
ai task.md  # uses Ollama by default
ai --clear-default  # remove saved default