Operational contract
CLI auth, config, and output
Authentication roles, local config, output modes, stderr/stdout rules, and scripting expectations for the Parchment CLI.
This page is the practical contract for running purvey in scripts, CI, agent harnesses, and local terminals. It covers which commands require auth, what config exists today, and how output behaves across interactive and non-interactive modes.
If you automate against purvey, treat stdout and stderr semantics as part of the interface, not just the command names.
Authentication commands
- purvey auth login opens the browser consent flow. Review the requesting machine and scopes at /auth/cli, authorize the request, and return to the terminal; the CLI exchanges its private verifier for the scoped Parchment API key.
- purvey auth login --headless prints the consent URL for agents, CI, containers, and remote hosts. Open it in any browser and authorize the request; the browser approval completes the sign-in without a manual URL handoff.
- Login uses the OAuth session only to mint a machine-named scoped Parchment API key. The CLI stores that key plus non-secret identity metadata, not session access or refresh tokens.
- purvey auth status validates the stored API key. On success it reports authenticated state, account email, role, key ID, and key creation time; an invalid or revoked key is reported as unauthenticated.
- Catalog search, get, and stats require catalog:read; structured process filters require member access. Catalog similar additionally requires a member-owned key or an API Origin/Enterprise key. Inventory, roast, sales, and tasting require the member role and matching key scopes.
Login and status
purvey auth login
purvey auth login --headless
purvey auth status --json
purvey auth logoutLocal config
- Today the primary supported key is form-mode, stored in ~/.config/purvey/config.json.
- When form-mode is true, several write commands can enter guided form mode automatically when required flags are missing.
- Config commands are local-only and do not require authentication.
| Command | Notes |
|---|---|
| purvey config list | Show all stored config values. |
| purvey config get <key> | Print the raw value to stdout for scripting. |
| purvey config set <key> <value> | Persist a config value locally. |
| purvey config reset | Clear config back to defaults. |
Stdout and stderr behavior
- Compact JSON on stdout is the default success shape for most commands.
- --pretty keeps JSON but formats it for human reading. --csv changes successful stdout only and only on commands that support CSV-shaped output.
- Info messages, confirmations, spinner text, and fatal errors go to stderr so stdout can stay script-friendly.
- With --json, --pretty, --csv, or non-interactive piping, fatal errors become JSON envelopes on stderr. Interactive no-flag sessions may show human-readable fatal errors instead.
Script-friendly usage
purvey inventory list | jq '.[].id'
purvey sales list --csv > sales.csv
purvey auth status 2>/dev/null | jq -r '.email'Exit-code expectations
- 0 means success.
- 3 is the important automation code for auth failures, including missing or revoked credentials and insufficient role or entitlement.
- 5 represents dependency conflicts such as inventory deletion without --force when dependent roasts or sales exist.
- 6 represents local config problems.