pp-nasa-images

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/media-and-entertainment/nasa-images/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# NASA Image and Video Library — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `nasa-images-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install nasa-images --cli-only
   ```
2. Verify: `nasa-images-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/nasa-images/cmd/nasa-images-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Reach for this CLI when an agent or workflow needs deterministic access to NASA's public-domain media archive — image search, asset rendition picking, caption extraction, bulk album archiving — without parsing prose. The local SQLite mirror makes repeat queries free and unlocks chronological/topic-timeline analyses the upstream API doesn't support. The MCP surface gives Claude agents typed tools for every endpoint plus the novel composed commands (assets best, captions fetch text, citation, etc.).

## When Not to Use This CLI

Do not activate this CLI for requests that require creating, updating, deleting, publishing, commenting, upvoting, inviting, ordering, sending messages, booking, purchasing, or changing remote state. This printed CLI exposes read-only commands for inspection, export, sync, and analysis.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Local state that compounds
- **`download album`** — Bulk-download every asset in a curated NASA album with byte-range resume — re-runs pick up exactly where the last failed transfer left off.

  _When you need 200 NASA images for a deck or archive, this is the one command that finishes — flaky wifi, sleep-resume, mid-run cancellation all become non-events._

  ```bash
  nasa-images-pp-cli download album Apollo-at-50 --variant orig --resume --out ./apollo
  ```
- **`recent`** — FTS5 search over the synced local mirror (title, description, description_508, keywords, album), with chronological sort the upstream API doesn't expose.

  _When breaking news hits, you can pull the most recent NASA images on a topic in milliseconds — without paging through decades of archival results._

  ```bash
  nasa-images-pp-cli recent --q "perseverance" --sort date-desc --limit 20 --json
  ```
- **`center profile`** — Local aggregation over the synced cache: counts by media_type, year-bucket histogram, top keywords, and top photographers for one of the 11 NASA centers.

  _Journalists answer 'which center publishes this kind of image' before they search — saving search time on stories where a center is the obvious source._

  ```bash
  nasa-images-pp-cli center profile JPL --json
  ```
- **`unused-in`** — Lists nasa_ids in a curated album that haven't been downloaded yet locally — anti-join against the downloads ledger.

  _Plan next week's slides without picking the same image twice — without keeping a manual list of nasa_ids you've already used._

  ```bash
  nasa-images-pp-cli unused-in Apollo-at-50 --json
  ```
- **`timeline`** — Local GROUP BY strftime('%Y-%m', date_created) over FTS-matched rows; prints month-bucket counts showing when a topic got coverage.

  _Spot publishing patterns — quiet months, new-release bursts — that surface story angles a keyword search hides._

  ```bash
  nasa-images-pp-cli timeline --q "perseverance" --bucket month --json
  ```

### API indirections we follow for you
- **`captions fetch`** — Returns the captions file CONTENT (.srt or .vtt), not just the URL — with an optional `--format text` mode that strips cue numbers and timecodes for readable transcripts.

  _Agents pulling NASA video captions for analysis, search, or quote-finding skip an extra HTTP call and a parse step._

  ```bash
  nasa-images-pp-cli captions fetch jsc2022m000123 --format text --agent
  ```
- **`metadata fetch`** — Follows the /metadata/{id} indirection, fetches the metadata.json sidecar, flattens AVAIL:* and EXIF fields, and drops internal-path leak fields (SourceFile, File:Directory, AVAIL:Owner).

  _Journalists and educators get the bylined photo credit (photographer + center + date) without scrubbing noise fields by hand._

  ```bash
  nasa-images-pp-cli metadata fetch PIA24439 --json --select AVAIL:Title,AVAIL:Photographer,AVAIL:DateCreated
  ```

### Agent-native plumbing
- **`assets best`** — Parses an asset's rendition manifest, classifies each file by variant (orig/large/medium/small/thumb), applies a caller preference order with optional byte ceiling, and prints exactly one URL.

  _Claude agents in MCP can ask for 'the best version of nasa_id X under 5 MB' and get exactly one URL — no token spend on parsing filenames._

  ```bash
  nasa-images-pp-cli assets best as11-40-5874 --prefer orig,large,medium --max-bytes 5000000
  ```

### Domain-specific shortcuts
- **`citation`** — Generates a ready-to-paste citation string (APA / MLA / Chicago) from cached metadata (photographer, date, center, nasa_id, URL).

  _Drop a NASA image in a piece and paste the citation underneath — no formatting by hand._

  ```bash
  nasa-images-pp-cli citation PIA24439 --style apa
  ```

## Command Reference

**albums** — Retrieve the contents of a curated NASA album (e.g. Apollo-at-50, Mars-Perseverance)

- `nasa-images-pp-cli albums <album_name>` — Return paginated asset listing for a curated album. Album names are case-sensitive (Apollo-at-50 works, apollo-at-50...

**assets** — Retrieve the rendition manifest for an asset (every file URL: original/large/medium/small/thumb for images; mp4 variants for video; mp3/m4a for audio)

- `nasa-images-pp-cli assets <nasa_id>` — Return the list of every file URL for an asset

**captions** — Retrieve the location URL of a video asset's captions file (.srt or .vtt)

- `nasa-images-pp-cli captions <nasa_id>` — Return the location URL of the captions file. Video assets only — 400 for images, 404 for video without captions....

**media** — Search the NASA Image and Video Library catalog by free text and filters

- `nasa-images-pp-cli media` — Search the catalog by free text or filters. At least one query parameter is required.

**metadata** — Retrieve the location URL of an asset's metadata.json sidecar (AVAIL editorial + ExifTool fields)

- `nasa-images-pp-cli metadata <nasa_id>` — Return the location URL of the metadata.json sidecar for an asset. Use `metadata fetch` (novel command) to follow...


### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
nasa-images-pp-cli which "<capability in your own words>"
```

`which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query.

## Hand-written Extensions

These commands are declared by the spec author and require separate hand-written wiring; th