Skip to main content
The axon run command performs full end-to-end execution of AXON programs, from source code to final output. It compiles the source, targets a backend, and executes through the AXON runtime.

​
Synopsis

axon run <file.axon> [options]

​
Description

Executes the complete AXON pipeline:
  1. Compile — Lex → Parse → Type Check → IR Generation
  2. Backend Compile — Transform IR to backend-specific prompts
  3. Execute — Run through the AXON runtime with configured backend
  4. Output — Display results and optional execution trace
This command requires a valid API key for the chosen backend (e.g., ANTHROPIC_API_KEY). See API Keys for setup.

​
Arguments

​
file
string
required
Path to the .axon source file to execute

​
Options

​
--backend
string
default:"anthropic"
LLM backend to use for execution.Choices: anthropic, openai, gemini, ollamaShort form: -b
​
--trace
flag
Save execution trace to <filename>.trace.json for debugging and analysis.
​
--tool-mode
string
default:"stub"
Tool execution mode:
  • stub: Use fake tools (no external calls, safe for testing)
  • real: Use production tool backends (requires API keys)
  • hybrid: Prefer real tools, fallback to stubs
Choices: stub, real, hybrid

​
Exit Codes

CodeMeaning
0Success — execution completed without errors
1Compilation or execution error
2I/O error or missing API key

​
Output Format

​
Success Output

$ axon run contract_analyzer.axon

════════════════════════════════════════════════════════════
  AXON Execution Result
════════════════════════════════════════════════════════════

  status: success
  
  output:
    {
        "parties": [
            {"name": "Acme Corp", "role": "Vendor"},
            {"name": "Beta Inc", "role": "Client"}
        ],
        "risk_score": 0.65,
        "summary": "Contract contains 3 high-risk clauses..."
    }

════════════════════════════════════════════════════════════

​
With Trace Saved

$ axon run program.axon --trace

════════════════════════════════════════════════════════════
  AXON Execution Result
════════════════════════════════════════════════════════════
  ...
════════════════════════════════════════════════════════════

📋 Trace saved → program.trace.json

​
Error Output

$ axon run broken.axon
✗ Compilation error: Type mismatch at line 23

$ axon run program.axon --backend openai
✗ Backend error: OPENAI_API_KEY not set

​
Examples

​
Basic Execution

axon run program.axon
Run with default settings (Anthropic backend, stub tools).

​
Production Execution

export ANTHROPIC_API_KEY="sk-ant-..."
export SERPER_API_KEY="..."
axon run program.axon --backend anthropic --tool-mode real
Execute with production LLM and real tool backends.

​
With Execution Trace

axon run program.axon --trace
axon trace program.trace.json
Save and visualize execution trace for debugging.

​
Different Backends

# Anthropic Claude
axon run program.axon --backend anthropic

# OpenAI GPT
axon run program.axon --backend openai

# Google Gemini
axon run program.axon --backend gemini

# Local Ollama
axon run program.axon --backend ollama

​
Safe Testing with Stubs

# No API calls, no external dependencies
axon run program.axon --tool-mode stub
Perfect for:
  • Unit testing
  • CI/CD pipelines
  • Development without API keys
export SERPER_API_KEY="..."
axon run program.axon --tool-mode hybrid
  • Uses real tools where API keys are available
  • Falls back to stubs automatically
  • Best for development environments

​
Batch Execution

#!/bin/bash
for file in programs/*.axon; do
  echo "Running $file..."
  axon run "$file" --trace || echo "Failed: $file"
done

​
CI/CD Integration

# GitHub Actions example
- name: Test AXON Programs
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    axon run tests/test_program.axon --tool-mode stub

​
Execution Trace

When --trace is enabled, AXON records detailed execution information: 
{
  "_meta": {
    "source": "program.axon",
    "backend": "anthropic",
    "axon_version": "0.4.0a0",
    "start_time": "2026-03-06T15:23:45.123Z",
    "duration_ms": 1247
  },
  "events": [
    {
      "type": "step_start",
      "timestamp": "2026-03-06T15:23:45.234Z",
      "data": {"step_name": "Extract"}
    },
    {
      "type": "model_call",
      "timestamp": "2026-03-06T15:23:45.456Z",
      "data": {
        "model": "claude-3-5-sonnet-20241022",
        "prompt_tokens": 342,
        "completion_tokens": 156
      }
    },
    {
      "type": "validation_pass",
      "timestamp": "2026-03-06T15:23:46.789Z",
      "data": {"type": "EntityMap"}
    }
  ]
}
Trace events include:
  • Step execution
  • Model API calls
  • Anchor checks
  • Validation results
  • Retry attempts
  • Memory operations
Analyze traces with: 
axon trace program.trace.json

​
Tool Modes Explained

​
Stub Mode (Default)

axon run program.axon --tool-mode stub
Behavior:
  • All tools return fake data
  • No external API calls
  • No file system access
  • Deterministic results
Use Cases:
  • Testing
  • CI/CD
  • Development without credentials
Available Tools (all stubbed):
  • WebSearch → Returns mock search results
  • FileReader → Returns mock file contents
  • CodeExecutor → Returns mock execution results
  • PDFExtractor, ImageAnalyzer, APICall (stubs)
  • Calculator, DateTime (always real)

​
Real Mode

axon run program.axon --tool-mode real
Behavior:
  • All tools use production backends
  • Requires API keys for external services
  • Fails if dependencies missing
Use Cases:
  • Production execution
  • Integration testing
  • Real-world workflows
Available Tools:
  • WebSearch → Serper.dev API
  • FileReader → Local filesystem
  • CodeExecutor → subprocess execution
  • Calculator, DateTime → stdlib (always available)
axon run program.axon --tool-mode hybrid
Behavior:
  • Prefers real backends where available
  • Falls back to stubs automatically
  • Graceful degradation
Use Cases:
  • Development with partial credentials
  • Mixed test/production environments
  • Gradual rollout of real tools

​
Backend Configuration

Each backend requires specific setup. See API Keys for detailed configuration.

​
Anthropic (Claude)

export ANTHROPIC_API_KEY="sk-ant-api03-..."
axon run program.axon --backend anthropic
Models Used: claude-3-5-sonnet-20241022 (default)

​
OpenAI (GPT)

export OPENAI_API_KEY="sk-proj-..."
axon run program.axon --backend openai
Models Used: gpt-4-turbo or gpt-4o (varies by backend logic)

​
Google Gemini

export API_KEY_GEMINI="AIza..."
axon run program.axon --backend gemini
Models Used: gemini-1.5-pro

​
Ollama (Local)

# Ensure Ollama is running locally
ollama serve

axon run program.axon --backend ollama
Models Used: llama3.1, mistral, or custom local models

​
Troubleshooting

​
Missing API Key

✗ Backend error: ANTHROPIC_API_KEY not set
Solution: Set the required environment variable: 
export ANTHROPIC_API_KEY="your-key-here"

​
Execution Failed

✗ Execution failed: AnchorBreachError at step 'Assess'
Solution: Check execution trace for details: 
axon run program.axon --trace
axon trace program.trace.json

​
Tool Backend Error

✗ Tool 'WebSearch' failed: SERPER_API_KEY not set
Solution: Either:
  • Set the required API key, OR
  • Use --tool-mode stub for testing

​
Network Timeout

Solution: Increase timeout in your program or check network connectivity.

check

Validate before running

compile

Compile without execution

trace

Analyze execution traces

​
Performance Tips

  1. Use stubs for development: Avoid API costs and latency
  2. Enable tracing selectively: Adds ~5-10% overhead
  3. Batch similar programs: Reuse backend connections
  4. Cache compiled IR: Use axon compile + load IR for repeated runs

Build docs developers (and LLMs) love

Get started for freeTalk to us