---
title: "Piping & Output"
description: "Compose ai-cli with other commands using stdin and stdout."
canonical_url: "https://ai-cli.dev/docs/single"
---
# Piping & Output

## 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"
    }
  ]
}
```

> **Tip**:
>
> The `--json` flag is useful for scripts and CI pipelines that need to know where files were saved and whether generation succeeded.