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 launches the browser OAuth flow. purvey auth login --headless prints a URL and expects a pasted callback URL, which is better for agents and remote hosts.
- purvey auth status does not require an existing valid session. It reports authenticated state, role, and token timing when available.
- Catalog commands require the viewer role. Inventory, roast, sales, and tasting commands require the member role.
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 login, expired session, or insufficient role.
- 5 represents dependency conflicts such as inventory deletion without --force when dependent roasts or sales exist.
- 6 represents local config problems.