# Catalog commands

> Search, rank, and compare catalog coffees and suppliers, and find similar coffees.

HTML version: https://www.purveyors.io/docs/cli/catalog

Search the normalized green coffee catalog, rank candidates, compare suppliers, and find similar coffees from your terminal. For no-login browsing, use the web catalog at https://purveyors.io/catalog.

Access: Viewer. Any signed-in account.

## purvey catalog search

Search coffees by origin, process, price, and catalog metadata.

Usage: `purvey catalog search [options]`

Access: Viewer. Any signed-in account.

- All filters are optional. Without flags, returns up to --limit results.
- Grading filters add a grading object to each coffee: disclosed screen size, labeled grade codes, lab analysis, and cup score with its protocol.
- Each coffee carries a taxonomy object with its standardized variety, species, and drying labels when the supplier text matched the vocabulary. An unknown code is an error; --variety and --drying-method still match by text.
- --ids fetches specific catalog items by ID, ignoring --limit and --offset.
- --offset + --limit enables pagination through large result sets.
- Without --include-proof, the output shape is unchanged.
- PURVEYORS_API_KEY or PARCHMENT_API_KEY overrides the scoped API key stored by `purvey auth login`.

| Argument or flag | Details |
| --- | --- |
| `--origin <origin>` | Only coffees from this origin; matches continent, country, or region names, case-insensitive and partial. |
| `--process <method>` | Only coffees whose processing label contains this text, such as natural or washed (case-insensitive). |
| `--decaf <true\|false>` | true selects decaffeinated coffees; false excludes them. Omit for any coffee. |
| `--processing-base-method <method>` | Only coffees whose structured base process exactly matches this value, such as Natural or Washed. List values with `purvey catalog facets processing_base_method`. |
| `--fermentation-type <type>` | Only coffees whose structured fermentation type exactly matches this value, such as Anaerobic. List values with `purvey catalog facets fermentation_type`. |
| `--process-additive <additive>` | Only coffees whose process discloses exactly this additive, such as hops. |
| `--processing-disclosure-level <level>` | Only coffees whose supplier disclosed process details at exactly this level. |
| `--processing-confidence-min <n>` | Only coffees whose process details were identified with at least this confidence. Range: 0 to 1. |
| `--price-min <n>` | Lowest price per pound to include, in US dollars. |
| `--price-max <n>` | Highest price per pound to include, in US dollars. |
| `--name <text>` | Only coffees whose name contains this text (case-insensitive). |
| `--ids <n,n,...>` | Fetch these catalog IDs, comma-separated, instead of searching; --limit and --offset are ignored. |
| `--variety <text>` | Only coffees whose variety or cultivar contains this text (case-insensitive). |
| `--stocked-days <n>` | Only coffees that came into stock within the last N days. |
| `--supplier <name>` | Only coffees from suppliers whose name contains this text (case-insensitive). |
| `--drying-method <method>` | Only coffees whose drying method or processing text contains this value, such as raised bed (case-insensitive). |
| `--flavor <keywords>` | Comma-separated flavor keywords searched in coffee descriptions and tasting notes; a coffee matches if it mentions any of them. |
| `--stocked` | Only coffees currently in stock; without it, results also include coffees no longer stocked. |
| `--sort <field>` | Sort by price (cheapest first), price-desc, name, or origin (by country); without it, the most recently stocked coffees come first. |
| `--offset <n>` | Number of results to skip when paging; must be a multiple of --limit. Default: 0. |
| `--limit <n>` | Maximum number of coffees to return. Default: 10. Range: 1 to 1000. |
| `--include-proof` | Add a proof summary to each coffee: how well its process, provenance, freshness, and pricing details are supported (strong, partial, limited, or not available). |
| `--elevation-min <masl>` | Lowest growing elevation in meters; coffees whose disclosed range overlaps match. Range: 1 to 6000. |
| `--elevation-max <masl>` | Highest growing elevation in meters. Range: 1 to 6000. |
| `--screen-min <n>` | Smallest disclosed screen size (64ths of an inch); an 18+ lot matches any minimum up to its range. Range: 8 to 20. |
| `--screen-max <n>` | Largest disclosed screen size (64ths of an inch). Range: 8 to 20. |
| `--grade <codes>` | Comma-separated grade codes such as KE:AA,PREP:EP; a coffee matches if it carries any of them. List codes with `purvey catalog grades`. |
| `--grade-kind <kind>` | Only coffees with a grade of this kind: size, altitude, defects, cup, or preparation. |
| `--peaberry` | Only peaberry lots. |
| `--lab-analyzed` | Only coffees with lab values such as moisture, water activity, density, or defect counts. |
| `--moisture-max <pct>` | Highest disclosed moisture percentage; coffees without a moisture reading are excluded. Range: 0 to 20. |
| `--score-protocol <protocol>` | Only cup scores from this protocol: sca_2004, cva_affective, q_arabica, coe, or supplier_unspecified. |
| `--variety-code <codes>` | Comma-separated variety codes such as gesha,bourbon; a coffee matches if it carries any of them, and a family code also matches the codes under it (bourbon matches pink_bourbon). Find codes with `purvey catalog taxonomies`. |
| `--species-code <codes>` | Comma-separated species codes such as arabica or canephora (Robusta); matches coffees whose supplier states the species. |
| `--drying-method-code <codes>` | Comma-separated drying method codes such as raised_bed,patio; raised_bed also matches african_bed. |

Examples:

```bash
purvey catalog search --decaf true --stocked --pretty
purvey catalog search --decaf false --process "natural" --pretty
purvey catalog search --origin "Ethiopia" --process "natural" --pretty
purvey catalog search --processing-base-method "Natural" --fermentation-type "Anaerobic" --pretty
purvey catalog search --process-additive "hops" --processing-confidence-min 0.8 --pretty
purvey catalog search --variety "gesha" --stocked --pretty
purvey catalog search --stocked-days 30 --pretty
purvey catalog search --supplier "Royal" --flavor "blueberry,jasmine" --stocked --pretty
purvey catalog search --origin "Ethiopia" --include-proof --json
purvey catalog search --grade KE:AA,KE:AB --screen-min 17 --stocked --pretty
purvey catalog search --grade-kind altitude --elevation-min 1600 --pretty
purvey catalog search --variety-code bourbon,gesha --stocked --pretty
```

## purvey catalog get

Get details for a specific coffee by ID.

Usage: `purvey catalog get <id> [options]`

Access: Viewer. Any signed-in account.

| Argument or flag | Details |
| --- | --- |
| `<id>` | Required: Catalog ID of the coffee. |
| `--include-proof` | Add the proof summary: how well the coffee's process, provenance, freshness, and pricing details are supported. |

Examples:

```bash
purvey catalog get 128 --pretty
purvey catalog get 128 --include-proof --json
```

## purvey catalog stats

Aggregate statistics for the catalog.

Usage: `purvey catalog stats`

Access: Viewer. Any signed-in account.

Examples:

```bash
purvey catalog stats --pretty
```

## purvey catalog facets

List counted catalog facet values for filter discovery.

Usage: `purvey catalog facets [field] [options]`

Access: Viewer. Any signed-in account.

- Without a field, prints every facet except the grading and code facets, with its counted values and meta (values, facets, meta); name one of those fields to get its counts.
- Code facets (varieties, species_codes, drying_methods) roll up: a family counts every coffee carrying it or any code under it, once.
- With a field, prints { field, facet, data, meta }: that facet's counted values and meta.
- Counts for multi-valued dimensions can overlap, so do not sum them.
- Defaults to currently stocked coffees; use --all for every coffee you can see.

| Argument or flag | Details |
| --- | --- |
| `[field]` | Optional: The facet to list: supplier, country, decaf, processing_base_method, fermentation_type, drying_method, wholesale, grade_size, grade_altitude, grade_defects, grade_cup, grade_preparation, screen_size_min, elevation_band, varieties, species_codes, or drying_methods. Without it, every facet except the grading and code facets is listed. |
| `--decaf <true\|false>` | Count only decaffeinated coffees (true) or coffees that are not decaffeinated (false). Omit for any coffee. |
| `--all` | Count every coffee you can see, including ones no longer stocked; without it, only coffees currently in stock are counted. |

Examples:

```bash
purvey catalog facets decaf --pretty
purvey catalog facets country --decaf true --pretty
purvey catalog facets supplier --pretty
purvey catalog facets country --all --json
purvey catalog facets --pretty
purvey catalog facets grade_altitude --pretty
purvey catalog facets varieties --pretty
```

## purvey catalog rank

Rank catalog coffees for a goal: premium, value, fresh arrivals, or rare origins.

Usage: `purvey catalog rank [options]`

Access: Viewer. Any signed-in account.

- Objectives are premium, value, fresh_arrival, and rare_origin.
- Uses the Purveyor Score as the quality signal.
- Output metadata reports stocked_only/scope, sample scope, and truncation; rare_origin is rarity within sampled matching candidates.

| Argument or flag | Details |
| --- | --- |
| `--objective <objective>` | What to rank for: premium (highest Purveyor Score), value (score per dollar), fresh_arrival (newest arrivals), or rare_origin (least common origins in the sample). Default: premium. |
| `--supplier <name>` | Only coffees from suppliers whose name contains this text. |
| `--country <country>` | Only coffees from this country. |
| `--process <method>` | Only coffees with this processing method, such as washed or natural. |
| `--stocked` | Only coffees currently in stock; this is already the default unless you pass --all. |
| `--all` | Rank every coffee you can see, including ones no longer stocked, instead of only coffees in stock. |
| `--price-max <n>` | Highest price per pound to include, in US dollars. |
| `--min-score <n>` | Lowest Purveyor Score to include. |
| `--non-wholesale-only` | Leave out wholesale listings, keeping retail and listings with unknown wholesale status, before sampling. |
| `--sample-size <n>` | Number of matching coffees to consider before ranking; a smaller sample is faster but may miss candidates. Default: 5000. Range: 1 to 5000. |
| `--limit <n>` | Maximum number of ranked coffees to return. Default: 10. Range: 1 to 50. |

Examples:

```bash
purvey catalog rank --objective premium --stocked --pretty
purvey catalog rank --objective value --country Ethiopia --price-max 12 --json
purvey catalog rank --objective premium --supplier "Royal Coffee" --limit 5 --json
```

## purvey catalog rank-premium

Rank premium catalog candidates by Purveyor Score.

Usage: `purvey catalog rank-premium [options]`

Access: Viewer. Any signed-in account.

- Shows the Purveyor Score with its confidence, tier, factor breakdown, version, and update metadata.
- Output includes rank, catalog context, pricing, stocked status, Purveyor Score qualifiers, and transparent ranking signals for agents.
- Output metadata reports sample ordering and whether more rows matched than the requested sample size.

| Argument or flag | Details |
| --- | --- |
| `--origin <origin>` | Only coffees from this continent, country, or region (case-insensitive). |
| `--process <method>` | Only coffees with this processing method, such as washed or natural. |
| `--stocked` | Only coffees currently in stock; without it, coffees no longer stocked are ranked too. |
| `--price-max <n>` | Highest price per pound to include, in US dollars. |
| `--min-score <n>` | Lowest Purveyor Score to include. |
| `--include-unscored` | Also list coffees without a Purveyor Score, after all scored coffees. |
| `--sample-size <n>` | Number of matching coffees to consider before ranking. Default: 250. Range: 1 to 5000. |
| `--limit <n>` | Maximum number of ranked coffees to return. Default: 10. Range: 1 to 50. |

Examples:

```bash
purvey catalog rank-premium --stocked --limit 10 --pretty
purvey catalog rank-premium --origin Ethiopia --min-score 88 --json
```

## purvey catalog supplier-list

Summarize suppliers from the catalog coffees they list.

Usage: `purvey catalog supplier-list [options]`

Access: Viewer. Any signed-in account.

- Summarizes supplier counts, stocked counts, Purveyor Score coverage, average score, average confidence, price range, origin/process coverage, and representative top coffees with score qualifiers.
- Country and non-wholesale filters apply to coffees before suppliers are summarized.
- Output metadata reports source-ordered pagination, rows examined, and whether the aggregate is sample-limited.

| Argument or flag | Details |
| --- | --- |
| `--country <country>` | Only count coffees from this country. |
| `--stocked` | Only count coffees currently in stock; without it, coffees no longer stocked count too. |
| `--non-wholesale-only` | Leave out wholesale listings before suppliers are summarized. |
| `--sample-size <n>` | Number of catalog coffees to read per page before summarizing suppliers. Default: 5000. Range: 1 to 5000. |
| `--limit <n>` | Maximum number of suppliers to return. Default: 25. Range: 1 to 100. |

Examples:

```bash
purvey catalog supplier-list --country Ethiopia --non-wholesale-only --pretty
```

## purvey catalog supplier-detail

Show aggregate detail for a supplier query.

Usage: `purvey catalog supplier-detail <supplier> [options]`

Access: Viewer. Any signed-in account.

- Supplier matching is case-insensitive and partial, mirroring catalog search.
- Output metadata reports source-ordered pagination, rows examined, and whether the aggregate is sample-limited.

| Argument or flag | Details |
| --- | --- |
| `<supplier>` | Required: Supplier name to look up (case-insensitive, partial match). |
| `--country <country>` | Only count coffees from this country. |
| `--stocked` | Only count coffees currently in stock; without it, coffees no longer stocked count too. |
| `--non-wholesale-only` | Leave out wholesale listings before the supplier is summarized. |
| `--top-coffees <n>` | Number of representative top coffees to include. Default: 5. Range: 1 to 25. |
| `--sample-size <n>` | Number of catalog coffees to read per page before summarizing. Default: 5000. Range: 1 to 5000. |

Examples:

```bash
purvey catalog supplier-detail "Royal Coffee" --pretty
```

## purvey catalog supplier-rank

Rank suppliers by average Purveyor Score and stocked coverage.

Usage: `purvey catalog supplier-rank [options]`

Access: Viewer. Any signed-in account.

- Ranks suppliers by average Purveyor Score, then currently stocked count.
- Country and non-wholesale filters apply to coffees before suppliers are ranked.
- Output metadata reports source-ordered pagination, rows examined, and whether the aggregate is sample-limited.

| Argument or flag | Details |
| --- | --- |
| `--country <country>` | Only count coffees from this country. |
| `--stocked` | Only count coffees currently in stock; without it, coffees no longer stocked count too. |
| `--non-wholesale-only` | Leave out wholesale listings before suppliers are ranked. |
| `--min-coffees <n>` | Minimum number of matching coffees a supplier needs to be ranked. Default: 1. Range: 1 to 100. |
| `--sample-size <n>` | Number of catalog coffees to read per page before ranking suppliers. Default: 5000. Range: 1 to 5000. |
| `--limit <n>` | Maximum number of suppliers to return. Default: 25. Range: 1 to 100. |

Examples:

```bash
purvey catalog supplier-rank --country Ethiopia --non-wholesale-only --min-coffees 3 --pretty
```

## purvey catalog similar

Beta: find likely same-lot candidates and similar coffees for a catalog coffee.

Usage: `purvey catalog similar <id> [options]`

Access: Viewer. Any signed-in account.

- Needs a sign-in (`purvey auth login`) or any API key with catalog:read. The free Green API plan includes it within its monthly quota.
- Results are beta candidates to review, not confirmed matches.
- Default JSON output groups results under data.target, data.groups.canonical_candidates, data.groups.similar_recommendations, optional data.matches, and meta.
- canonical_candidates are likely same-lot candidates; similar_recommendations are profile substitutes and expose blocker reasons when identity details disagree.
- Keeps classification_version, query_strategy, proof summaries, pricing metadata, blocker details, and score dimensions as returned.

| Argument or flag | Details |
| --- | --- |
| `<id>` | Required: Catalog ID of the coffee to match. |
| `--threshold <score>` | Minimum similarity score a match needs; higher values return fewer, closer matches. Default: 0.7. Range: 0.5 to 0.99. |
| `--limit <count>` | Maximum number of matches to return. Default: 10. Range: 1 to 25. |
| `--stocked-only` | Only return coffees currently in stock; without it, matches can include coffees no longer stocked. |
| `--mode <mode>` | Which matches to return: all, likely_same (probably the same lot listed elsewhere), or similar_profile (substitutes with a similar profile). Default: all. |

Examples:

```bash
purvey catalog similar 1182 --threshold 0.85 --stocked-only --json
purvey catalog similar 1182 --mode likely_same --json | jq '.data.groups.canonical_candidates'
```

## purvey catalog compare

Compare 2 to 6 coffees side by side, priced at your quantity.

Usage: `purvey catalog compare <ids> [options]`

Access: Viewer. Any signed-in account.

- Rows are grouped Price, Availability, Origin, Process, Coffee, Grading, Taste, and Listing, each marked same, partial, or different.
- Price rows name the cheapest lots in bestLotIds; grading rows never carry best marks.
- Viewer accounts compare 2 coffees; member accounts and API keys compare up to 6.

| Argument or flag | Details |
| --- | --- |
| `<ids>` | Required: 2 to 6 catalog IDs, space- or comma-separated. |
| `--quantity <lb>` | Pounds you plan to buy, any positive number up to 10000; each coffee is priced at the tier that applies to this quantity. Default: 1. |

Examples:

```bash
purvey catalog compare 416 8806 --pretty
purvey catalog compare 416 8806 1182 --quantity 5 --json | jq '.data.bestPriceLotIds'
```

## purvey catalog price-history

Daily smallest-tier price history for one coffee.

Usage: `purvey catalog price-history <id> [options]`

Access: Viewer. Any signed-in account.

- Prices track the smallest order tier.
- Parchment decides access: member accounts, Parchment Intelligence, and API keys with catalog:read, including the key `purvey auth login` stores.
- Events flag days when the smallest tier's quantity changed, which makes prices before and after not directly comparable.

| Argument or flag | Details |
| --- | --- |
| `<id>` | Required: Catalog ID of the coffee. |
| `--days <n>` | How many days of history to return. Default: 180. Range: 7 to 365. |

Examples:

```bash
purvey catalog price-history 1182 --pretty
purvey catalog price-history 1182 --days 90 --json | jq '.data.summary'
```

## purvey catalog grades

Explain green grade codes such as KE:AA, ET:G1, GT:SHB, or PREP:EP.

Usage: `purvey catalog grades [codes] [options]`

Access: Viewer. Any signed-in account.

- Codes are \<system>:\<token>; composite grades such as ET:G1 carry more than one kind.
- Implied ranges come from the published definition, not from any listing.
- Codes not in the vocabulary are listed under unknownCodes.

| Argument or flag | Details |
| --- | --- |
| `[codes]` | Optional: optional grade codes to explain, space- or comma-separated. |
| `--kind <kind>` | Only codes of this kind: size, altitude, defects, cup, or preparation. |
| `--system <system>` | Only codes from this grading system, such as KE, ET, BR, ALT, or PREP. |
| `--include-retired` | Include retired codes, which stay valid on older listings. |

Examples:

```bash
purvey catalog grades KE:AA ET:G1 --pretty
purvey catalog grades --kind altitude --json | jq '.data[].code'
```

## purvey catalog taxonomies

Look up variety, species, and drying method codes, such as gesha or raised_bed.

Usage: `purvey catalog taxonomies [search] [options]`

Access: Viewer. Any signed-in account.

- Each entry has a code, a label, its family (parent_code), and the supplier spellings that map to it.
- Use the codes with `purvey catalog search --variety-code`, `--species-code`, and `--drying-method-code`.
- An empty result means the name is not in the vocabulary yet, not that no coffee has it.

| Argument or flag | Details |
| --- | --- |
| `[search]` | Optional: optional name to find; matches a code, a label, or a supplier spelling (geisha finds gesha). |
| `--taxonomy <name>` | Only this vocabulary: variety, species, or drying_method. |
| `--family <code>` | Only this family code and the codes under it, such as bourbon. |
| `--include-retired` | Include retired codes, which stay valid on older listings. |

Examples:

```bash
purvey catalog taxonomies geisha --pretty
purvey catalog taxonomies --taxonomy variety --family bourbon --pretty
```

## Related

- [Web catalog](https://www.purveyors.io/catalog): Browse the same catalog in the browser.
- [Purveyor Score](https://www.purveyors.io/docs/catalog/purveyor-score): How the score used by rank commands is calculated.
- [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group.