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

Clone the repository

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

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.

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.

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).

Make it executable

chmod +x hello.md

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:

Command	Description
`ai` / `airun`	Universal entry point - run scripts, switch providers
`ai update`	Update AI Runner to the latest version
`ai-sessions`	View active AI coding sessions
`ai-status`	Show 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

Get Started

Core Concepts

Guides

Providers

Advanced

Quickstart

Quickstart

Prerequisites

Installation

Your First Executable AI Script

Example: Piping Data

Example: Script Variables

Example: Unix Pipes

Switch Providers

Available Commands

Next Steps

Installation Guide

Provider Setup

Examples

Scripting Guide

Tips

​Quickstart

​Prerequisites

​Installation

​Your First Executable AI Script

​Example: Piping Data

​Example: Script Variables

​Example: Unix Pipes

​Switch Providers

​Available Commands

​Next Steps

Installation Guide

Provider Setup

Examples

Scripting Guide

​Tips

Quickstart

Prerequisites

Installation

Your First Executable AI Script

Example: Piping Data

Example: Script Variables

Example: Unix Pipes

Switch Providers

Available Commands

Next Steps

Tips