Piping & Output

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

Stdin

All generation 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"

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 output.md, prints "Saved to /path/output.md"
ai image "a cat"        # → saves output.png
ai video "ocean"        # → saves output.mp4

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

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)

When -o points to a directory, files are named output.png, output-2.png, etc.

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/output.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/output.png"
    }
  ]
}