list-outputs

name	list-outputs
description	Lists saved output ARTEFACTS (files, images, audio, transcripts) from past Pixie tool RUNS, optionally filtered by tool. Use when the user asks to list, show, or browse saved OUTPUTS or ARTEFACTS. Do NOT use to list installed tools (list-tools), search by name (find-output), or show one tool's runs (view-runs).
allowed-tools	Bash, Read

List saved Pixie outputs across tools

You are producing a single read-only report of artefacts saved across one or every Pixie tool. Artefacts are real files on disk under artefacts/<tool_id>/<run_id>/<filename> and are also indexed in the artefacts SQLite table. You query Pixie's API and print a markdown table — you do not modify or delete anything.

Routing check (do this first)

• If the user wants to list runs (events, history, what executed and when) rather than the FILES produced, switch to view-runs.
• If the user wants one tool's full schema, dependencies, and secrets, switch to inspect-tool.
• If the user wants to search saved outputs by a name, label, or tag substring, switch to find-output.
• If the user wants the live runtime view (what is warm now), switch to pixie-status.

Pre-flight: read the kill file

Before doing anything that might touch existing patterns, read .build/KILL_FILE.md. Any entry whose Context or Symptom matches your current task -> apply the documented Fix directly, do not re-debug from scratch.

Steps

1. Confirm Pixie is reachable

curl -s http://127.0.0.1:8765/api/healthz

If the response is empty or non-2xx, tell the user Pixie is not running and stop. Do not attempt a database-level fallback in this skill — find-output and open-artefacts-folder are the offline paths.

2. Decide scope

If the user named a tool, scope to that tool. Otherwise scope to every tool.

Optional flags inferred from the user's phrasing:

Flag	Default	Effect
tool_id	unset	Restrict to one tool.
limit	20	Max rows returned. Cap at 200.
starred_only	false	If the user said "starred" / "favourites" / "pinned", set true.
sort	date	Or size if the user said "largest" / "biggest".
order	desc	Or asc if the user said "oldest" / "smallest".

3. Call the artefacts API

curl -s "http://127.0.0.1:8765/api/artefacts?tool_id=<id-or-empty>&limit=<n>&starred_only=<bool>"

The endpoint returns a JSON list of artefact rows: id, run_id, tool_id, output_key, rel_path, filename, mime, size_bytes, sha256, created_at, starred, label, tags.

If the response is [], print a single line — "No saved outputs found." — and stop. If a tool was scoped, suggest running the tool once to produce some.

4. Sort client-side

Re-sort the returned list by the chosen field and order. The API defaults to created_at desc so a simple list usually needs no resort.

5. Format the table

Use sentence-case British English headers. Truncate filenames longer than 32 chars with an ellipsis. Format sizes with MB up to 1024 MB then GB, one decimal. Format created_at as YYYY-MM-DD HH:MM (UTC, as returned). Star column shows ★ if starred else blank.

Created	Tool	Run	File	MIME	Size	Star	Label

The Run column shows the run_id truncated to the first 8 characters.

6. Print a summary line

Below the table:

"<N> artefact(s) shown, total <size> — across <M> run(s) in <K> tool(s)."

If starred_only=true, append: "(filtered to starred runs)".

If the returned list was capped by limit, append: "Increase limit to see more — there may be older artefacts."

7. Suggest next steps

If the table is non-empty, print one line:

"Use find-output to search by name or label, copy-output-to to copy a file to disk, or open-artefacts-folder to browse the folder directly."

8. Do NOT run the validator

This skill is read-only and does not modify any tool.

On failure: append to the kill file

If you encounter an error NOT already in .build/KILL_FILE.md, append a new entry with the next KILL-NNNN id following the schema. Be terse -- root cause + one-line fix + one-line rule.

Refusal templates

Pixie is not running, so I cannot query the artefacts API. Either start Pixie
(`uv run pixie`) or use `open-artefacts-folder` to browse the artefacts directory
directly on disk.

Do NOT

• Do NOT delete, move, rename, or modify any artefact file or row.
• Do NOT download or copy artefact contents in this skill — use copy-output-to.
• Do NOT include artefact SHA-256 hashes in the table — they are noise for a listing.
• Do NOT bind to 0.0.0.0 or any non-loopback interface.
• Do NOT run the Pixie validator.
• Do NOT invoke other Pixie skills programmatically — name them and stop.