@purveyors/cli
CLI overview
The Parchment CLI is a terminal interface for catalog queries, inventory management, roasting workflows, scripting, and agent automation.
The Parchment CLI (purvey) provides terminal access to the same coffee domain model as the web app. Catalog commands require an authenticated viewer session. Inventory, roast, sales, and tasting commands additionally require the member role.
Not every command requires auth. auth, config, context, and manifest are onboarding or local utility surfaces. context prints dense human-readable reference text by default, while manifest emits the machine-readable contract directly.
Install and first-run flow
- Use purvey auth login for browser OAuth or purvey auth login --headless on servers, CI, and agent hosts.
- Run purvey auth status to confirm both session health and current role before scripting against viewer-only or member-only commands.
- Use purvey manifest when a wrapper needs the machine-readable contract directly. Use purvey context when a human or model should read the dense reference text first.
npm install -g @purveyors/cli
purvey auth login
purvey auth status --prettypurvey auth login --headless
purvey context
purvey manifest --prettyCommand groups and auth model
| Group | Examples | Auth |
|---|---|---|
| auth | login, status, logout | None |
| catalog | search, get, stats, similar | Authenticated viewer session |
| inventory / roast / sales / tasting | Personal data and write workflows | Authenticated member session |
| config | list, get, set, reset | None, local-only |
| context / manifest | Dense reference text and machine-readable contract | None |
Catalog commands are authenticated, even though the HTTP API supports anonymous reads
The CLI intentionally requires a signed-in viewer session for catalog commands. For anonymous or API-key-based integrations, use GET /v1/catalog instead of shelling out to the CLI.
Output contract
- Most commands write compact JSON to stdout by default. --json is an explicit alias for that mode, while --pretty prints indented JSON and --csv exports array-shaped results where supported.
- Operational messages and fatal errors stay on stderr so stdout remains safe for pipes, jq, and redirect-based automation.
- Interactive terminals without an explicit output flag can still show human-readable success or error text. When piped or redirected, the CLI falls back to structured JSON output and JSON error envelopes.
- purvey auth status is the main exception worth remembering: in an interactive TTY it prints human-readable status unless you force --json, --pretty, or --csv.
When to use the CLI vs. the API vs. the web app
- Use the CLI for scripts, terminal-first operations, and agent workflows that benefit from a stable documented command surface.
- Use GET /v1/catalog for external integrations that need a stable HTTP contract, anonymous access, or API-key auth without a stored user session.
- Use the web app for charts, dashboards, and interactive exploration.