pp-numista

name	pp-numista
description	Every Numista catalogue and collection feature, with offline FTS5 search and a monthly-quota tracker no Numista SDK has. Trigger phrases: `look up a coin on numista`, `what is my coin collection worth`, `track numista prices`, `check my numista quota`, `import my coins into numista`, `browse numista series`, `use numista-pp-cli`, `run numista-pp-cli`.
author	Vinny Pasceri
license	Apache-2.0
argument-hint	<command> [args] | install cli|mcp
allowed-tools	Read Bash
metadata	{"openclaw":{"requires":{"bins":["numista-pp-cli"]}}}

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:

   npx -y @mvanhorn/printing-press-library install numista --cli-only
   

2. Verify: numista-pp-cli --version
3. Ensure $GOPATH/bin (or $HOME/go/bin) is on $PATH.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 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 install step did not put the binary 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.

If your input is a PCGS cert

Pair with pcgs-pp-cli when you're starting from a PCGS-graded coin and need its Numista catalogue ID (N#). PCGS is one of Numista's reference catalogues — registered as catalogue id 1856 (code PCGS, title "PCGS CoinFacts") — so a PCGSNo resolves to an N# in one API call with no text-match guessing.

Direct cross-walk (recommended when you have a PCGSNo).

# 1. Get the PCGSNo from PCGS (no Numista quota cost).
pcgs-pp-cli coin facts-cert <cert-number> --json --select PCGSNo,Name,Year
# → e.g. {"PCGSNo":"7130","Name":"1881-S Morgan Dollar","Year":"1881"}

# 2. Look up the Numista N# directly via the catalogue cross-reference.
numista-pp-cli types search --catalogue 1856 --number 7130 \
  --agent --select types.id,types.title
# → {"results":{"types":[{"id":1492,"title":"1 Dollar \"Morgan Dollar\""}]}}

Verify the catalogue id at any time with numista-pp-cli catalogues find pcgs (local-only, no quota cost; requires that numista-pp-cli catalogues has been run at least once to populate the local cache).

Text-search fallback (no PCGSNo, or the catalogue lookup misses). The PCGS CoinFacts reference catalogue doesn't index every cert. When --catalogue 1856 --number <PCGSNo> returns no types, fall back to text search:

pcgs-pp-cli coin facts-cert <cert-number> --json --select Name,Year,CountryName
# → e.g. {"Name":"1881-S Morgan Dollar","Year":"1881","CountryName":"United States"}

numista-pp-cli types search --q "morgan dollar" --issuer united-states --date 1881 \
  --agent --select types.id,types.title
# → top result is usually the Numista N# you want.

Use --date (Gregorian calendar year) for the year PCGS returns, not --year — Numista's --year is the year as written on the item (relevant for Hijri / Republican / other non-Gregorian dating on world coins; for US coins they coincide).

Tips:

• Issuer slugs are hyphenated (united-states, south-africa). Run numista-pp-cli issuers find <name> to look one up — local-only, no quota cost.
• This CLI does NOT depend on pcgs-pp-cli. No shell-out, no auto-detection — install it separately when you want grade / cert / population data on the coin Numista returned.

Auth Setup

Set NUMISTA_API_KEY in your environment (request one at https://en.numista.com/api/index.php — the free plan is 2000 calls/month). Catalogue and reference endpoints work with the API key alone. User-collection commands (users collected-items add, collection value, users collections hydrate) need an OAuth token — request an OAuth bearer with numista-pp-cli oauth-token --grant-type client_credentials --scope view_collection and save it via numista-pp-cli auth set-token <token> to grant the CLI access to your own account; the token is stored at ~/.numista-pp-cli/auth.json (mode 0600).

Run numista-pp-cli doctor to verify setup.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.

• Pipeable — JSON on stdout, errors on stderr

• Filterable — --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:

  numista-pp-cli catalogues --agent --select id,name,status
  

• Previewable — --dry-run shows the request without sending

• Offline-friendly — sync/search commands can use the local SQLite store when available

• Non-interactive — never prompts, every input is a flag

• Explicit retries — use --idempotent only when an already-existing create should count as success, and --ignore-missing only when a missing delete target should count as success

Response envelope

Commands that read from the local store or the API wrap output in a provenance envelope:

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal AND no machine-format flag (--json, --csv, --compact, --quiet, --plain, --select) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout.

Agent Feedback

When you (or the agent) notice something off about this CLI, record it:

numista-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
numista-pp-cli feedback --stdin < notes.txt
numista-pp-cli feedback list --json --limit 10

Entries are stored locally at ~/.numista-pp-cli/feedback.jsonl. They are never POSTed unless NUMISTA_FEEDBACK_ENDPOINT is set AND either --send is passed or NUMISTA_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

Output Delivery

Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Sink	Effect
stdout	Default; write to stdout only
file:<path>	Atomically write output to <path> (tmp + rename)
webhook:<url>	POST the output body to the URL (application/json or application/x-ndjson when --compact)

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

Named Profiles

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.

numista-pp-cli profile save briefing --json
numista-pp-cli --profile briefing catalogues
numista-pp-cli profile list --json
numista-pp-cli profile show briefing
numista-pp-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.

Exit Codes

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Resource not found
4	Authentication required
5	API error (upstream issue)
7	Rate limited (wait and retry)
10	Config error

Argument Parsing

Parse $ARGUMENTS:

1. Empty, help, or --help → show numista-pp-cli --help output
2. Starts with install → ends with mcp → MCP installation; otherwise → see Prerequisites above
3. Anything else → Direct Use (execute as CLI command with --agent)

MCP Server Installation

Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:

claude mcp add numista-pp-mcp -- numista-pp-mcp

Verify: claude mcp list

Direct Use

1. Check if installed: which numista-pp-cli If not found, offer to install (see Prerequisites at the top of this skill).
2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
3. Execute with the --agent flag:

   numista-pp-cli <command> [subcommand] [args] --agent
   

4. If ambiguous, drill into subcommand help: numista-pp-cli <command> --help.