@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. purvey auth login uses browser OAuth once to create and persist a scoped Parchment API key; the CLI does not retain an ongoing viewer session. Basic catalog commands require catalog:read; structured process filters and catalog similar additionally require member-level access, with similar also available to explicit API Origin/Enterprise keys. Inventory, roast, sales, and tasting commands require the matching member role and key scopes.
Not every command requires auth. auth, config, context, and manifest are onboarding or local utility surfaces. purvey context is the dense human-readable reference, while purvey manifest is the preferred machine-readable contract.
Install and first-run flow
- Use purvey auth login for browser OAuth or purvey auth login --headless on servers, CI, and agent hosts.
- purvey auth login opens a request-specific browser consent page where you review the machine name and requested scopes before authorizing. The CLI receives the scoped Parchment API key directly; the browser never displays the key.
- Run purvey auth status to confirm the stored API key is valid and inspect its account email, role, key ID, and creation time before scripting against basic catalog or member-level commands.
- PARCHMENT_API_KEY or the PURVEYORS_API_KEY compatibility alias overrides the key stored by purvey auth login for command execution.
- Use purvey manifest when a wrapper needs the preferred machine-readable contract. Use purvey context when a human or model should read the dense reference text first, or use purvey context --json / --pretty when an existing caller needs manifest-parity output.
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 | API key with catalog:read; structured process filters require member access |
| catalog | similar | API Origin/Enterprise key with catalog:read |
| inventory / roast / sales / tasting | Personal data and write workflows | Member-owned API key with matching scopes |
| config | list, get, set, reset | None, local-only |
| context / manifest | Dense reference text and machine-readable contract | None |
Catalog commands use scoped API-key authentication
purvey auth login creates and stores an account-linked scoped Parchment API key for CLI commands. Set PARCHMENT_API_KEY or PURVEYORS_API_KEY to use an explicit key instead. Direct Parchment catalog and entitled calls also require a Bearer credential; public no-login catalog discovery lives in the Purveyors web catalog, while designated Market Index teaser slices remain anonymous.
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
- CLI login is a one-time OAuth bootstrap that exchanges the browser session for a scoped Parchment API key. The CLI and direct API are credentialed surfaces; the public no-login discovery surface is https://purveyors.io/catalog.
| Surface | Choose it when | Auth expectation |
|---|---|---|
| purvey catalog | A terminal, script, or agent is acting with scoped account access | Stored or explicit Parchment API key |
| Purveyors web catalog | The goal is public discovery, evaluation, or a zero-setup demo | No user login; coffee-app uses its server-held demo key upstream |
| API-key GET https://api.purveyors.io/v1/catalog | The integration needs production usage visibility, quotas, or server-to-server auth | Bearer API key required |
| Web app | A human wants visual exploration, dashboards, or account workflows | Browser session as needed |
Related links
Roles, local config, stderr/stdout guarantees, and exit-code expectations.
Text-first onboarding, manifest output, and wrapper guidance for agents.
The generated OpenAPI reference for the deployed Parchment API that complements the CLI.