@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.
- Headed purvey auth login also supports a pasted callback URL when a browser opens on a different machine, localhost is unreachable, or the automatic callback fails. That manual fallback is intentional for SSH, containers, and agent hosts, not a degraded path.
- 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. For anonymous discovery, call GET https://api.purveyors.io/v1/catalog directly.
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 is an account-linked tool surface; https://api.purveyors.io/v1/catalog is the public network surface.
| 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 |
| Anonymous GET https://api.purveyors.io/v1/catalog | The goal is public discovery, evaluation, or a zero-setup demo | None |
| 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.