Quickstart

Get started with AIRun in 5 minutes - install, create your first executable AI script, and run it

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 Claude Code installed. AIRun extends Claude Code with executable markdown and provider switching.

# Install Claude Code (if not already installed)
curl -fsSL https://claude.ai/install.sh | bash

Claude Code is Anthropic’s AI coding CLI. You’ll need an active Claude subscription (Pro or Max) or API credentials to use it.

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:

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 flags

Standard 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 defaults

Running 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