Agent workflows

Agent integration

Let AI agents search the catalog, keep your records, and read market data on your behalf.

Any AI agent that can run shell commands, such as Claude Code, Codex, Cursor, or OpenClaw, can use purvey to work with your Purveyors data. Commands return structured JSON when asked with --json, report a clear exit code, and state the access they need, so an agent can act and recover from errors without guessing.

The fastest way to connect an agent is the setup prompt on this page. Your agent installs the CLI, asks you to approve sign-in in your browser, and installs the Purveyors skill.

View as Markdown

For AI agents

Set up your agent

Paste this into Claude Code, Codex, Cursor, or any agent that can run commands. It installs the Purveyors CLI, asks you to approve sign-in in your browser, and adds the Purveyors skill.

Read https://purveyors.io/docs/agents/setup.md and follow it to install the Purveyors CLI, sign me in, and install the Purveyors skill.

Agents that cannot run commands, such as Claude Desktop and ChatGPT, cannot complete this setup yet. Read the setup steps.

What your agent can do

  • Find coffees: search and rank the catalog by origin, process, price, score, and freshness, compare suppliers, and find similar lots.
  • Keep records: add inventory, import Artisan roasts, record sales, and log cupping scores.
  • Watch the market: check value signals, price movement, and Price Index comparisons.
  • Plan roasts: compare roasts with your saved references and export the next plan to Artisan.

Your account stays in your hands

  • You approve sign-in in your own browser. Your agent never sees your password and never needs an API key from you.
  • The CLI stores a key for the machine that requested it. You can revoke it at any time from your API keys in the Parchment Console.
  • Each command reference lists the access it needs, so your agent can tell you up front when a task needs a different plan.

Patterns that work well

  • Install the Purveyors skill with purvey skill install so your agent knows the commands, ID types, and output rules before it starts.
  • Have the agent read purvey context for a compact reference, or purvey manifest for the full machine-readable contract of the installed version.
  • Pass --json to every command you parse. Most commands print JSON by default, but purvey context prints readable text, and in an interactive terminal so do purvey auth status and purvey config list.
  • Rely on exit codes: 3 means sign-in or access is missing, 2 means a bad argument, and 4 means the record was not found.
  • Keep ID types straight. Catalog IDs, inventory IDs, roast IDs, and sale IDs are different; the ID reference shows which command takes which.
  • Building an application rather than an agent? Use the Parchment API and @purveyors/sdk, documented at https://api.purveyors.io/docs.
A typical agent session
purvey auth status --json
purvey catalog search --origin "Ethiopia" --stocked --limit 5 --json
purvey inventory list --stocked --json

Agents without a shell

Chat apps that cannot run commands, such as Claude Desktop and ChatGPT, cannot use the CLI yet. You can still give them the documentation: https://purveyors.io/llms-full.txt contains every docs page in one file.

Related links

Set up your agent

The step-by-step setup your agent follows.

Context and manifest

Readable and machine-readable references for agents.

Auth, config, and output

Exit codes, error envelopes, and the ID reference.