Piping & Output

Compose ai-cli with other commands using stdin and stdout.

Stdin

Most commands accept input via stdin. The behavior depends on the command type:

Text

Stdin is read as text and combined with the prompt argument:

bash

cat notes.txt | ai text "summarize this"
git diff | ai text "explain these changes"
cat src/auth.ts | ai text "review for security issues"

If both stdin and a prompt argument are provided, they're joined with a --- separator:

<stdin content>

---

<prompt argument>

If only stdin is provided, it becomes the full prompt.

Image

Stdin is read as binary image data for image-to-image generation:

bash

cat photo.png | ai image "make it a watercolor painting"

Video

Stdin is read as binary image data for image-to-video generation:

bash

ai image "a dragon" | ai video "animate this"
cat scene.png | ai video "zoom out slowly"

Audio

audio speak reads stdin as text. audio transcribe reads stdin as binary audio:

bash

echo "Ship the changelog" | ai audio speak -o changelog.mp3
cat recording.mp3 | ai audio transcribe -o transcript.txt

Stdout

Output behavior changes based on whether stdout is a TTY (interactive terminal) or a pipe:

Interactive (TTY)

Saves to a file and prints the path to stderr:

bash

ai text "hello"         # → saves <id>.md, prints "Saved to /path/<id>.md"
ai image "a cat"        # → saves <id>.png
ai video "ocean"        # → saves <id>.mp4
ai audio speak "hello"  # → saves <id>.mp3

Piped (non-TTY)

Writes raw output directly to stdout for composability:

bash

ai text "hello" | pbcopy                    # copy to clipboard
ai image "a dragon" | ai video "animate"    # chain image → video
ai text "hello" > response.md              # redirect to file
ai audio speak "hello" > speech.mp3        # redirect audio bytes

Output path

Control where files are saved with -o:

bash

ai image "a sunset" -o sunset.png          # specific file
ai image "a sunset" -o ./renders/          # directory (auto-names files)
ai audio transcribe call.mp3 -o call.txt   # transcript file

When -o points to a directory, files use response IDs when available and random 8-character names otherwise.

The AI_CLI_OUTPUT_DIR environment variable sets a default output directory:

bash

export AI_CLI_OUTPUT_DIR=~/ai-output
ai image "a sunset"    # → saves to ~/ai-output/<id>.png

JSON metadata

Use --json to get structured metadata on stdout instead of raw output:

bash

ai image "a sunset" --json

json

{
  "elapsed_ms": 3420,
  "count": 1,
  "results": [
    {
      "index": 1,
      "model": "openai/gpt-image-2",
      "elapsed_ms": 3420,
      "success": true,
      "file": "/Users/you/resp_abc123.png"
    }
  ]
}