pp-numista

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/other/numista/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/". -->

# Numista — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `numista-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 numista --cli-only
   ```
2. Verify: `numista-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/other/numista/cmd/numista-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 numista-pp-cli when you have a Numista API key and need quota-aware automation over the catalogue and your collection. Ideal for: bulk-importing a collection from another tracker, running scheduled price refreshes on watched coins, computing a current valuation of an entire collection, or pulling a full series (every year, every grade) for one type into a local store for analysis. Skip it when one ad-hoc lookup is all you need — the Numista web UI is fine for that.

## Unique Capabilities

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

### Quota economics
- **`--quota`** — Print the current month's used/remaining/reset Numista quota and exit, with zero API calls.

  _Reach for this before any batch or crawl to know whether the operation fits today's budget — zero quota cost._

  ```bash
  numista-pp-cli --quota --json
  ```
- **`audit`** — Query the local lookup_log directly to see every API call, its endpoint, duration, and cache-hit status — aggregated by day, endpoint, or type ID.

  _Use this to diagnose unexpected quota consumption, find duplicate lookups worth caching, or audit which endpoints power which workflows._

  ```bash
  numista-pp-cli audit --by-endpoint --json
  ```
- **`types batch`** — Parse a CSV / JSONL / text list of Numista type IDs (N# numbers) and look up each one against the API — with cache reuse, --dry-run cost forecast, and --resumable splitting across UTC months.

  _Use any time you have more than one type ID to look up. Dry-run is always cheap; resumable is essential for >2K-item lists._

  ```bash
  numista-pp-cli types batch --file ./type-ids.csv --dry-run --json
  ```

### Local state that compounds
- **`types series`** — For one type (e.g., N#11013 — Australia 3 pence George VI), pull every year-of-issue, every issue's prices across all grades, and persist the full price/mintage curve to the local store — then print the scarcity and price-evolution table.

  _Reach for this when a user wants the full picture of one coin type — every year it was struck, every grade's current value — in one command instead of dozens of individual calls._

  ```bash
  numista-pp-cli types series 11013 --json --select issues.year,issues.mintage,prices.grade,prices.price
  ```
- **`collection value`** — Sum the current estimated value of every item in a user's Numista collection, fetching missing prices on demand, and emit a per-item breakdown sorted by value.

  _Use to answer 'what is my collection worth right now?' without scrolling through Numista's web UI. Refuses to start when remaining quota is less than the number of items needing fresh prices._

  ```bash
  numista-pp-cli collection value 12345 --json
  ```
- **`refresh`** — Refresh cached types by re-fetching only fields that actually change (prices, mintage) while leaving cataloger-set identity fields untouched. --dry-run --older 30d lists what needs refresh without spending a call.

  _Use weekly or monthly to keep cached prices current without re-pulling the entire catalogue. --dry-run --older makes the cost predictable._

  ```bash
  numista-pp-cli refresh --all --older 30d --json
  ```
- **`crawl issuer`** — Crawl every type from one issuer (e.g., 'australia') matching a year range, persist to local store, and print a summary table. Forecasts call cost as %-of-monthly-quota and requires confirmation before crawling.

  _Reach for this when starting research on an issuer or period — pay the call cost once, then ask the local store any question for free._

  ```bash
  numista-pp-cli crawl issuer australia_section --years 1900-1950 --dry-run
  ```
- **`watchlist`** — Track price changes for a set of types over time. `watchlist add N#` registers a type; `watchlist check` refreshes prices, snapshots them to the prices table with a timestamp, and prints the diff since the last snapshot.

  _Run on a cron after adding a few types; the CLI surfaces material price moves without polluting your inbox._

  ```bash
  numista-pp-cli watchlist check --json
  ```

### Agent-native plumbing
- **`users collected-items add --from-file`** — Import a list of new collected items from CSV / JSONL with --dry-run cost forecast. Idempotent on (user_id, type_id, issue_id, grade) so re-running the same file is safe.

  _Use to migrate a collection from another tracker, or to bulk-add a haul from a coin show without dozens of UI clicks._

  ```bash
  numista-pp-cli users collected-items add 12345 --from-file imports.csv --dry-run
  ```
- **`users collections hydrate`** — Given a collection-folder-id, fan out get-item for every item, optionally fan out get-prices, and persist everything to the local store. Refuses to start when remaining quota is less than the item count.

  _Use once after `auth set-token` (with an OAuth bearer) to populate the local store with everything in your collection — then most subsequent reads are quota-free._

  ```bash
  numista-pp-cli users collections hydrate 12345 --with-prices --json
  ```

## Command Reference

**catalogues** — The API endpoints in this section allow to access the data of the Numista catalogue of coins, banknotes and exonumia.

- `numista-pp-cli catalogues` — Retrieve the list of all the reference catalogues used for cross-reference in the catalogue

**issuers** — Manage issuers

- `numista-pp-cli issuers` — Retrieve the details about all the issuing countries and territories

**mints** — Manage mints

- `numista-pp-cli mints get` — Retrieve the details about all the mints
- `numista-pp-cli mints get-mintid` — Retrieve the details about a specific mint.

**oauth-token** — Manage oauth token

- `numista-pp-cli oauth-token` — In order to access the data of a Numista user, you will need to authenticate using the OAuth 2.0 protocol. See the...

**publications** — Manage publications

- `numista-pp-cli publications <id>` — Retrieve the details about a specific item in the literature catalogue.

**types** — Manage types

- `numista-pp-cli types get` — Retrieve the details about a specific type in the catalogue.
- `numista-pp-cli types search` — Search the catalogue for coin, banknote, and exonumia types. At least one of the following parameters should be...

**users** — The API endpoints in this section allow to access data about the Numista users and their collection.

- `numista-pp-cli users <user_id>` — Get details about a user


### Finding the right command

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

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

`whic