Catalog data
CLI catalog commands
Search and browse the green coffee catalog from your terminal with an authenticated viewer session.
Catalog commands are the fastest way to explore the green coffee feed from the terminal when the workflow is tied to a signed-in account. They require an authenticated viewer session; run purvey auth login before using them.
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 /v1/catalog/{id}/similar endpoint, but the CLI uses viewer-session auth instead of API keys. If the goal is anonymous discovery or API-key integration, use the HTTP API instead. 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 authentication.
- purvey catalog get <id>: fetch a single coffee by catalog ID.
- purvey catalog similar <id>: find coffees similar to a given catalog entry.
- 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 /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.