Catalog data
CLI catalog commands
Search and browse the green coffee catalog from your terminal with a scoped Parchment API key.
Catalog commands are the fastest way to explore the green coffee feed from the terminal with account-linked access. Run purvey auth login to create and store a scoped Parchment API key, or set PARCHMENT_API_KEY or PURVEYORS_API_KEY to supply one explicitly.
The search command supports filters for origin, processing method, price range, flavor notes, stocked-only, and result limits. purvey catalog similar <id> mirrors the account-linked matching workflow exposed by the beta https://api.purveyors.io/v1/catalog/{id}/similar endpoint and uses the same scoped API-key model, including its member or API Origin/Enterprise entitlement requirement. API Green keys receive 403. If the goal is public no-login discovery, use https://purveyors.io/catalog. See the CLI overview for install and login instructions.
Commands
- purvey catalog search: search by origin, processing method, price, flavor, variety, drying method, and more. Requires catalog:read.
- purvey catalog get <id>: fetch a single coffee by catalog ID.
- purvey catalog similar <id>: find coffees similar to a given catalog entry. Requires catalog:read plus a member-owned key or API Origin/Enterprise key.
- purvey catalog stats: aggregate catalog statistics.
purvey catalog search --origin "Ethiopia" --process "natural" --pretty
purvey catalog search --variety "Heirloom" --stocked --pretty
purvey catalog search --drying-method "raised bed" --stocked --limit 20
purvey catalog search --stocked-days 30 --sort newest --pretty
purvey catalog search --ids "1182,1183,1200" --pretty
purvey catalog similar 1182 --threshold 0.85 --stocked-only --prettySimilar matching
- purvey catalog similar <id> finds beta similar-coffee candidates for one catalog ID. Treat results as leads for comparison, not canonical identity claims.
- --threshold sets the minimum similarity score. The HTTP beta endpoint accepts 0.5 through 0.99 and defaults to 0.7.
- --stocked-only limits matches to currently stocked coffees. The HTTP endpoint defaults stocked_only to true.
- When an integration needs API-key access, rate-limit headers, or explicit beta response metadata, call GET https://api.purveyors.io/v1/catalog/{id}/similar directly.
Search filters
- --origin <text>: partial match across country, continent, and region fields.
- --process <text>: partial match on processing method (e.g. washed, natural).
- --flavor <text>: partial match on flavor notes (comma-separated for multiple).
- --variety <text>: filter by coffee variety or cultivar (partial match).
- --drying-method <text>: filter by drying method (partial match, e.g. raised bed, patio).
- --name <text>: filter by coffee name (partial match, case-insensitive).
- --supplier <name>: filter by supplier or source name (partial match, case-insensitive).
- --stocked: only show currently available coffees.
- --stocked-days <n>: only show coffees stocked within the last N days.
- --price-min <n> / --price-max <n>: filter by price per pound range.
- --ids <n,n,...>: fetch specific catalog IDs (comma-separated; ignores --limit).
- --sort <price|price-desc|name|origin|newest>: sort results.
- --offset <n>: skip N results for pagination.
- --limit <n>: maximum results returned (default: 10).
Output formats
- --pretty: formatted output for terminal reading.
- --csv: comma-separated output for spreadsheets and data pipelines.
- --origin accepts partial matches across country, continent, and region fields.