@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 even though GET /v1/catalog supports anonymous and API-key access. 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. 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 both session health and current role before scripting against viewer-only or member-only commands.
- 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, 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 so terminal workflows stay account-linked and predictable. For anonymous discovery or API-key production 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
- CLI login is intentional product behavior, not a contradiction of the HTTP API. The CLI is an account-linked tool surface; /v1/catalog is the public network surface.
| Surface | Choose it when | Auth expectation |
|---|---|---|
| purvey catalog | A terminal, script, or agent is acting on behalf of a signed-in account | Viewer session required |
| Anonymous GET /v1/catalog | The goal is public discovery, evaluation, or a zero-setup demo | None |
| API-key GET /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 |