Skip to main content
Output flags control how AI Runner displays results, handles streaming, and processes piped input.

​
Streaming Flags

​
--live
flag
Stream output in real-time - Display AI responses as they’re generated
ai --live task.md
ai --aws --opus --live script.md
ai --live --skip automation.md
What it does:
  • Enables real-time streaming output
  • Shows AI response as it’s being generated (word by word)
  • Status messages go to stderr, clean output to stdout
  • Automatically adds --output-format stream-json --verbose
Requirements:
  • jq must be installed: brew install jq
Use for:
  • Long-running scripts where you want progress
  • Scripts that generate reports (output to file, narration to console)
  • Debugging and monitoring
Example:
# Stream to console, clean output to file
ai --live report.md > output.txt
Shebang:
#!/usr/bin/env -S ai --live --skip
Generate a detailed report of the codebase.
Print progress updates as you work.
​
--quiet
flag
Suppress status messages - Clean output only (perfect for CI/CD)
ai --quiet task.md
ai -q script.md
ai --live --quiet report.md > output.txt
Short form: -qWhat it does:
  • Disables --live status narration
  • Suppresses “Using: …” and “Model: …” messages
  • Only shows AI response (clean stdout)
  • Perfect for piping and file redirection
Use for:
  • CI/CD pipelines
  • Script output that feeds into other tools
  • File generation without noise
Examples:
# Clean output to file
ai --quiet generate.md > output.txt

# Pipe to another command
ai -q analyze.md | jq '.results'

# CI/CD pipeline
ai --skip --quiet test-runner.md | tee results.txt

​
Input Positioning

​
--stdin-position
flag
Control where piped content goes - Prepend or append stdin to file content
cat data.json | ai task.md --stdin-position prepend
cat data.json | ai task.md --stdin-position append
Values:
  • prepend (default) - Piped content comes before file content
  • append - Piped content comes after file content
Default behavior (prepend):
cat data.json | ai analyze.md
# AI sees:
# The following input was provided via stdin:
# ---
# {json data}
# ---
#
# {content of analyze.md}
Append behavior:
cat data.json | ai analyze.md --stdin-position append
# AI sees:
# {content of analyze.md}
#
# ---
# The following input was provided via stdin:
# ---
# {json data}
Use prepend for:
  • Data-first workflows (“here’s the data, now analyze it”)
  • Piping logs/metrics to analysis scripts
Use append for:
  • Context-first workflows (“here’s the task, here’s the data”)
  • Scripts where instructions come first

​
Output Format

​
--output-format
flag
Claude Code native: Control output format
ai --output-format text task.md
ai --output-format json task.md
ai --output-format stream-json task.md
Values:
  • text (default) - Plain text output
  • json - Complete JSON response at end
  • stream-json - Streaming JSON (used by --live)
Note: --live automatically sets stream-jsonExamples:
# Get JSON output
ai --output-format json query.md | jq '.response'

# Explicit streaming (--live is easier)
ai --output-format stream-json --verbose task.md
​
--verbose
flag
Claude Code native: Show detailed execution information
ai --verbose task.md
ai --aws --verbose debug.md
What it does:
  • Shows detailed internal operations
  • Displays API requests/responses
  • Useful for debugging issues
Automatically enabled by:
  • --live flag
  • --output-format stream-json

​
Examples

​
Real-Time Streaming

# Stream output to console
ai --live task.md

# Stream with file output (status to console, content to file)
ai --live report.md > output.txt

# Stream with clean stdout (no status)
ai --live --quiet script.md > clean-output.txt
Shebang for streaming: 
#!/usr/bin/env -S ai --live --skip
Generate a comprehensive report.
Print updates as you progress through each section.

​
CI/CD Clean Output

# Suppress all status messages
ai --quiet generate-config.md > config.json
ai -q build-report.md | tee report.txt

# Pipeline usage
ai --skip --quiet test-runner.md | jq '.results.failed'
GitHub Actions: 
steps:
  - name: Generate docs
    run: |
      ai --skip --quiet generate-docs.md > docs/api.md

​
Unix Pipelines

# Pipe data in, prepend (default)
cat data.json | ai analyze.md

# Pipe data in, append
cat metrics.log | ai summarize.md --stdin-position append

# Chain scripts
cat input.txt | ./process.md | ./format.md > final.txt

# Git history analysis
git log --oneline -20 | ai --live summarize-changes.md

​
Debugging

# Verbose output for debugging
ai --verbose --aws debug-connection.md

# Live streaming with full visibility
ai --live --verbose trace-execution.md

​
Report Generation

#!/usr/bin/env -S ai --live
Generate a detailed security audit report.

For each file you analyze, print:
- "Analyzing: {filename}"
- Brief summary of findings

At the end, print the full report in markdown format.

chmod +x audit.md
./audit.md > audit-report.md
# Console shows progress, file gets clean markdown

​
Dual Output Streams

# Live narration goes to stderr (console)
# Clean output goes to stdout (file)
ai --live report.md > clean-report.txt

# Redirect both separately
ai --live script.md > output.txt 2> progress.log

# Keep narration, discard output
ai --live task.md > /dev/null

​
Live Streaming Details

When you use --live:
  1. Status messages → stderr (your console)
  2. Clean output → stdout (files, pipes)
  3. Real-time display → word-by-word as generated
  4. Requires jq → install with brew install jq
Example output: 
$ ai --live task.md > output.txt

Using: Claude Code + AWS Bedrock
Model: claude-opus-4-6-v1:0

[Streaming]
Analyzing codebase structure...
Found 47 source files...
Generating architecture diagram...
Writing summary...

Complete!

$ cat output.txt
# Codebase Architecture

[clean markdown output only]

​
Combining Flags

# Streaming + permissions + provider
ai --aws --opus --live --skip report.md > output.txt

# Quiet + permissions + CI/CD
ai --skip --quiet generate.md | jq '.config'

# Live + quiet (disables live status, keeps streaming)
ai --live --quiet task.md  # Equivalent to just streaming output

# Verbose + live (double verbose, for debugging)
ai --live --verbose debug.md

​
Stream Processing

​
Extract JSON Fields

ai --output-format json query.md | jq '.response.text'

​
Parse Streaming Output

ai --live script.md 2>&1 | grep "^\[" | tee status.log

​
Split Streams

# Output to file, status to console
ai --live task.md > output.txt

# Both to separate files
ai --live task.md > output.txt 2> status.log

# Status only
ai --live task.md > /dev/null

​
Troubleshooting

Install jq for JSON streaming:
# macOS
brew install jq

# Ubuntu/Debian
sudo apt install jq

# Verify
jq --version
Status messages go to stdout by default. Use --quiet or redirect stderr:
# Suppress status
ai --quiet task.md > output.txt

# Or redirect streams separately
ai task.md > output.txt 2> status.log
Make sure you’re using the AI Runner wrapper, not calling Claude Code directly:
# ✅ Correct
ai --live task.md

# ❌ Won't stream properly
claude -p "$(cat task.md)" --output-format stream-json
Use --stdin-position to control placement:
# Context first, then data
cat data.json | ai task.md --stdin-position append

Permission Flags

Control file access and execution

Scripting Guide

Full automation guide with examples