# CLI overview

> The Purveyors CLI brings your coffee catalog, inventory, roasting, sales, and market data to the terminal, to scripts, and to AI agents.

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

purvey gives you terminal access to the same coffee data as the web app: catalog search and ranking, inventory, roasts and Artisan imports, sales, tasting notes, Market Index signals, the Parchment Price Index, sourcing briefs, and saved references and plans.

This reference matches @purveyors/cli 0.44.0. Run purvey --version to check your version, and purvey manifest for the exact contract of the version you have installed.

## Install and sign in

- Requires Node.js 20 or later.
- purvey auth login opens a browser page where you review the requesting machine and approve access. The CLI then stores its own scoped key for your account, so you never copy or paste a key.
- On a server, in CI, or for an AI agent, use purvey auth login --headless. It prints an approval link you can open in any browser, and the command finishes on its own once you approve.
- To use a specific API key instead, set PARCHMENT_API_KEY or PURVEYORS_API_KEY. A key in the environment takes priority over the stored sign-in.

Install and sign in:

```bash
npm install -g @purveyors/cli
purvey auth login
purvey auth status
```

> **Setting up an AI agent?**
>
> Set up your agent (/docs/agents/setup) walks an agent through install, browser sign-in, and the Purveyors skill. Copy the one-line prompt on that page and paste it into your agent.

## Command groups

Each group has a full reference page with every command, argument, flag, and example. Access levels are explained in Auth, config, and output.

| Group | What it does | Access | Reference |
| --- | --- | --- | --- |
| `purvey auth` | Sign in to purveyors.io, check your login, and sign out. | None. Works without signing in. | /docs/cli/auth-output |
| `purvey catalog` | Search, rank, and compare catalog coffees and suppliers, and find similar coffees. | Viewer. Any signed-in account. | /docs/cli/catalog |
| `purvey inventory` | Manage your green coffee inventory. | Member. Requires member access on your account. | /docs/cli/inventory |
| `purvey roast` | Record roasts, import and download Artisan .alog files, and watch a folder for new roasts. | Member. Requires member access on your account. | /docs/cli/roast |
| `purvey roast-batch` | List, open, rename, and delete roast batches by batch ID. | Member. Requires member access on your account. | /docs/cli/roast-batch |
| `purvey sales` | Record and manage coffee sales. | Member. Requires member access on your account. | /docs/cli/sales |
| `purvey tasting` | Read supplier tasting notes and record your own cupping scores. | Member. Requires member access on your account. | /docs/cli/tasting |
| `purvey config` | Manage local purvey CLI settings. | None. Works without signing in. | /docs/cli/auth-output |
| `purvey context` | Print a dense human-readable CLI reference, or the manifest as JSON. | None. Works without signing in. | /docs/cli/context-manifest |
| `purvey manifest` | Print the stable machine-readable CLI contract as JSON. | None. Works without signing in. | /docs/cli/context-manifest |
| `purvey skill` | Print or install agent instructions generated from this manifest. | None. Works without signing in. | /docs/cli/skill |
| `purvey market` | Market Index value signals, price movement, metadata trends, market overview, and named-lot evidence. | Varies by command. | /docs/cli/market |
| `purvey price-index` | Parchment Price Index snapshots, matched 30-day price comparisons, and chart history. | Varies by command. | /docs/cli/price-index |
| `purvey procurement` | Read your saved sourcing briefs and the catalog coffees that match them. | Member. Requires member access on your account. | /docs/cli/procurement |
| `purvey reference-profile` | Import, compare, adjust, save, and export Studio reference roast plans, from an Artisan file or a past roast, and download the original Artisan file. | Member. Requires member access on your account. | /docs/cli/reference-profile |

## Output for scripts

- Most commands write compact JSON to standard output. Add --pretty for indented JSON or --csv for list results on commands that support it.
- Progress messages and errors go to standard error, so standard output stays safe for pipes, jq, and redirects.
- When output is piped or redirected, errors are JSON with a stable code and exit code. In an interactive terminal without an output flag, you see readable messages instead.

## CLI, API, or web app

| Surface | Best for | Sign-in |
| --- | --- | --- |
| purvey | Terminal work, scripts, and AI agents acting on your account | purvey auth login, or an API key in the environment |
| Purveyors web catalog | Browsing and evaluating coffees without setup | None needed to browse |
| Parchment API (https://api.purveyors.io/v1) | Applications and server-to-server integrations with usage tracking and quotas | API key from the Parchment Console |
| Purveyors web app | Visual exploration, dashboards, and day-to-day account work | Browser sign-in |

## Common workflows

Catalog to inventory:

```bash
purvey catalog search --origin "Ethiopia" --stocked --pretty
purvey inventory add --catalog-id 128 --qty 10 --cost 85.00
```

Catalog proof and similarity research:

```bash
purvey catalog search --origin "Ethiopia" --include-proof --json
purvey catalog get 128 --include-proof --json
purvey catalog similar 1182 --threshold 0.85 --stocked-only --json | jq '.data.groups'
```

Check prices and market moves:

```bash
purvey market signals --summary --pretty
purvey market stats --origin "Colombia" --window 30d --json
purvey price-index history --window-days 90 --json
```

Import a roast from Artisan:

```bash
purvey inventory list --stocked --pretty
purvey roast import ~/artisan/ethiopia.alog --coffee-id 7 --pretty
```

Find a roast:

```bash
purvey roast list --search "guji" --include-totals --pretty
purvey roast list --search "guji" --include-totals --limit 20 --offset 20
purvey roast get 4529 --pretty
```

Get a roast's Artisan file back:

```bash
purvey roast get 4529 | jq '.artisan_file_available'
purvey roast artisan-file 4529 --output ~/artisan/
```

Plan and export an Artisan reference:

```bash
purvey reference-profile import ~/artisan/ethiopia.alog --title "Ethiopia baseline"
purvey reference-profile get 5ea1af6f-234c-43a9-9bf8-5678dd24f854 --pretty
purvey reference-profile preview 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --request changes.json --pretty
purvey reference-profile save 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --request changes.json --idempotency-key 3f6c2a1b-8e4d-4b7a-9c05-7e1f2d3a4b5c
purvey reference-profile export 0b7e9f52-3c61-4d8a-9e24-6f1a8c3d5b90 c43a1d7e-95b2-4e06-8f7c-1d2b3a4e5f68 --output ~/artisan/next-batch.alog
```

Plan the next roast from a past roast:

```bash
purvey reference-profile roasts --pretty
purvey reference-profile preview-from-roast 4529 --request changes.json --pretty
purvey reference-profile from-roast 4529 --artisan-source --pretty
purvey reference-profile save 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --request changes.json
purvey reference-profile export 0b7e9f52-3c61-4d8a-9e24-6f1a8c3d5b90 c43a1d7e-95b2-4e06-8f7c-1d2b3a4e5f68 --output ~/artisan/next-batch.alog
```

Watch a folder for new roasts:

```bash
purvey roast watch ~/artisan/ --coffee-id 7 --batch-prefix "wednesday"
purvey roast watch ~/artisan/ --auto-match
purvey roast watch --resume
purvey roast-batch list --name "wednesday" --pretty
```

Import several roasts into one batch:

```bash
purvey roast-batch create --name "wednesday" --pretty
purvey roast import ~/artisan/first.alog --coffee-id 7 --batch-id 7c1d4e2a-9b3f-4a6c-8d5e-2f1a0b9c8d7e
purvey roast import ~/artisan/second.alog --coffee-id 7 --batch-id 7c1d4e2a-9b3f-4a6c-8d5e-2f1a0b9c8d7e
purvey roast list --batch-id 7c1d4e2a-9b3f-4a6c-8d5e-2f1a0b9c8d7e --pretty
```

Rate coffee and record a sale:

```bash
purvey tasting rate 7 --aroma 4 --body 3 --acidity 5 --sweetness 4 --aftertaste 4
purvey roast-batch list --pretty
purvey sales record --batch-id 7c1d4e2a-9b3f-4a6c-8d5e-2f1a0b9c8d7e --coffee-id 7 --oz 12 --price 22.00 --buyer "Jane Smith"
```

## Related

- [Set up your agent](https://www.purveyors.io/docs/agents/setup): Install, browser sign-in, and the Purveyors skill for AI agents.
- [Auth, config, and output](https://www.purveyors.io/docs/cli/auth-output): Access roles, output modes, exit codes, and the ID reference.
- [Parchment API reference](https://api.purveyors.io/docs): The HTTP API behind the CLI, for building your own integrations.