@purveyors/cli
CLI overview
The Purveyors CLI brings your coffee catalog, inventory, roasting, sales, and market data to the terminal, to scripts, and to AI agents.
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
npm install -g @purveyors/cli
purvey auth login
purvey auth statusSetting 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
purvey catalog search --origin "Ethiopia" --stocked --pretty
purvey inventory add --catalog-id 128 --qty 10 --cost 85.00Catalog proof and similarity research
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
purvey market signals --summary --pretty
purvey market stats --origin "Colombia" --window 30d --json
purvey price-index history --window-days 90 --jsonImport a roast from Artisan
purvey inventory list --stocked --pretty
purvey roast import ~/artisan/ethiopia.alog --coffee-id 7 --prettyFind a roast
purvey roast list --search "guji" --include-totals --pretty
purvey roast list --search "guji" --include-totals --limit 20 --offset 20
purvey roast get 4529 --prettyGet a roast's Artisan file back
purvey roast get 4529 | jq '.artisan_file_available'
purvey roast artisan-file 4529 --output ~/artisan/Plan and export an Artisan reference
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.alogPlan the next roast from a past roast
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.alogWatch a folder for new roasts
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" --prettyImport several roasts into one batch
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 --prettyRate coffee and record a sale
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"