--live streams progress for long-running scripts.
The Script
How It Works
The --live Flag
--live:
--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”
--live something to stream.
Running the Script
Basic Usage
Save Output to File
--live automatically separates narration from content:
Console (stderr) - streams in real-time:
- 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:Real-World Usage
Repository Documentation
Generate README documentation with live progress:Onboarding New Team Members
Security Audit with Progress
Long-Running Test Suites
Browser Automation with Live Progress
Combine--live with --chrome for browser testing:
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)
Only Status Messages (No Content)
Separate Files for Narration and Content
- Clean report →
report.md - Progress narration →
progress.log
Requirements
--live requires jq to be installed:
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
--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)
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 thatjq is installed:
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:# 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