Pp Numista

<!-- 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:

   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.6 or newer):

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.

  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.

  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.

  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.

  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.

  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.

  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.

  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.

  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.

  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.

  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:

numista-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.

Recipes

Identify a coin from a fuzzy description

numista-pp-cli types search --q 'Australia 3 pence George VI' --json --select types.id,types.title,types.min_year,types.max_year

Narrow with --select to keep the payload tight; the dotted-path projection turns ~50 lines of JSON per result into 4.

See what a coin is worth in every grade

numista-pp-cli types series 11013 --json

One command pulls every year + every grade's price into the local store; subsequent reads are free.

Estimate this month's batch cost before running it

numista-pp-cli types batch --file ./watchlist.csv --dry-run --json

--dry-run forecasts live calls vs cache hits vs %-of-quota; never spends a call.

Refresh only stale prices in your cache

numista-pp-cli refresh --all --older 30d --json

Re-fetches only types whose prices are older than 30 days; never touches identity fields.

Total my collection's value right now

numista-pp-cli collection value 12345 --json --select totals.estimated_value,totals.currency,items.id,items.grade,items.estimated_value

Joins your locally-cached collection against the prices table; refuses to start if remaining quota would be exceeded.