Managing Outputs

The CLI stores a local history of your runs. Use the betterprompt outputs commands to retrieve results and review past generations.

Fetch a run's output

Retrieve the output of a specific run by its ID:

betterprompt outputs <run-id>

Flag	Description
--sync	Fetch outputs from the remote API and update local state.
--remote	Fetch from remote without updating local cache.
--json	Machine-readable JSON output.

# Read from local history
betterprompt outputs 01234567-89ab-cdef-0123-456789abcdef

# Sync from remote (useful if the run finished after a timeout)
betterprompt outputs 01234567-89ab-cdef-0123-456789abcdef --sync

List recent runs

betterprompt outputs list [flags]

Flag	Description
--remote	List runs from the remote API.
--status <status>	Filter: queued, running, succeeded, or failed.
--limit <n>	Maximum number of runs to return.
--since <date>	Only runs created on or after this date (ISO 8601 or unix ms).
--json	Machine-readable JSON output.

betterprompt outputs list --limit 20
betterprompt outputs list --status succeeded --since 2026-03-01
betterprompt outputs list --remote --json

Where outputs are stored

Outputs are saved in the outputs/ directory within your BetterPrompt state directory:

outputs/
├── history.jsonl          # Append-only index for fast listing
└── <runId>/
    ├── request.json       # Original request payload
    ├── response.json      # API response
    ├── metadata.json      # Run metadata
    └── assets/            # Downloaded images/videos
        ├── hero.png
        └── alt-1.png

The location depends on scope — ~/.betterprompt/outputs/ for global, .betterprompt/outputs/ for project-local. See Configuration for details.