Skip to main content
See AI output as it’s generated, not just when complete. This example shows how --live streams progress for long-running scripts.

The Script

From examples/live-report.md. Note the key phrase: “Print your findings as you go.”

How It Works

The --live Flag

Enables real-time streaming of AI output. Instead of waiting for the full response, you see text appear as the AI writes it. Without --live:
With --live:

How Streaming Works

--live streams at turn granularity - each time Claude writes text between tool calls, that text appears immediately.
Critical insight: The AI must be prompted to narrate its progress, otherwise it may work silently using tools and only output text at the end.Streams incrementally:
No intermediate output:
Both produce the same final result, but only the first streams progress.

Prompting for Live Output

Use these phrases to get streaming output:
  • “Print as you go”
  • “Report findings as you discover them”
  • “Describe each step”
  • “Narrate your progress”
  • “Step by step, explain what you find”
These prompt the AI to write text between tool calls, giving --live something to stream.

Running the Script

Basic Usage

You’ll see output stream in real-time:

Save Output to File

When stdout is redirected, --live automatically separates narration from content: Console (stderr) - streams in real-time:
File (stdout) - clean content only:
How it works:
  • Intermediate turns (narration) → stderr (appears on console)
  • Last turn content → stdout (saved to file)
  • The last turn is split at the first markdown heading or YAML frontmatter
  • Only the structured content goes to the file

Override Model or Provider

Suppress Status Messages

For CI/CD where you only want clean output:
No status messages, just the final report saved to the file.

Real-World Usage

Repository Documentation

Generate README documentation with live progress:
You’ll see progress on console, clean README saved to file.

Onboarding New Team Members

Security Audit with Progress

Long-Running Test Suites

Browser Automation with Live Progress

Combine --live with --chrome for browser testing:
You’ll see each step as it happens:

Output Redirection Patterns

Narration to Console, Content to File

This is the default behavior when redirecting:
  • Narration streams to console (stderr)
  • Clean report saved to file (stdout)

Everything to File (No Console Output)

Both stdout and stderr go to the file.

Only Status Messages (No Content)

See progress on console, discard the final report.

Separate Files for Narration and Content

  • Clean report → report.md
  • Progress narration → progress.log

Requirements

--live requires jq to be installed:
If jq is not installed, AIRun will fall back to non-streaming output and show a warning.

When to Use --live

Use --live for:
  • Long-running scripts (>30 seconds) where you want to see progress
  • Browser automation to see each step as it happens
  • Test suites to see results as tests complete
  • Repository exploration to understand what the AI is examining
  • CI/CD to get real-time build logs
Don’t use --live for:
  • Quick scripts (under 10 seconds) where streaming adds no value
  • Pipe chains where you’re piping to another script
  • JSON output where structured data is needed

Combining with Other Flags

Live + Quiet (CI/CD)

Streaming to stdout, no status messages on stderr. Good for CI/CD logs.

Live + Variables

Live + Provider Override

Troubleshooting

No Intermediate Output

Problem: Using --live but only seeing output at the end. Solution: Add narration phrases to your prompt:

Output Not Streaming to Console

Problem: Output appears all at once instead of streaming. Solution: Check that jq is installed:
If not found:

Wrong Content in File

Problem: Redirected file contains narration instead of just the report. Solution: Make sure your prompt ends with a clear content marker:
The # heading tells AIRun where content starts.

Next Steps

Test Automation

Add —live to test scripts

CI/CD Integration

Use live output in CI/CD pipelines

Data Processing

Stream processing for large datasets

Scripting Guide

Complete guide to streaming output