Operational contract
Auth, config, and output
How purvey signs in, which commands need which access, where settings live, and how output, errors, and exit codes work.
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. |
purvey auth login
purvey auth login --headlesspurvey 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. |
purvey auth status
purvey auth status --pretty
purvey auth status --jsonpurvey 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).
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.
purvey auth logoutAccess 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 contextprints dense human-readable operator reference text unless --json or --pretty is passed. -
purvey manifestis the preferred machine-readable contract and always emits it on stdout. -
purvey context --jsonstays available for compatibility parity with existing context-based callers. -
@purveyors/cli/manifestexposes the same machine-readable contract for in-process consumers. -
purvey config list/get/set/resetstay 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 <bean-id>, 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:<roast-id>, 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:<uuid>, 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:<uuid>, 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.
purvey config list
purvey config list --jsonpurvey config get
Get a config value.
Usage: purvey config get <key>
Access: None. Works without signing in.
- Interactive terminals print the raw value with no decorators.
- Machine mode emits {"<key>": value|null}.
- --csv is not supported on config commands.
| Argument or flag | Details |
|---|---|
<key> | Required: Config key. |
purvey config get form-mode
purvey config get form-mode --jsonpurvey config set
Set a config value.
Usage: purvey config set <key> <value>
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 |
|---|---|
<key> | Required: Config key. |
<value> | Required: Config value. |
purvey config set form-mode true
purvey config set form-mode true --jsonpurvey 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.
purvey config reset
purvey config reset --json