# Purveyors documentation (full text) > Every Purveyors docs page as Markdown, in navigation order. For the Parchment HTTP API, see https://api.purveyors.io/docs. AI agents: to install the Purveyors CLI, sign in, and add the Purveyors skill, follow https://www.purveyors.io/docs/agents/setup.md --- Source: https://www.purveyors.io/docs/catalog/purveyor-score.md # Purveyor Score > Purveyor Score is a metadata and listing-intelligence score for green coffee listings. HTML version: https://www.purveyors.io/docs/catalog/purveyor-score Purveyor Score makes green coffee metadata quality visible at the point of comparison. It rewards structured, comparable, buyer-useful listing information because buyers cannot evaluate what suppliers do not disclose. The score is proprietary to Purveyors, deterministic, and intentionally narrow. It is not a cup quality score, supplier verification, certification, regulatory assurance, or a promise that a coffee is better than another coffee. This methodology follows the argument in Who Profits When Coffee Data Stays Scarce?: the industry has made progress on price transparency, but product metadata remains inconsistent and relationship-gated. Purveyor Score turns that disclosure gap into an inspectable product signal. ## What it measures Purveyor Score is scored from the normalized coffee_catalog metadata already used by the catalog, API, CLI, and analytics surfaces. It favors fields that help a buyer compare similar listings across suppliers: provenance, process transparency, freshness, pricing comparability, and sensory context. Confidence is separate from the score. Score measures metadata richness and buyer usefulness. Confidence measures how reliable and structured the inputs look, including recency, processing confidence, and evidence availability. | Dimension | Max points | Examples | | --- | --- | --- | | Provenance depth | 25 | Country, region, farm or producer notes, cultivar, grade, and appearance. | | Process transparency | 25 | Base method, fermentation, additives, drying method, duration, disclosure level, and processing confidence. | | Freshness and availability | 20 | Stock status, stocked date, arrival date, and last-updated date. | | Pricing comparability | 15 | Per-pound price, tiered pricing, and wholesale classification. | | Sensory context | 15 | Tasting notes, supplier cup score when present, roast recommendations, and useful catalog descriptions. | ## Tier language | Score | Tier | Meaning | | --- | --- | --- | | 85-100 | Exceptional | Deep, structured metadata across most buyer-relevant dimensions. | | 70-84 | Strong | Enough structured disclosure for confident comparison. | | 50-69 | Developing | Useful listing, but key metadata is missing or less structured. | | 1-49 | Limited | Sparse metadata. Treat as a starting point, not a complete sourcing picture. | | 0 | Unscored | No usable score inputs are available. | ## Why metadata matters - Price answers whether a transaction may be fair. Metadata answers whether this is the right coffee to buy. - Decision-critical fields such as arrival date, farm provenance, processing detail, cup score, and cultivar are less consistently disclosed than broad fields such as country. - Normalizing listings across suppliers makes both disclosed data and missing data visible. That visibility creates an incentive for richer disclosure. - The scraper and audit loop behind Purveyors treats data quality as something measurable: extraction gaps, field completeness, format validation, and source health all become signals the product can improve over time. > **Not verification** > > Purveyor Score does not verify supplier claims, certify a coffee, replace buyer due diligence, or rate cup quality. It summarizes the listing intelligence Purveyors can currently see. ## Implementation contract - Purveyor Score v1 is stored on coffee_catalog as purveyor_score, purveyor_score_confidence, purveyor_score_tier, purveyor_score_factors, purveyor_score_version, and purveyor_score_updated_at. - A database function computes the score from normalized fields and a trigger refreshes score fields when relevant metadata changes. - The score can be recalculated when the formula changes. Consumers should read purveyor_score_version before comparing scores across major methodology updates. - Raw supplier evidence remains withheld from public catalog responses unless a future product surface explicitly supports safe evidence inspection. Response fragment: ```json { "purveyor_score": 82, "purveyor_score_tier": "Strong", "purveyor_score_confidence": 0.78, "purveyor_score_version": "purveyor-score-v1" } ``` ## Related - [Green Coffee Catalog](https://www.purveyors.io/catalog): Browse the public catalog using the same score language. - [Catalog API](https://www.purveyors.io/docs/api/catalog): The public catalog contract that carries normalized listing data. - [Metadata scarcity thesis](https://www.purveyors.io/blog/who-profits-when-coffee-data-stays-scarce): The public essay that frames metadata as the real sourcing asymmetry. --- Source: https://www.purveyors.io/docs/cli/overview.md # 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.43.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. --- Source: https://www.purveyors.io/docs/cli/auth-output.md # Auth, config, and output > How purvey signs in, which commands need which access, where settings live, and how output, errors, and exit codes work. HTML version: https://www.purveyors.io/docs/cli/auth-output Use this page when you run purvey in scripts, CI, or agent tools. Output format, error envelopes, and exit codes are stable parts of the CLI contract. purvey auth login stores a scoped key for your account on this machine. purvey auth logout removes it locally; revoke the key from your API keys in the Parchment Console if the machine is lost. ## purvey auth login Log in to purveyors.io. Usage: `purvey auth login [options]` Access: None. Works without signing in. | Argument or flag | Details | | --- | --- | | `--headless` | Print the approval URL instead of opening a browser; use it for agents, SSH sessions, and remote machines. The CLI finishes on its own once you approve. | Examples: ```bash purvey auth login purvey auth login --headless ``` ## purvey auth status Show current login status and role. Usage: `purvey auth status [options]` Access: None. Works without signing in. | Argument or flag | Details | | --- | --- | | `--pretty` | Print the status as indented, colorized JSON. | | `--csv` | Print the status as a CSV row. | Examples: ```bash purvey auth status purvey auth status --pretty purvey auth status --json ``` ## purvey auth whoami Show the identity, plan, scopes, and capabilities of the active credential. Usage: `purvey auth whoami` Access: None. Works without signing in. - Prints the account details unchanged: authenticated, userId, appRoles, primaryAppRole, apiPlan, ppiAccess, apiScopes, and capabilities (capabilities.profileStudio shows Studio access). - Uses PARCHMENT_API_KEY or PURVEYORS_API_KEY when set, otherwise the stored login key. - Without a credential it prints a signed-out result (authenticated: false). Examples: ```bash purvey auth whoami --pretty purvey auth whoami | jq '.capabilities.profileStudio' ``` ## purvey auth logout Clear stored credentials. Usage: `purvey auth logout` Access: None. Works without signing in. Examples: ```bash purvey auth logout ``` ## Access roles Commands list the access they need. purvey auth login stores a scoped key for your account; PARCHMENT_API_KEY or PURVEYORS_API_KEY overrides it when set. | Role | Meaning | | --- | --- | | viewer | any signed-in account, or any API key with catalog:read; enough for every catalog command. | | member | a Purveyors membership; required for inventory, roast, roast-batch, sales, tasting, procurement, and reference-profile commands. | ## Global options | Flag | Details | | --- | --- | | `--json` | Print results as compact JSON, the default for data commands; use it to be explicit. | | `--pretty` | Print results as indented, colorized JSON for reading. | | `--csv` | Print list results as CSV on commands that support it. | | `--help` | Show help for purvey or any command. | | `--version` | Print the installed CLI version. | ## Output and errors Standard output: Structured JSON by default for most commands, CSV when explicitly requested on supporting commands, and human-readable reference text for `purvey context` unless JSON is requested. Standard error: interactive progress and prompts, plus human-readable or structured fatal errors depending on mode. - Most commands emit compact JSON to stdout by default. - Use --json to request compact JSON explicitly. - Use --pretty for indented JSON. - Use --csv for array-shaped results that support CSV output. - PURVEYORS_API_KEY or PARCHMENT_API_KEY, when set, is used instead of the key stored by `purvey auth login`. - `purvey context` prints dense human-readable operator reference text unless --json or --pretty is passed. - `purvey manifest` is the preferred machine-readable contract and always emits it on stdout. - `purvey context --json` stays available for compatibility parity with existing context-based callers. - `@purveyors/cli/manifest` exposes the same machine-readable contract for in-process consumers. - `purvey config list/get/set/reset` stay human-readable in an interactive TTY, but emit JSON on stdout in machine mode and reject --csv. - In interactive use, stderr may also carry prompts, spinners, and human-readable status lines. - Parser mistakes like unknown options, unknown commands, and missing required arguments follow the same fatal-error contract as runtime command failures. - Important exception: auth status prints human-readable output in an interactive TTY unless --json, --pretty, or --csv is passed; when piped or redirected it emits structured JSON automatically. > **Structured errors** > > Emitted for parser and runtime command failures when the invocation is non-interactive or when --json, --pretty, or --csv selects a machine-readable output mode. Every error includes error, code, exitCode, message. `purvey auth status` keeps its status payload on stdout even when unauthenticated; this envelope documents command failures. ## Exit codes | Exit code | Code | Meaning | | --- | --- | --- | | 0 | OK | success. | | 1 | GENERAL_ERROR | unexpected error. | | 2 | INVALID_ARGUMENT | invalid argument or input. | | 3 | AUTH_ERROR | not signed in, the stored key was revoked, or your account or API key lacks access to this command. | | 4 | NOT_FOUND | resource not found. | | 5 | DEPENDENCY_CONFLICT | the change conflicts with related records, such as deleting a coffee that still has roasts or sales. | | 6 | CONFIG_ERROR | configuration problem, such as a file path or API address the CLI cannot use. | ## ID reference Each ID belongs to one kind of record. Passing the wrong kind is the most common reason a command returns NOT_FOUND. | ID | Identifies | Used by | | --- | --- | --- | | `catalog_id` | a coffee listed in the Purveyors catalog | `catalog get`, `catalog similar`, `catalog compare`, `catalog price-history`, `inventory add --catalog-id`, `tasting get `, `roast list --catalog-id` | | `inventory_id` | a coffee in your green inventory | `inventory get/update/delete`, `roast --coffee-id`, `roast list --coffee-id`, `tasting rate [bean-id]` | | `roast_id` | one of your roast profiles | `roast get/chart/artisan-file/delete`, `roast list --roast-id`, `sales record --roast-id`, `sales list --roast-id`, `reference-profile compare roast:`, `reference-profile preview-from-roast/from-roast` | | `batch_id` | one of your roast batches (a UUID); batch names can repeat, batch IDs cannot | `roast-batch get/update/delete`, `roast list --batch-id`, `roast create/import/update/from-reference --batch-id`, `sales record --batch-id`, `sales list --batch-id` | | `sale_id` | one of your recorded sales | `sales update/delete` | | `reference_profile_id` | one of your Studio reference profiles | `reference-profile get`, `reference-profile chart`, `reference-profile preview/save`, `reference-profile export`, `reference-profile artisan-file`, `reference-profile compare profile:`, `roast from-reference` | | `reference_revision_id` | immutable revision belonging to a reference profile | `reference-profile chart`, `reference-profile preview/save`, `reference-profile export`, `reference-profile compare revision:`, `roast from-reference` | ## Common errors | Problem | Exit codes | What to do | | --- | --- | --- | | Not logged in | 3 | Run `purvey auth login` or `purvey auth login --headless`. Run `purvey auth status` to confirm role after login. | | Wrong ID type | 2, 4 | Verify whether the command wants catalog_id, inventory_id, roast_id, batch_id, sale_id, reference_profile_id, or reference_revision_id. See the ID map. | | Missing required args in write commands | 2 | Pass the required positional arguments and flags shown by `--help`; `--form` is an interactive terminal alternative. | | Parser mistakes like unknown options or commands | 2 | Unknown options, unknown commands, and missing required arguments use the same JSON error envelope contract in machine mode. In an interactive terminal with no explicit output flag, those parser failures stay human-readable. | | Dependency conflict on delete | 5 | Delete dependent roast profiles and sales records explicitly, then retry. | | Batch name matches more than one batch | 2 | `sales record --coffee-id --batch-name` lists each matching batch ID with its date; run it again with --batch-id. | | Mutually exclusive watch flags | 2 | `roast watch` forbids using --auto-match together with --coffee-id. | | Pagination only returning the first page | None | Only these commands page with --offset (default --limit): catalog search 10, inventory list 20, roast list 20, roast-batch list 20, sales list 20. For example `--limit 20 --offset 40` returns items 41-60. `roast list --include-totals` adds meta.totals.roasts; the last page is the one where --offset plus the rows returned reaches it. | ## Local files | File | Path | | --- | --- | | Stored sign-in | ~/.config/purvey/credentials.json | | Settings | ~/.config/purvey/config.json | ## purvey config list Show all config values. Usage: `purvey config list` Access: None. Works without signing in. - Interactive terminals print human-readable key = value lines. - Machine mode emits the full config object as JSON. - --csv is not supported on config commands. Examples: ```bash purvey config list purvey config list --json ``` ## purvey config get Get a config value. Usage: `purvey config get ` Access: None. Works without signing in. - Interactive terminals print the raw value with no decorators. - Machine mode emits {"\": value|null}. - --csv is not supported on config commands. | Argument or flag | Details | | --- | --- | | `` | Required: Config key. | Examples: ```bash purvey config get form-mode purvey config get form-mode --json ``` ## purvey config set Set a config value. Usage: `purvey config set ` Access: None. Works without signing in. - Interactive terminals print a human-readable success line. - Machine mode emits the updated config value as JSON. - --csv is not supported on config commands. | Argument or flag | Details | | --- | --- | | `` | Required: Config key. | | `` | Required: Config value. | Examples: ```bash purvey config set form-mode true purvey config set form-mode true --json ``` ## purvey config reset Reset config to defaults. Usage: `purvey config reset` Access: None. Works without signing in. - Interactive terminals print a human-readable success line. - Machine mode emits {}. - --csv is not supported on config commands. Examples: ```bash purvey config reset purvey config reset --json ``` ## Related - [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group. - [Context and manifest](https://www.purveyors.io/docs/cli/context-manifest): Readable and machine-readable references for your installed version. - [API keys](https://www.purveyors.io/api-dashboard/keys): Review and revoke keys in the Parchment Console. --- Source: https://www.purveyors.io/docs/cli/catalog.md # 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 ` | Only coffees from this origin; matches continent, country, or region names, case-insensitive and partial. | | `--process ` | Only coffees whose processing label contains this text, such as natural or washed (case-insensitive). | | `--processing-base-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 ` | Only coffees whose structured fermentation type exactly matches this value, such as Anaerobic. List values with `purvey catalog facets fermentation_type`. | | `--process-additive ` | Only coffees whose process discloses exactly this additive, such as hops. | | `--processing-disclosure-level ` | Only coffees whose supplier disclosed process details at exactly this level. | | `--processing-confidence-min ` | Only coffees whose process details were identified with at least this confidence. Range: 0 to 1. | | `--price-min ` | Lowest price per pound to include, in US dollars. | | `--price-max ` | Highest price per pound to include, in US dollars. | | `--name ` | Only coffees whose name contains this text (case-insensitive). | | `--ids ` | Fetch these catalog IDs, comma-separated, instead of searching; --limit and --offset are ignored. | | `--variety ` | Only coffees whose variety or cultivar contains this text (case-insensitive). | | `--stocked-days ` | Only coffees that came into stock within the last N days. | | `--supplier ` | Only coffees from suppliers whose name contains this text (case-insensitive). | | `--drying-method ` | Only coffees whose drying method or processing text contains this value, such as raised bed (case-insensitive). | | `--flavor ` | 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 ` | Sort by price (cheapest first), price-desc, name, or origin (by country); without it, the most recently stocked coffees come first. | | `--offset ` | Number of results to skip when paging; must be a multiple of --limit. Default: 0. | | `--limit ` | 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 ` | Lowest growing elevation in meters; coffees whose disclosed range overlaps match. Range: 1 to 6000. | | `--elevation-max ` | Highest growing elevation in meters. Range: 1 to 6000. | | `--screen-min ` | Smallest disclosed screen size (64ths of an inch); an 18+ lot matches any minimum up to its range. Range: 8 to 20. | | `--screen-max ` | Largest disclosed screen size (64ths of an inch). Range: 8 to 20. | | `--grade ` | 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 ` | 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 ` | Highest disclosed moisture percentage; coffees without a moisture reading are excluded. Range: 0 to 20. | | `--score-protocol ` | Only cup scores from this protocol: sca_2004, cva_affective, q_arabica, coe, or supplier_unspecified. | | `--variety-code ` | 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 ` | Comma-separated species codes such as arabica or canephora (Robusta); matches coffees whose supplier states the species. | | `--drying-method-code ` | Comma-separated drying method codes such as raised_bed,patio; raised_bed also matches african_bed. | Examples: ```bash 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 [options]` Access: Viewer. Any signed-in account. | Argument or flag | Details | | --- | --- | | `` | 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, 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. | | `--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 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 ` | 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 ` | Only coffees from suppliers whose name contains this text. | | `--country ` | Only coffees from this country. | | `--process ` | 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 ` | Highest price per pound to include, in US dollars. | | `--min-score ` | Lowest Purveyor Score to include. | | `--non-wholesale-only` | Leave out wholesale listings, keeping retail and listings with unknown wholesale status, before sampling. | | `--sample-size ` | Number of matching coffees to consider before ranking; a smaller sample is faster but may miss candidates. Default: 5000. Range: 1 to 5000. | | `--limit ` | 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 ` | Only coffees from this continent, country, or region (case-insensitive). | | `--process ` | 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 ` | Highest price per pound to include, in US dollars. | | `--min-score ` | Lowest Purveyor Score to include. | | `--include-unscored` | Also list coffees without a Purveyor Score, after all scored coffees. | | `--sample-size ` | Number of matching coffees to consider before ranking. Default: 250. Range: 1 to 5000. | | `--limit ` | 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 ` | 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 ` | Number of catalog coffees to read per page before summarizing suppliers. Default: 5000. Range: 1 to 5000. | | `--limit ` | 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 [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 | | --- | --- | | `` | Required: Supplier name to look up (case-insensitive, partial match). | | `--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 ` | Number of representative top coffees to include. Default: 5. Range: 1 to 25. | | `--sample-size ` | 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 ` | 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 ` | Minimum number of matching coffees a supplier needs to be ranked. Default: 1. Range: 1 to 100. | | `--sample-size ` | Number of catalog coffees to read per page before ranking suppliers. Default: 5000. Range: 1 to 5000. | | `--limit ` | 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 [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 | | --- | --- | | `` | Required: Catalog ID of the coffee to match. | | `--threshold ` | Minimum similarity score a match needs; higher values return fewer, closer matches. Default: 0.7. Range: 0.5 to 0.99. | | `--limit ` | 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 ` | 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 [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 | | --- | --- | | `` | Required: 2 to 6 catalog IDs, space- or comma-separated. | | `--quantity ` | 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 [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 | | --- | --- | | `` | Required: Catalog ID of the coffee. | | `--days ` | 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 \:\; 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 ` | Only codes of this kind: size, altitude, defects, cup, or preparation. | | `--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 ` | Only this vocabulary: variety, species, or drying_method. | | `--family ` | 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. --- Source: https://www.purveyors.io/docs/cli/inventory.md # Inventory commands > Manage your green coffee inventory. HTML version: https://www.purveyors.io/docs/cli/inventory Manage the green coffee inventory you see on the Beans page of the web app. Inventory IDs are separate from catalog IDs; roast and tasting commands expect inventory IDs. Access: Member. Requires member access on your account. ## Before you start > **Use inventory IDs for roast work** > > purvey roast --coffee-id expects an inventory ID from purvey inventory list, not a catalog ID. ## purvey inventory list List your green coffee inventory with catalog details. Usage: `purvey inventory list [options]` Access: Member. Requires member access on your account. - Returns your inventory items with their catalog details. - The returned id field is the inventory ID, distinct from catalog_id. - --offset + --limit enables pagination through large result sets. | Argument or flag | Details | | --- | --- | | `--stocked` | Only coffees you have marked as in stock. | | `--catalog-id ` | Only inventory items bought from this catalog coffee (a catalog ID). | | `--purchase-date-start ` | Only purchases made on or after this date. | | `--purchase-date-end ` | Only purchases made on or before this date. | | `--origin ` | Only coffees whose country of origin contains this text. | | `--limit ` | Maximum number of items to return. Default: 20. | | `--offset ` | Number of items to skip when paging. Default: 0. | Examples: ```bash purvey inventory list --stocked --pretty purvey inventory list --limit 20 --offset 20 ``` ## purvey inventory get Get a single inventory item. Usage: `purvey inventory get ` Access: Member. Requires member access on your account. | Argument or flag | Details | | --- | --- | | `` | Required: Inventory ID of the item. | Examples: ```bash purvey inventory get 7 --pretty ``` ## purvey inventory add Add a bean to your inventory. Usage: `purvey inventory add [options]` Access: Member. Requires member access on your account. - Flag mode requires --qty and exactly one of --catalog-id or --manual-name. - --manual-name creates a manual coffee record when manual inventory entries are enabled. | Argument or flag | Details | | --- | --- | | `--catalog-id ` | Catalog ID of the coffee you bought; use exactly one of --catalog-id or --manual-name. | | `--manual-name ` | Name for a coffee that is not in the catalog; use exactly one of --catalog-id or --manual-name. | | `--qty ` | Quantity purchased, in pounds. Required unless you use --form. | | `--cost ` | Total amount paid for the beans, in US dollars (not the price per pound). | | `--tax-ship ` | Tax and shipping paid for this purchase, in US dollars. | | `--notes ` | Free-text notes about this purchase. | | `--purchase-date ` | Date of purchase; defaults to today. | | `--form` | Prompt for a catalog coffee, quantity, total cost, and notes; the purchase date is set to today. | Examples: ```bash purvey inventory add --catalog-id 128 --qty 10 --cost 85.00 --pretty purvey inventory add --manual-name "Farm-gate Ethiopia lot 7" --qty 12 --cost 96 --pretty ``` ## purvey inventory update Update an inventory item. Usage: `purvey inventory update [options]` Access: Member. Requires member access on your account. | Argument or flag | Details | | --- | --- | | `` | Required: Inventory ID of the item. | | `--qty ` | New purchased quantity, in pounds. | | `--cost ` | New total bean cost, in US dollars (not the price per pound). | | `--tax-ship ` | New tax and shipping amount, in US dollars. | | `--notes ` | Replace the notes for this item. | | `--stocked ` | Mark the coffee as in stock (true) or used up (false). | | `--rank ` | Your own whole-number ranking for this coffee, used to order your inventory. | ## purvey inventory delete Delete an inventory item. Usage: `purvey inventory delete [options]` Access: Member. Requires member access on your account. | Argument or flag | Details | | --- | --- | | `` | Required: Inventory ID of the item. | | `--yes` | Delete without asking for confirmation; needed in scripts and agents. | ## Related - [Roast commands](https://www.purveyors.io/docs/cli/roast): Inventory IDs feed roast create, import, and watch. - [Beans page](https://www.purveyors.io/beans): Manage inventory in the web app. - [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group. --- Source: https://www.purveyors.io/docs/cli/roast.md # Roast commands > Record roasts, import and download Artisan .alog files, and watch a folder for new roasts. HTML version: https://www.purveyors.io/docs/cli/roast Record roasts, import Artisan .alog files with their curves and milestones, download the file a roast was imported from, and watch a folder so new roasts are captured automatically. Access: Member. Requires member access on your account. ## purvey roast list List your roast profiles, sorted by date. Usage: `purvey roast list [options]` Access: Member. Requires member access on your account. - --coffee-id expects inventory_id, not catalog_id. - --catalog-id filters by catalog ID. - --date-start and --date-end accept YYYY-MM-DD format. - --search takes up to 100 characters and is matched as written: % and _ are ordinary characters, and * stands for any one character. A number finds the roast with exactly that ID, and any roast with the number in its coffee or batch name. Search text that is refused exits 2; the message calls the search text q. - Every filter narrows the list together: --search with --coffee-name, --batch-name, or --roast-id returns only roasts that match all of them. - --wholesale false includes roasts of coffees with no catalog listing, so true and false together cover every roast. - --include-totals adds meta.totals { roasts, batches, average_loss_percent } for every roast the filters match, the same on every page. average_loss_percent is null when no matching roast has a recorded weight loss. An empty result prints data: [] with totals of zero. It does not support --csv. - Paging: raise --offset by --limit. With --include-totals, a page is the last one when --offset plus the number of roasts returned reaches meta.totals.roasts. - Without --include-totals the output is a list of roasts, and an empty result prints nothing on stdout. - Every roast includes batch_id, the ID of the batch it belongs to. - artisan_file_available is true when roast artisan-file can return the Artisan file the roast was imported from. | Argument or flag | Details | | --- | --- | | `--coffee-id ` | Only roasts of this inventory item (an inventory ID, not a catalog ID). | | `--roast-id ` | Only the roast with this roast ID. | | `--batch-id ` | Only the roasts in this batch (a batch ID from roast-batch list). | | `--batch-name ` | Only roasts whose batch name contains this text (case-insensitive); names can repeat, so this can span several batches. | | `--coffee-name ` | Only roasts of coffees whose name contains this text (case-insensitive). | | `--search ` | Only roasts whose coffee name or batch name contains this text (case-insensitive), or whose roast ID is this number, with or without a leading #. | | `--date-start ` | Only roasts on or after this date. | | `--date-end ` | Only roasts on or before this date. | | `--stocked` | Only roasts of coffees still marked as in stock in your inventory. | | `--catalog-id ` | Only roasts of coffees bought from this catalog coffee (a catalog ID). | | `--wholesale ` | true for roasts of wholesale coffees only, false for every other roast; without it, both. | | `--include-totals` | Print { data, meta } instead of a list: data is the page of roasts, and meta.totals counts every roast the filters match. | | `--limit ` | Maximum number of roasts to return. Default: 20. | | `--offset ` | Number of roasts to skip when paging. Default: 0. | Examples: ```bash purvey roast list --search "guji" --include-totals purvey roast list --wholesale false --limit 20 --offset 20 purvey roast list --date-start 2026-03-01 --date-end 2026-03-31 purvey roast list --batch-id 7c1d4e2a-9b3f-4a6c-8d5e-2f1a0b9c8d7e ``` ## purvey roast get Get a single roast profile. Usage: `purvey roast get [options]` Access: Member. Requires member access on your account. - artisan_file_available is true when roast artisan-file can return the Artisan file the roast was imported from. | Argument or flag | Details | | --- | --- | | `` | Required: Roast ID. | | `--include-temps` | Add the full temperature curve; output can be large. | | `--include-events` | Add roast event markers such as first crack and drop. | ## purvey roast chart Get sampled chart data for one roast: temperature series, events, and chart revision. Usage: `purvey roast chart [options]` Access: Member. Requires member access on your account. - Returns the roast chart data unchanged: sampled series, events, and metadata. - data.metadata.revision identifies the immutable chart revision used by reference-profile compare. | Argument or flag | Details | | --- | --- | | `` | Required: Roast ID. | | `--target-points ` | Approximate number of samples per temperature series. Default: 400. Range: 50 to 1000. | Examples: ```bash purvey roast chart 123 --pretty purvey roast chart 123 --target-points 120 | jq '.data.metadata.revision' ``` ## purvey roast artisan-file Download the Artisan file a roast was imported from, exactly as you uploaded it. Usage: `purvey roast artisan-file [options]` Access: Member. Requires member access on your account. - Writes the file byte for byte, checks it against its SHA-256, and prints a JSON receipt: data.path, data.bytes, data.sha256. A file that fails the check is removed. - Requires Studio access on your account; API keys need the roast:read scope. - A roast has a file when artisan_file_available is true in roast get or roast list. Roasts entered by hand, logged live, or imported before files were kept have none; the error message says which. | Argument or flag | Details | | --- | --- | | `` | Required: Roast ID. | | `--output ` | File to write, or an existing folder to save the file in under its original name. Defaults to the current folder. | | `--force` | Overwrite the output file if it already exists. | Examples: ```bash purvey roast artisan-file 123 purvey roast artisan-file 123 --output ~/artisan/ ``` ## purvey roast create Create a new roast profile. Usage: `purvey roast create [options]` Access: Member. Requires member access on your account. - Pass --batch-id or --batch-name, not both. The created roast includes batch_id. | Argument or flag | Details | | --- | --- | | `--coffee-id ` | Inventory ID of the coffee you roasted (not a catalog ID). Required unless you use --form. | | `--batch-id ` | Add the roast to this existing batch, whatever the roast date; the roast takes the batch's name. Use instead of --batch-name. | | `--batch-name ` | Add the roast to your batch with this name on the roast date, or start one; defaults to the coffee name plus today's date. | | `--oz-in ` | Green coffee weight going in, in ounces. | | `--oz-out ` | Roasted coffee weight coming out, in ounces. | | `--roast-date ` | Date of the roast; defaults to today. | | `--notes ` | Free-text notes about the roast. | | `--targets ` | What you were aiming for, such as "FC at 390F, 18% development". | | `--roaster-type ` | Roaster model or type, such as Aillio Bullet. | | `--form` | Prompt for an inventory coffee, batch name, weight in, notes, and targets; the roast date is set to today and targets are saved in the notes. | ## purvey roast update Update a roast profile. Usage: `purvey roast update [options]` Access: Member. Requires member access on your account. - --batch-id and --batch-name move this roast between batches. To rename a batch, use roast-batch update --name. | Argument or flag | Details | | --- | --- | | `` | Required: Roast ID. | | `--notes ` | Replace the roast notes. | | `--oz-out ` | New roasted weight, in ounces; weight loss is recalculated when the green weight is known. | | `--batch-id ` | Move the roast into this batch; use instead of --batch-name. | | `--batch-name ` | Move the roast into your batch with this name on the roast date, or start one. | | `--targets ` | Replace the roast targets. | ## purvey roast delete Delete a roast profile. Usage: `purvey roast delete [options]` Access: Member. Requires member access on your account. - Deleting the last roast in a batch leaves the batch in place, empty. Remove it with roast-batch delete. | Argument or flag | Details | | --- | --- | | `` | Required: Roast ID. | | `--yes` | Delete without asking for confirmation; needed in scripts and agents. | ## purvey roast import Import an Artisan .alog roast file. Usage: `purvey roast import [file] [options]` Access: Member. Requires member access on your account. - Pass --batch-id or --batch-name, not both. - The result includes batch_id; pass it as --batch-id to import the next file into the same batch. | Argument or flag | Details | | --- | --- | | `[file]` | Optional: Path to Artisan .alog file. | | `--coffee-id ` | Inventory ID of the coffee you roasted (not a catalog ID). Required unless you use --form. | | `--batch-id ` | Add the roast to this existing batch, whatever the roast date; the roast takes the batch's name. Use instead of --batch-name. | | `--batch-name ` | Add the roast to your batch with this name on the roast date, or start one; defaults to the coffee name plus the roast date. | | `--oz-in ` | Green coffee weight going in, in ounces; overrides the weight read from the .alog file. | | `--roast-notes ` | Notes to save with the imported roast. | | `--roast-targets ` | What you were aiming for, saved with the imported roast. | | `--form` | Pick the file and inventory item interactively. | ## purvey roast from-reference Create a roast from the Artisan file saved with a reference profile. Usage: `purvey roast from-reference [options]` Access: Member. Requires member access on your account. - Creates the roast from the Artisan file uploaded with reference-profile import, so the .alog file does not need to be on this machine. - Only an uploaded Artisan reference can become a roast. A generated plan is never recorded as a roast, and a reference saved from a past roast is refused because that roast is already in your history. - Output is the created roast with its curve, an import summary, and the reference it came from. - Pass --batch-id or --batch-name, not both. - Requires a member credential and Studio access on your account. | Argument or flag | Details | | --- | --- | | `` | Required: UUID of an uploaded Artisan reference profile. | | `` | Required: UUID of that profile's current revision. | | `--coffee-id ` | Required. Inventory ID of the coffee you roasted (not a catalog ID). | | `--batch-id ` | Add the roast to this existing batch, whatever the roast date; the roast takes the batch's name. Use instead of --batch-name. | | `--batch-name ` | Add the roast to your batch with this name on the roast date, or start one; defaults to the coffee name plus the roast date. | | `--roast-date ` | Date of the roast; defaults to the date in the saved Artisan file. | | `--oz-in ` | Green coffee weight going in, in ounces; overrides the weight in the saved Artisan file. | | `--oz-out ` | Roasted weight coming out, in ounces; overrides the weight in the saved Artisan file. | | `--roast-notes ` | Notes to save with the new roast. | | `--roast-targets ` | What you were aiming for, saved with the new roast. | | `--idempotency-key ` | Key that makes retries safe: repeating the command with the same key does not create a second roast. A new key is generated when omitted. | Examples: ```bash purvey roast from-reference 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --coffee-id 7 --pretty ``` ## purvey roast watch Watch a directory for new Artisan .alog files. Usage: `purvey roast watch [directory] [options]` Access: Member. Requires member access on your account. - --auto-match is mutually exclusive with --coffee-id. - --auto-match matches each new roast to a stocked inventory item from its metadata. - --commit-mode defaults to batch so new roasts are queued until the session ends. - In batch commit mode the session opens one new batch, named by --batch-prefix, and saves every roast into it by batch ID. It stays one batch when the name was used before and when the session runs past midnight. The closing summary prints the batch ID. - --resume keeps adding to the same batch. A session saved by an earlier CLI version, which stored only the batch name, continues in the batch that holds its first saved roast. - The batch is opened when the first roast is saved. If no roast is saved into it, for example when every import fails, it is removed when the session ends. - In individual commit mode each roast is its own batch, named "\ #1", "\ #2", and so on. | Argument or flag | Details | | --- | --- | | `[directory]` | Optional: Directory to watch. | | `--coffee-id ` | Inventory ID to attach every new roast to; required unless you use --auto-match, --resume, or --form. | | `--batch-prefix ` | Batch name for the watch session; defaults to the coffee name. Batch commit mode saves every roast into one new batch with this name, and individual commit mode numbers them like "\ #1". | | `--prompt-each` | Ask which inventory item each new file belongs to instead of attaching every file to --coffee-id. | | `--auto-match` | Match each new roast to a stocked inventory item automatically from details in its .alog file; cannot be combined with --coffee-id. | | `--commit-mode ` | batch queues new roasts and saves them into one new batch when you stop watching, so the session is a single batch; individual saves each roast as soon as its file appears, as its own numbered batch. Default: batch. | | `--oz-in ` | Green coffee weight, in ounces, to record for every watched import. | | `--roast-notes ` | Notes to save with every watched import. | | `--roast-targets ` | Roast targets to save with every watched import. | | `--resume` | Continue the last watch session with its saved directory, settings, import progress, and batch. | | `--form` | Set up the directory, coffee, and commit mode interactively. | ## Related - [Roasts page](https://www.purveyors.io/roast): Charts, comparison, and plans. - [Roast batch commands](https://www.purveyors.io/docs/cli/roast-batch): Work on a roasting session by its batch ID. - [Sales commands](https://www.purveyors.io/docs/cli/sales): Record sales against roast IDs. - [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group. --- Source: https://www.purveyors.io/docs/cli/roast-batch.md # Roast batch commands > List, open, rename, and delete roast batches by batch ID. HTML version: https://www.purveyors.io/docs/cli/roast-batch A batch is one roasting session and the roasts in it. Batch names can repeat, so these commands find a batch by its ID. Access: Member. Requires member access on your account. ## purvey roast-batch list List your roast batches, newest batch date first. Usage: `purvey roast-batch list [options]` Access: Member. Requires member access on your account. - A batch is one roasting session. Each batch has id, name, batch_date, roast_count, roast_ids, and coffee_ids (the inventory items roasted). - The date filters use the batch date, not the roast dates inside the batch. - A batch with no roasts is listed only with --include-empty, under a placeholder name. | Argument or flag | Details | | --- | --- | | `--name ` | Only batches with exactly this name; several batches can carry the same name. | | `--date-start ` | Only batches dated on or after this date. | | `--date-end ` | Only batches dated on or before this date. | | `--include-empty` | Also list batches that hold no roasts. | | `--limit ` | Maximum number of batches to return. Default: 20. Range: 1 to 200. | | `--offset ` | Number of batches to skip when paging. Default: 0. | Examples: ```bash purvey roast-batch list --pretty purvey roast-batch list --name "wednesday" --pretty ``` ## purvey roast-batch get Get one roast batch with the IDs of its roasts. Usage: `purvey roast-batch get ` Access: Member. Requires member access on your account. - List the full roasts with roast list --batch-id. | Argument or flag | Details | | --- | --- | | `` | Required: Batch ID. | ## purvey roast-batch create Open a new, empty roast batch to add roasts to. Usage: `purvey roast-batch create [options]` Access: Member. Requires member access on your account. - Always opens a new batch, even when another batch has the same name. - Add roasts with --batch-id on roast import, roast create, or roast from-reference. Roasts keep their own dates, so one batch can span days. - Until it holds a roast, the batch is listed only with --include-empty and reads with a placeholder name. - roast watch opens its own batch; use this when importing files one at a time. | Argument or flag | Details | | --- | --- | | `--name ` | Required. Name for the batch; other batches may already use it. | | `--date ` | Session date for the batch; defaults to today. | | `--idempotency-key ` | Key that makes retries safe: repeating the command with the same key does not open a second batch. A new key is generated when omitted. | Examples: ```bash purvey roast-batch create --name "wednesday" --pretty ``` ## purvey roast-batch update Rename or re-date a roast batch. Usage: `purvey roast-batch update [options]` Access: Member. Requires member access on your account. - Pass at least one flag. Other batches with the same name are not changed. | Argument or flag | Details | | --- | --- | | `` | Required: Batch ID. | | `--name ` | New name for this batch; it also appears on the batch's roasts and on sales recorded against it. | | `--date ` | New batch date; roast dates are not changed. | Examples: ```bash purvey roast-batch update 7c1d4e2a-9b3f-4a6c-8d5e-2f1a0b9c8d7e --name "wednesday decaf" ``` ## purvey roast-batch delete Delete one roast batch and the roasts in it. Usage: `purvey roast-batch delete [options]` Access: Member. Requires member access on your account. - Deletes this batch and every roast in it, with their temperature and event data. No other batch is touched, even one with the same name. - Sales recorded against the batch are kept: they keep the batch name and lose the link to the batch. - Output is the deleted batch ID, its name, and the IDs of the roasts deleted with it. | Argument or flag | Details | | --- | --- | | `` | Required: Batch ID. | | `--yes` | Delete without asking for confirmation; needed in scripts and agents. | Examples: ```bash purvey roast-batch delete 7c1d4e2a-9b3f-4a6c-8d5e-2f1a0b9c8d7e --yes ``` ## Related - [Roast commands](https://www.purveyors.io/docs/cli/roast): Add roasts to a batch and list the roasts in one. - [Sales commands](https://www.purveyors.io/docs/cli/sales): Record sales against a batch ID. - [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group. --- Source: https://www.purveyors.io/docs/cli/sales.md # Sales commands > Record and manage coffee sales. HTML version: https://www.purveyors.io/docs/cli/sales Record roasted-coffee sales against roast profiles. Sales roll into the Profit page in the web app. Access: Member. Requires member access on your account. ## purvey sales list List your sales, sorted by sell date. Usage: `purvey sales list [options]` Access: Member. Requires member access on your account. - --coffee-id filters by inventory ID. - Every sale includes batch_id and roast_id. batch_id is null when the sale is not linked to one batch; roast_id is set only when the sale named a roast. - --date-start and --date-end accept YYYY-MM-DD and compose into a range. - --offset + --limit enables pagination through large result sets. | Argument or flag | Details | | --- | --- | | `--coffee-id ` | Only sales of this inventory item (an inventory ID). | | `--batch-id ` | Only sales recorded against this roast batch. | | `--roast-id ` | Only sales that name this roast. | | `--date-start ` | Only sales on or after this date. | | `--date-end ` | Only sales on or before this date. | | `--buyer ` | Only sales to buyers whose name contains this text (case-insensitive). | | `--limit ` | Maximum number of sales to return. Default: 20. | | `--offset ` | Number of sales to skip when paging. Default: 0. | ## purvey sales record Record a new sale. Usage: `purvey sales record [options]` Access: Member. Requires member access on your account. - Selector modes: --batch-id (with --coffee-id when the batch holds more than one coffee), --roast-id, or --coffee-id + --batch-name. - --batch-id records the sale against the batch as a whole, for a bag that could have come from any of its roasts of that coffee. --roast-id also records which roast it came from. - Batch names can repeat. When --coffee-id + --batch-name matches more than one batch, nothing is recorded and the error lists each batch ID with its date and roast IDs; run the command again with --batch-id. - The recorded sale includes batch_id, and roast_id when --roast-id was used. | Argument or flag | Details | | --- | --- | | `--batch-id ` | Batch the coffee came from, by batch ID; records the sale against the batch as a whole. Add --coffee-id when the batch holds more than one coffee. | | `--roast-id ` | Roast the coffee came from; records the sale against that roast and its batch. The CLI looks up the inventory item and batch. | | `--coffee-id ` | Inventory ID of the coffee sold; use with --batch-id or --batch-name, not with --roast-id. | | `--batch-name ` | Exact batch name of the coffee sold; use with --coffee-id. Refused when the name matches more than one batch. | | `--oz ` | Roasted coffee sold, in ounces. Required unless you use --form. | | `--price ` | Total sale price, in US dollars (not per ounce). Required unless you use --form. | | `--buyer ` | Buyer name or identifier. | | `--sell-date ` | Date of the sale; defaults to today. | | `--form` | Prompt for a roast, ounces sold, sale price, and buyer; the sale date is set to today. | ## purvey sales update Update a sale record. Usage: `purvey sales update [options]` Access: Member. Requires member access on your account. | Argument or flag | Details | | --- | --- | | `` | Required: Sale ID. | | `--oz ` | New amount sold, in ounces. | | `--price ` | New total sale price, in US dollars. | | `--buyer ` | New buyer name or identifier. | | `--sell-date ` | New sale date. | ## purvey sales delete Delete a sale record. Usage: `purvey sales delete [options]` Access: Member. Requires member access on your account. | Argument or flag | Details | | --- | --- | | `` | Required: Sale ID. | | `--yes` | Delete without asking for confirmation; needed in scripts and agents. | ## Related - [Profit page](https://www.purveyors.io/profit): See margins built from sales. - [Roast commands](https://www.purveyors.io/docs/cli/roast): Find the roast IDs that sales reference. - [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group. --- Source: https://www.purveyors.io/docs/cli/tasting.md # Tasting commands > Read supplier tasting notes and record your own cupping scores. HTML version: https://www.purveyors.io/docs/cli/tasting Read supplier tasting notes from the catalog and record your own cupping scores on inventory items. Access: Member. Requires member access on your account. ## purvey tasting get Get tasting notes for a coffee. Usage: `purvey tasting get [options]` Access: Member. Requires member access on your account. | Argument or flag | Details | | --- | --- | | `` | Required: Catalog ID of the coffee, not an inventory ID. | | `--filter ` | Which notes to return: user (your cupping scores), supplier (the supplier's flavor notes), or both. Default: both. | ## purvey tasting rate Rate a coffee bean with cupping scores. Usage: `purvey tasting rate [bean-id] [options]` Access: Member. Requires member access on your account. - Rating again replaces the earlier scores for that inventory item. | Argument or flag | Details | | --- | --- | | `[bean-id]` | Optional: Inventory ID of the coffee, not a catalog ID. | | `--aroma <1-5>` | Aroma score, a whole number; higher is better. Required unless you use --form. Range: 1 to 5. | | `--body <1-5>` | Body score, a whole number; higher is better. Required unless you use --form. Range: 1 to 5. | | `--acidity <1-5>` | Acidity score, a whole number; higher is better. Required unless you use --form. Range: 1 to 5. | | `--sweetness <1-5>` | Sweetness score, a whole number; higher is better. Required unless you use --form. Range: 1 to 5. | | `--aftertaste <1-5>` | Aftertaste score, a whole number; higher is better. Required unless you use --form. Range: 1 to 5. | | `--brew-method ` | How you brewed the coffee, such as pour_over, french_press, or espresso. | | `--notes ` | Free-text tasting notes. | | `--form` | Pick the coffee, then enter the five scores and notes interactively. | ## Related - [Inventory commands](https://www.purveyors.io/docs/cli/inventory): Cupping scores are stored on inventory items. - [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group. --- Source: https://www.purveyors.io/docs/cli/skill.md # Agent skill commands > Print or install agent instructions generated from this manifest. HTML version: https://www.purveyors.io/docs/cli/skill Print or install instructions that teach an AI agent the Purveyors commands, ID types, and output rules. Access: None. Works without signing in. ## purvey skill print Write the generated SKILL.md, workflows.md, or the AGENTS.md block to stdout. Usage: `purvey skill print [options]` Access: None. Works without signing in. - Prints one file as Markdown by default; --json or --pretty wraps it as { name, file, cliVersion, bytes, content }, or every file with --file all as { name, cliVersion, files: [{ file, bytes, content }] }. - --csv is not supported, and --agents-md cannot be combined with --file. - Rendered from this manifest, so it changes only when the CLI contract changes. | Argument or flag | Details | | --- | --- | | `--file ` | Skill file to print: SKILL.md, workflows.md, or all; all needs --json or --pretty. Default: SKILL.md. The skill is a folder: SKILL.md, which agents load when the skill triggers, and workflows.md, the step-by-step workflows SKILL.md points to. | | `--agents-md` | Print the compact AGENTS.md block instead of the skill. | Examples: ```bash purvey skill print purvey skill print --file workflows.md purvey skill print --file all --json purvey skill print --agents-md ``` ## purvey skill install Install the generated instructions for Claude Code, Agent Skills clients such as Codex and Cursor, or a repository AGENTS.md. Usage: `purvey skill install [options]` Access: None. Works without signing in. - Needs no credentials and makes no network calls. - Emits { target, scope, path, action, written, dryRun, cliVersion, bytes } as JSON on stdout; action is create, update, unchanged, append, or overwrite. - claude and agents also emit files: [{ file, path, action, written, bytes }] for SKILL.md and workflows.md. The top-level path is SKILL.md, action is the most significant file action (overwrite, update, create, then unchanged), written is true when any file was written, and bytes is the total. - agents-md also emits claudeCode: { visible, via, reason, claudeMdFiles, link? }. visible is false when a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the current directory or above it keeps Claude Code from reading AGENTS.md and none of them imports it; a warning then goes to stderr. - Re-running is safe: an identical file is left unchanged, an unedited file from an earlier CLI version is updated in place, and a missing workflows.md (for example after a SKILL.md-only install) is created. - A file with local edits, or one purvey did not write, is refused with exit 6 unless --force is passed. Every skill file is checked before any is written, so a refusal changes nothing. | Argument or flag | Details | | --- | --- | | `--target ` | Required. Where to install: claude (Claude Code), agents (Codex, Cursor, and other Agent Skills clients), or agents-md (this repository's AGENTS.md). claude: SKILL.md and workflows.md in ~/.claude/skills/purveyors/ (project scope: .claude/skills/purveyors/); use this for Claude Code, which loads skills only from .claude/skills. agents: SKILL.md and workflows.md in ~/.agents/skills/purveyors/, read by Codex, Cursor, and other Agent Skills clients (project scope: .agents/skills/purveyors/); Claude Code does not read .agents/. agents-md: ./AGENTS.md in the current directory; adds or refreshes one marked block and leaves the rest of the file alone. Claude Code reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the current directory or above it; see --link-claude-md. | | `--scope ` | user (your home directory) or project (the current directory); defaults to user, or project for agents-md. | | `--force` | Replace skill files or an AGENTS.md block that have local edits. | | `--dry-run` | Report the path and action without writing. | | `--link-claude-md` | agents-md only: add an @AGENTS.md import to ./CLAUDE.md so Claude Code loads the block. Appends one @AGENTS.md line to ./CLAUDE.md, or @../AGENTS.md to ./.claude/CLAUDE.md, and creates ./CLAUDE.md when neither exists. Only acts when a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md on the path hides AGENTS.md and none imports it; idempotent and honors --dry-run. Never edits CLAUDE.local.md or a CLAUDE.md in a parent directory. | Examples: ```bash purvey skill install --target claude purvey skill install --target agents --dry-run purvey skill install --target agents-md purvey skill install --target agents-md --link-claude-md ``` ## Related - [Set up your agent](https://www.purveyors.io/docs/agents/setup): The full install, sign-in, and skill setup flow. - [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group. --- Source: https://www.purveyors.io/docs/cli/market.md # Market commands > Market Index value signals, price movement, metadata trends, market overview, and named-lot evidence. HTML version: https://www.purveyors.io/docs/cli/market Check market value signals, price movement, metadata trends, and the evidence behind them. Summary views are open to everyone; filtered views require Parchment Intelligence access. Access: Varies by command. ## purvey market signals Actionable market value signals; unfiltered summary is a public teaser. Usage: `purvey market signals [options]` Access: None. Works without signing in. - --summary is the only view that works without credentials (counts only); every filter requires Parchment Intelligence access (exit 3 on denial). - --json emits the API response unchanged. | Argument or flag | Details | | --- | --- | | `--summary` | Return only signal counts; the one view that works without signing in or Parchment Intelligence. | | `--type ` | Signal types to include: price_drop, below_market, or value_quality; repeat the flag or separate with commas. Without it, all three. | | `--origin ` | Only signals for this origin (exact name). | | `--process ` | Only signals for this process group (exact name), such as washed. | | `--market ` | Which listings to read: retail, wholesale, or all. Default: retail. | | `--min-discount ` | Only signals at least this large, as a percent price drop or discount. | | `--min-score ` | Only coffees with at least this supplier-stated cupping score. | | `--window <7d\|30d>` | Time window for price-movement signals; value_quality signals are not time-windowed and always appear. Default: 30d. | | `--limit ` | Number of signals per page. Default: 20. Range: 1 to 100. | Examples: ```bash purvey market signals --summary --pretty purvey market signals --type price_drop --type below_market --origin "Ethiopia" --json ``` ## purvey market stats Price movement-significance stats; unfiltered retail slice is public. Usage: `purvey market stats [options]` Access: None. Works without signing in. - The view with no origin or process at market=retail works without credentials; origin, process, and wholesale views require Parchment Intelligence access. | Argument or flag | Details | | --- | --- | | `--origin ` | Only this origin (exact name). | | `--process ` | Only this process group (exact name), such as washed. | | `--market ` | Which listings to measure: retail, wholesale, or all. Default: retail. | | `--window <7d\|30d>` | Length of the price move being measured. Default: 7d. | | `--baseline-weeks ` | Weeks of history the move is compared against to judge how unusual it is. Default: 12. Range: 8 to 52. | Examples: ```bash purvey market stats --pretty purvey market stats --origin "Colombia" --window 30d --json ``` ## purvey market metadata Metadata-trend index; process/retail/month slice is public. Usage: `purvey market metadata [options]` Access: None. Works without signing in. - Public view: dimension=process, no origin, market=retail, grain=month; anything else requires Parchment Intelligence access. - variety and drying report the share of lots carrying each variety or drying method code (see `purvey catalog taxonomies`). A lot counts under every code it lists and under that code's family, so these shares overlap: they do not sum to 100% and counts must not be added (meta.bucketSemantics is "overlapping"). - In variety and drying, the undisclosed bucket is lots stating none; unmapped is lots stating one the vocabulary does not cover yet. | Argument or flag | Details | | --- | --- | | `--dimension ` | What to trend: process (process mix), disclosure (how much suppliers disclose), score (Purveyor Score), variety (variety mix), or drying (drying-method mix). Default: process. | | `--origin ` | Only this origin (exact name). | | `--market ` | Which listings to read: retail, wholesale, or all. Default: retail. | | `--grain ` | Size of each period in the trend. Default: month. | | `--from ` | First period to include, as YYYY-MM-DD. | | `--to ` | Last period to include, as YYYY-MM-DD. | Examples: ```bash purvey market metadata --pretty purvey market metadata --dimension score --origin "Ethiopia" --grain month --json purvey market metadata --dimension variety --market all --json ``` ## purvey market overview Aggregate-only green-coffee market overview over the public catalog. Usage: `purvey market overview` Access: Viewer. Any signed-in account. - Anonymous requests are rejected; any signed-in account or API key with catalog read access receives the same public evidence. - Emits the API response unchanged: daily change, coverage, movement, process distribution, and origin price distributions. Examples: ```bash purvey market overview --pretty ``` ## purvey market evidence Named arrivals, delistings, comparable lots, and supplier health and price ranges. Usage: `purvey market evidence` Access: Member. Requires member access on your account. - Requires Parchment Intelligence plus catalog read access (exit 3 on denial). Examples: ```bash purvey market evidence --json ``` ## Related - [Market Index](https://www.purveyors.io/analytics): The same market data as charts in the web app. - [Price index commands](https://www.purveyors.io/docs/cli/price-index): Aggregate price snapshots and matched comparisons. - [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group. --- Source: https://www.purveyors.io/docs/cli/price-index.md # Price index commands > Parchment Price Index snapshots, matched 30-day price comparisons, and chart history. HTML version: https://www.purveyors.io/docs/cli/price-index Read Parchment Price Index snapshots, matched 30-day price comparisons, and chart history for origins and processes. Access: Varies by command. ## purvey price-index Fetch Parchment Price Index aggregate snapshots. Usage: `purvey price-index [options]` Access: Member. Requires member access on your account. - Requires a scoped member API key with Parchment Price Index access. - PARCHMENT_API_KEY or PURVEYORS_API_KEY overrides the scoped API key stored by `purvey auth login`. - --from and --to accept ISO dates (YYYY-MM-DD); --wholesale accepts "true" or "false". | Argument or flag | Details | | --- | --- | | `--origin ` | Only this origin (case-insensitive exact name). | | `--process ` | Only this process (case-insensitive exact name), such as washed. | | `--grade ` | Only this grade (case-insensitive exact name). | | `--from ` | Only snapshots on or after this date, as YYYY-MM-DD. | | `--to ` | Only snapshots on or before this date, as YYYY-MM-DD. | | `--wholesale ` | true for wholesale prices only, false for retail only; without it, both. | | `--page ` | Page number, starting at 1. Default: 1. | | `--limit ` | Number of snapshots per page. Default: 100. Range: 1 to 100. | Examples: ```bash purvey price-index --pretty purvey price-index --origin "Ethiopia" --json purvey price-index --from 2026-01-01 --to 2026-06-30 --pretty ``` ## purvey price-index comparisons Available exact 30-day matched price comparisons with significance. Usage: `purvey price-index comparisons [options]` Access: Member. Requires member access on your account. - Requires Parchment Intelligence access. - Lists every origin with an exact 30-day matched comparison; an empty comparisons list means none qualify. - Each comparison carries significance unchanged; classification (quiet|normal|notable|exceptional) is null until eight baseline windows exist, meaning not enough history, never quiet. | Argument or flag | Details | | --- | --- | | `--wholesale ` | true for wholesale listings, false for retail, or all for both. Default: false. | Examples: ```bash purvey price-index comparisons --pretty purvey price-index comparisons --wholesale all --json ``` ## purvey price-index comparison Matched-listing price comparison for one origin between two exact dates. Usage: `purvey price-index comparison [options]` Access: Member. Requires member access on your account. - Requires Parchment Intelligence access. - status insufficient_fresh_coverage returns a null changePercent, never zero. | Argument or flag | Details | | --- | --- | | `--origin ` | Required. Origin to compare. | | `--from ` | Required. Starting date, as YYYY-MM-DD (UTC). | | `--to ` | Required. Ending date, as YYYY-MM-DD (UTC), within 365 days of --from. | | `--wholesale ` | true to compare wholesale listings, false for retail. Default: false. | Examples: ```bash purvey price-index comparison --origin "Ethiopia" --from 2026-08-31 --to 2026-09-30 --pretty ``` ## purvey price-index history Daily price-index history for charts; windows up to 90 days are public. Usage: `purvey price-index history [options]` Access: None. Works without signing in. - Windows up to 90 days (the default) run without credentials; 91-365 days require Parchment Intelligence access. | Argument or flag | Details | | --- | --- | | `--window-days ` | Number of past days to include; up to 90 works without signing in, longer windows need Parchment Intelligence. Default: 90. Range: 1 to 365. | | `--page ` | Page number, starting at 1. Default: 1. | | `--limit ` | Number of data points per page. Default: 100. Range: 1 to 10000. | | `--order ` | Date order: asc (oldest first) or desc (newest first). Default: asc. | Examples: ```bash purvey price-index history --pretty purvey price-index history --window-days 365 --limit 500 --json ``` ## Related - [Market commands](https://www.purveyors.io/docs/cli/market): Value signals and movement statistics. - [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group. --- Source: https://www.purveyors.io/docs/cli/procurement.md # Procurement commands > Read your saved sourcing briefs and the catalog coffees that match them. HTML version: https://www.purveyors.io/docs/cli/procurement Read the sourcing briefs you have saved and page through the catalog coffees that match them. Access: Member. Requires member access on your account. ## purvey procurement list List your saved sourcing briefs. Usage: `purvey procurement list` Access: Member. Requires member access on your account. - The CLI reads saved briefs; it does not create them. Examples: ```bash purvey procurement list --pretty ``` ## purvey procurement get Get a single saved sourcing brief by ID. Usage: `purvey procurement get ` Access: Member. Requires member access on your account. | Argument or flag | Details | | --- | --- | | `` | Required: ID of the saved sourcing brief. | Examples: ```bash purvey procurement get --pretty ``` ## purvey procurement matches Run a saved brief against the catalog and page through matches. Usage: `purvey procurement matches [options]` Access: Member. Requires member access on your account. | Argument or flag | Details | | --- | --- | | `` | Required: ID of the saved sourcing brief. | | `--page ` | Page number, starting at 1. Default: 1. | | `--limit ` | Number of matching coffees per page. Default: 25. Range: 1 to 100. | Examples: ```bash purvey procurement matches --pretty purvey procurement matches --page 2 --limit 50 --json ``` ## Related - [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group. --- Source: https://www.purveyors.io/docs/cli/reference-profile.md # Reference profile commands > Import, compare, adjust, save, and export Studio reference roast plans, from an Artisan file or a past roast, and download the original Artisan file. HTML version: https://www.purveyors.io/docs/cli/reference-profile Work with your saved references and plans: compare roasts against a reference, preview and save plan changes, export a plan as an Artisan file for your next batch, and download the Artisan file a reference was added from. Access: Member. Requires member access on your account. ## purvey reference-profile list List your Studio reference profiles. Usage: `purvey reference-profile list [options]` Access: Member. Requires member access on your account. - Requires a member credential and Studio access on your account. - artisanFileAvailable is true when reference-profile artisan-file can return the original Artisan file. | Argument or flag | Details | | --- | --- | | `--include-archived` | Also list reference profiles you have archived. | Examples: ```bash purvey reference-profile list --pretty ``` ## purvey reference-profile get Get one reference profile and its current revision. Usage: `purvey reference-profile get ` Access: Member. Requires member access on your account. - Use data.currentRevision.id for chart, preview, and save. | Argument or flag | Details | | --- | --- | | `` | Required: Reference profile UUID. | Examples: ```bash purvey reference-profile get 5ea1af6f-234c-43a9-9bf8-5678dd24f854 --pretty ``` ## purvey reference-profile chart Get the Artisan chart for a reference revision. Usage: `purvey reference-profile chart ` Access: Member. Requires member access on your account. | Argument or flag | Details | | --- | --- | | `` | Required: Reference profile UUID. | | `` | Required: Revision UUID belonging to the profile. | Examples: ```bash purvey reference-profile chart 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --pretty ``` ## purvey reference-profile import Upload an Artisan file as a private Studio reference profile. Usage: `purvey reference-profile import [options]` Access: Member. Requires member access on your account. - The uploaded file is parsed on purveyors.io and kept private to your account. - Reuse an explicit idempotency key to replay the same upload. - Import creates a reference profile, not executed roast history. | Argument or flag | Details | | --- | --- | | `` | Required: Path to an Artisan .alog or importer-supported JSON file. | | `--title ` | Title for the new reference profile. | | `--notes ` | Notes about the reference profile. | | `--idempotency-key ` | Key that makes retries safe: repeating the upload with the same key does not create a second profile. A new key is generated when omitted. | Examples: ```bash purvey reference-profile import ~/artisan/ethiopia.alog --title "Ethiopia baseline" ``` ## purvey reference-profile compare Compare two immutable roast or reference revisions with measured deltas. Usage: `purvey reference-profile compare [options]` Access: Member. Requires member access on your account. - Output is the comparison result unchanged. - profile:\ resolves the profile currentRevisionId; roast:\ resolves data.metadata.revision from roast chart data. - Both sides are aligned at charge; a reference profile is never executed roast history. | Argument or flag | Details | | --- | --- | | `` | Required: selector: revision:\, profile:\, roast:\, or roast:\@\. | | `` | Required: selector: revision:\, profile:\, roast:\, or roast:\@\. | | `--unit ` | Temperature unit for the compared series: F (Fahrenheit) or C (Celsius). Default: F. | | `--target-points ` | Number of samples in each aligned temperature series. Default: 400. Range: 50 to 1000. | Examples: ```bash purvey reference-profile compare roast:123 profile:5ea1af6f-234c-43a9-9bf8-5678dd24f854 --pretty purvey reference-profile compare roast:123 roast:124 --unit C --json ``` ## purvey reference-profile roasts List your past roasts that a plan can be built from. Usage: `purvey reference-profile roasts [options]` Access: Member. Requires member access on your account. - Lists roasts with an Artisan file on record; each entry has the roastId and roastRevision that preview-from-roast and from-roast accept, and the reference the roast is or would be saved under. - data.ineligibleRoastCount counts your other roasts: entered by hand, logged live, imported before Artisan files were kept, or holding a file too large for a reference. Those cannot be a plan base. - Requires a member credential and Studio access on your account. | Argument or flag | Details | | --- | --- | | `--limit ` | Number of roasts to list, newest first. Default: 15. Range: 1 to 50. | Examples: ```bash purvey reference-profile roasts --pretty ``` ## purvey reference-profile preview Preview bounded temperature adjustments without saving. Usage: `purvey reference-profile preview [options]` Access: Member. Requires member access on your account. - Request JSON contains title, optional notes, optional userGoal (600 chars), modelRecommendation (800), and userEdits (800) provenance, and changes.temperatureAdjustments; each adjustment has kind, startMilliseconds, endMilliseconds, and delta. - At most 12 adjustments are accepted; intervals must be ordered and each nonzero delta is bounded to -20 through 20. - The plan is recalculated from the unchanged parent revision; preview never saves anything. | Argument or flag | Details | | --- | --- | | `` | Required: Reference profile UUID. | | `` | Required: Revision UUID to adjust; it is never changed. | | `--request ` | Required. JSON file with a title and up to 12 temperature adjustments; save accepts the same file. | Examples: ```bash purvey reference-profile preview 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --request changes.json --pretty ``` ## purvey reference-profile preview-from-roast Preview a plan built from one of your past roasts without saving. Usage: `purvey reference-profile preview-from-roast [options]` Access: Member. Requires member access on your account. - Nothing is saved and the roast is not changed. The result is a plan, never a roast you ran. - data.parentProfileId and data.parentRevisionId name the reference this roast is saved under; data.parentSaved says whether from-roast --artisan-source has saved it yet. - A roast with no Artisan file on record exits 2 with a message that says why and what to do next. | Argument or flag | Details | | --- | --- | | `` | Required: ID of a past roast with an Artisan file on record. | | `--request ` | Required. JSON file with a title and up to 12 temperature adjustments; preview and save accept the same file. | | `--roast-revision ` | The roast's revision from reference-profile roasts, to plan from exactly the roast you looked at. The roast's current revision is used when omitted. | Examples: ```bash purvey reference-profile preview-from-roast 4529 --request changes.json --pretty ``` ## purvey reference-profile from-roast Save one of your past roasts as a reference profile. Usage: `purvey reference-profile from-roast [options]` Access: Member. Requires member access on your account. - With --artisan-source, saving the same roast again returns the reference already saved from it. Pass data.id and data.currentRevisionId to save to store the plan. - The roast is never changed, and the reference is not a second roast. - A roast with no Artisan file on record exits 2 with a message that says why and what to do next. | Argument or flag | Details | | --- | --- | | `` | Required: ID of the past roast to save as a reference. | | `--artisan-source` | Keep the roast's Artisan file with the reference so a plan can be built from it. Without this flag the reference is a chart for comparison only. | | `--roast-revision ` | The roast's revision from reference-profile roasts, to save exactly the roast you looked at. The roast's current revision is used when omitted. | | `--title ` | Title for the reference profile. | | `--notes ` | Notes about the reference profile. | | `--idempotency-key ` | Key that makes retries safe: repeating the command with the same key does not create a second reference. A new key is generated when omitted. | Examples: ```bash purvey reference-profile from-roast 4529 --artisan-source --pretty ``` ## purvey reference-profile save Save changes as a new immutable generated reference plan. Usage: `purvey reference-profile save [options]` Access: Member. Requires member access on your account. - Reuse an explicit idempotency key to replay the same save. - To plan from a past roast, run from-roast --artisan-source first and pass the profile and revision ids it returns. - Generated references are plans and never create executed roast history. | Argument or flag | Details | | --- | --- | | `` | Required: Reference profile UUID. | | `` | Required: Revision UUID the new plan is based on; it is never changed. | | `--request ` | Required. The same JSON request file you previewed. | | `--idempotency-key ` | Key that makes retries safe: repeating the save with the same key does not create a second plan. A new key is generated when omitted. | Examples: ```bash purvey reference-profile save 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --request changes.json --pretty ``` ## purvey reference-profile export Download a saved generated reference as an unsigned Artisan .alog plan. Usage: `purvey reference-profile export [options]` Access: Member. Requires member access on your account. - Only a saved generated revision can be exported; output is a local file plus a JSON receipt. - The CLI does not claim verified Artisan 4.2 playback compatibility. | Argument or flag | Details | | --- | --- | | `` | Required: UUID of a saved generated reference profile. | | `` | Required: UUID of the saved generated revision. | | `--output ` | Required. Path to write the .alog file to. | | `--force` | Overwrite the output file if it already exists. | Examples: ```bash purvey reference-profile export 0b7e9f52-3c61-4d8a-9e24-6f1a8c3d5b90 c43a1d7e-95b2-4e06-8f7c-1d2b3a4e5f68 --output ~/artisan/next-batch.alog ``` ## purvey reference-profile artisan-file Download the Artisan file a reference was uploaded or saved from, exactly as stored. Usage: `purvey reference-profile artisan-file [options]` Access: Member. Requires member access on your account. - Writes the file byte for byte, checks it against its SHA-256, and prints a JSON receipt: data.path, data.bytes, data.sha256. A file that fails the check is removed. - Requires Studio access on your account; API keys need the roast:read scope. - A reference has an original file when artisanFileAvailable is true in reference-profile list. A planned profile has none; download it with reference-profile export. | Argument or flag | Details | | --- | --- | | `` | Required: Reference profile UUID. | | `--output ` | File to write, or an existing folder to save the file in under its original name. Defaults to the current folder. | | `--force` | Overwrite the output file if it already exists. | Examples: ```bash purvey reference-profile artisan-file 5ea1af6f-234c-43a9-9bf8-5678dd24f854 --output ~/artisan/ ``` ## Related - [Roast commands](https://www.purveyors.io/docs/cli/roast): Import the roasts you compare against references. - [Saved references and plans](https://www.purveyors.io/roast/saved): The same library in the web app. - [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group. --- Source: https://www.purveyors.io/docs/cli/context-manifest.md # Context and manifest > Get a readable command reference or the full machine-readable contract for the CLI version you have installed. HTML version: https://www.purveyors.io/docs/cli/context-manifest purvey context prints a compact, readable reference that suits people and language models. purvey manifest prints the same contract as stable JSON for scripts and tools. Both describe exactly the version you have installed and work without signing in. ## Which one to use | Need | Use | Notes | | --- | --- | --- | | A readable reference | purvey context | Plain text covering access rules, the ID map, workflows, and common errors. | | A machine-readable contract | purvey manifest | Stable JSON on standard output. Add --pretty for indented output. | | JSON from an existing context caller | purvey context --json | Prints the same contract as purvey manifest. | | The contract inside a Node.js tool | @purveyors/cli/manifest | Import getCliManifest() to read the same contract in-process. | ## purvey context Print a dense human-readable CLI reference, or the manifest as JSON. Usage: `purvey context [options]` Access: None. Works without signing in. - Use `purvey context` for dense human-readable operator reference text. - Prefer `purvey manifest` for the stable machine-readable CLI contract. - Use `purvey context --json` only for compatibility with existing context-based callers. - Use `@purveyors/cli/manifest` for the same contract in-process. | Argument or flag | Details | | --- | --- | | `--json` | Print the machine-readable manifest as compact JSON instead of the text reference. | | `--pretty` | Print the machine-readable manifest as indented JSON instead of the text reference. | Examples: ```bash purvey context purvey context --json purvey context --pretty ``` ## purvey manifest Print the stable machine-readable CLI contract as JSON. Usage: `purvey manifest [options]` Access: None. Works without signing in. - `purvey manifest` is the preferred machine-readable entrypoint and emits compact JSON by default. - `purvey context --json` remains available for compatibility with existing context-based callers. - The same contract is available in-process via `@purveyors/cli/manifest`. | Argument or flag | Details | | --- | --- | | `--json` | Print the manifest as compact JSON, the default. | | `--pretty` | Print the manifest as indented JSON. | Examples: ```bash purvey manifest purvey manifest --pretty ``` ## Related - [Agent integration](https://www.purveyors.io/docs/cli/agent-integration): Patterns for AI agents that use the CLI. - [Auth, config, and output](https://www.purveyors.io/docs/cli/auth-output): Output modes, exit codes, and the ID reference. --- Source: https://www.purveyors.io/docs/cli/agent-integration.md # Agent integration > Let AI agents search the catalog, keep your records, and read market data on your behalf. HTML version: https://www.purveyors.io/docs/cli/agent-integration Any AI agent that can run shell commands, such as Claude Code, Codex, Cursor, or OpenClaw, can use purvey to work with your Purveyors data. Commands return structured JSON when asked with --json, report a clear exit code, and state the access they need, so an agent can act and recover from errors without guessing. The fastest way to connect an agent is the setup prompt on this page. Your agent installs the CLI, asks you to approve sign-in in your browser, and installs the Purveyors skill. ## What your agent can do - Find coffees: search and rank the catalog by origin, process, price, score, and freshness, compare suppliers, and find similar lots. - Keep records: add inventory, import Artisan roasts, record sales, and log cupping scores. - Watch the market: check value signals, price movement, and Price Index comparisons. - Plan roasts: compare roasts with your saved references and export the next plan to Artisan. ## Your account stays in your hands - You approve sign-in in your own browser. Your agent never sees your password and never needs an API key from you. - The CLI stores a key for the machine that requested it. You can revoke it at any time from your API keys in the Parchment Console. - Each command reference lists the access it needs, so your agent can tell you up front when a task needs a different plan. ## Patterns that work well - Install the Purveyors skill with purvey skill install so your agent knows the commands, ID types, and output rules before it starts. - Have the agent read purvey context for a compact reference, or purvey manifest for the full machine-readable contract of the installed version. - Pass --json to every command you parse. Most commands print JSON by default, but purvey context prints readable text, and in an interactive terminal so do purvey auth status and purvey config list. - Rely on exit codes: 3 means sign-in or access is missing, 2 means a bad argument, and 4 means the record was not found. - Keep ID types straight. Catalog IDs, inventory IDs, roast IDs, and sale IDs are different; the ID reference shows which command takes which. - Building an application rather than an agent? Use the Parchment API and @purveyors/sdk, documented at https://api.purveyors.io/docs. A typical agent session: ```bash purvey auth status --json purvey catalog search --origin "Ethiopia" --stocked --limit 5 --json purvey inventory list --stocked --json ``` ## Agents without a shell Chat apps that cannot run commands, such as Claude Desktop and ChatGPT, cannot use the CLI yet. You can still give them the documentation: https://purveyors.io/llms-full.txt contains every docs page in one file. ## Related - [Set up your agent](https://www.purveyors.io/docs/agents/setup): The step-by-step setup your agent follows. - [Context and manifest](https://www.purveyors.io/docs/cli/context-manifest): Readable and machine-readable references for agents. - [Auth, config, and output](https://www.purveyors.io/docs/cli/auth-output): Exit codes, error envelopes, and the ID reference. --- Source: https://www.purveyors.io/docs/agents/setup.md # Set up your agent > Install the Purveyors CLI, sign in with browser approval, and give your AI agent the Purveyors skill. HTML version: https://www.purveyors.io/docs/agents/setup These steps are written for an AI agent with shell access, such as Claude Code, Codex, Cursor, or OpenClaw, working on behalf of a person. A person can follow them too. Agents without a shell, such as Claude Desktop and ChatGPT, cannot complete this setup yet. Work through the steps in order. Only step 2 needs the person: they approve sign-in in their browser. ## Before you start - The machine needs Node.js 20 or later with npm. Check with node --version. - The person you are helping needs a Purveyors account and a web browser. The browser does not have to be on this machine. - Never ask the person for an API key, password, or token, and never paste credentials into the conversation. Sign-in happens in their browser. ## Step 1: Install the CLI Install the CLI globally with npm, then confirm it runs. - purvey --version should print a version number. If the shell cannot find purvey, see Troubleshooting below. Install and confirm: ```bash npm install -g @purveyors/cli purvey --version ``` ## Step 2: Sign in with browser approval Run `purvey auth login --headless`. It prints a purveyors.io approval link, then waits until the person approves. - Keep the command running while you wait. If your shell tool only shows output after a command exits, start it in the background, write its output to a file, and read the link from that file. - Send the link to the person and ask them to open it, sign in, and approve access. - After approval, the command finishes on its own and prints the signed-in email. Nothing needs to be copied back. - The link expires after about 10 minutes. If it expires, run the command again for a fresh link. Start sign-in: ```bash purvey auth login --headless ``` If your shell waits for commands to exit (macOS and Linux): ```bash purvey auth login --headless > /tmp/purvey-login.log 2>&1 & sleep 3; cat /tmp/purvey-login.log ``` Message to send the person: ```text Please open this link, sign in to Purveyors, and approve access for this machine: Tell me when you are done. ``` > **Never ask for an API key** > > Do not ask the person for an API key, password, or session token, and do not accept one pasted into the conversation. Browser approval gives the CLI its own key, stored only on this machine. ## Step 3: Confirm the sign-in Run `purvey auth status --json`. - Success prints JSON with "authenticated": true, the account email, and its role, and exits with code 0. - If it prints "authenticated": false and exits with code 3, repeat step 2. Check status: ```bash purvey auth status --json ``` ## Step 4: Install the Purveyors skill The skill teaches your agent the Purveyors commands, ID types, output rules, and step-by-step workflows. Pick the command for the agent you are running in: `--target claude` if you are Claude Code, `--target agents` if you are Codex, Cursor, or another Agent Skills tool. Installing the skill needs no sign-in or network access. - Claude Code loads skills only from its own skills folder, so use `--target claude` there even if the project also has an `.agents` folder. - The skill installs for your user by default. Add --scope project to install it for the current project only. - The skill is a folder with two files: SKILL.md, the guide your agent loads first, and workflows.md, step-by-step command sequences it reads before a multi-step task. The command writes both. - Add --dry-run to see where the files will go without writing them. - Running the command again is safe. It updates both files in place and leaves a file you edited alone unless you pass --force. - Start a new agent session if the skill does not appear right away. | Agent | Command | | --- | --- | | Claude Code | `purvey skill install --target claude` | | Codex, Cursor, or another Agent Skills tool | `purvey skill install --target agents` | ## Step 5: Run a first command Run a catalog search to confirm everything works. - This returns five currently stocked Ethiopian green coffees with prices and suppliers. Summarize them for the person. - Then tell the person setup is complete and offer next steps: compare coffees, track inventory, import roasts, or check market prices. - For every command, run purvey context or read https://purveyors.io/docs/cli/overview. Find stocked Ethiopian coffees: ```bash purvey catalog search --origin "Ethiopia" --stocked --limit 5 --pretty ``` ## Optional: add Purveyors to a project To give every agent that works in one repository the Purveyors basics, run this from the project's root folder. It adds a short, marked Purveyors section to AGENTS.md and leaves the rest of the file alone. It changes files in the person's repository, so ask them first. - Codex, Cursor, and other agents that read AGENTS.md pick up the section directly. - Claude Code reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the project folder or any folder above it. `--link-claude-md` adds a one-line `@AGENTS.md` import to the project CLAUDE.md, creating one if needed, so Claude Code reads the section too. It never edits CLAUDE.local.md or a CLAUDE.md outside the project. - Without `--link-claude-md`, only AGENTS.md changes. If Claude Code would not see the section, the JSON output shows `"claudeCode": { "visible": false }` and a warning names the CLAUDE.md files that hide it. - Running it again is safe, and `--dry-run` shows every file it would change without writing. Add the Purveyors section to AGENTS.md: ```bash purvey skill install --target agents-md --link-claude-md ``` ## Troubleshooting | Problem | What to do | | --- | --- | | purvey: command not found | npm's global folder is not on PATH. Run npm prefix -g, add its bin folder to PATH, or open a new shell. | | EACCES or permission denied during install | Install Node.js with a version manager such as nvm, or set a user-owned npm prefix. Use sudo only if the person approves. | | Unsupported engine or syntax errors on start | Upgrade to Node.js 20 or later. | | The approval link expired | Run purvey auth login --headless again and send the new link. | | purvey auth status says not logged in | Repeat step 2. If PARCHMENT_API_KEY or PURVEYORS_API_KEY is set, it takes priority over browser sign-in; unset it unless the person wants to use that key. | | A command exits with code 3 after sign-in | That command needs access the account does not have. Tell the person which command failed; the command's reference page lists the access it needs. | | The CLI reports unknown command 'skill' | Update the CLI with npm install -g @purveyors/cli@latest, then run step 4 again. | | Your agent cannot run shell commands | This setup needs a shell. Use the Purveyors web app at https://purveyors.io instead. | ## Related - [CLI overview](https://www.purveyors.io/docs/cli/overview): Every command group and common workflows. - [Agent integration](https://www.purveyors.io/docs/cli/agent-integration): What agents can do with Purveyors and patterns that work well. - [Auth, config, and output](https://www.purveyors.io/docs/cli/auth-output): Exit codes, error envelopes, and the ID reference.