For AI agents

Set up your agent

Install the Purveyors CLI, sign in with browser approval, and give your AI agent the Purveyors skill.

These steps are written for an AI agent with shell access, such as Claude Code, Codex, Cursor, or OpenClaw, working on behalf of a person. A person can follow them too.

Agents without a shell, such as Claude Desktop and ChatGPT, cannot complete this setup yet.

Work through the steps in order. Only step 2 needs the person: they approve sign-in in their browser.

View as Markdown

For AI agents

Give your agent this prompt

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.

Before you start

The machine needs Node.js 20 or later with npm. Check with node --version.
The person you are helping needs a Purveyors account and a web browser. The browser does not have to be on this machine.
Never ask the person for an API key, password, or token, and never paste credentials into the conversation. Sign-in happens in their browser.

Step 1: Install the CLI

Install the CLI globally with npm, then confirm it runs.

purvey --version should print a version number. If the shell cannot find purvey, see Troubleshooting below.

Install and confirm

npm install -g @purveyors/cli
purvey --version

Step 2: Sign in with browser approval

Run purvey auth login --headless. It prints a purveyors.io approval link, then waits until the person approves.

Keep the command running while you wait. If your shell tool only shows output after a command exits, start it in the background, write its output to a file, and read the link from that file.
Send the link to the person and ask them to open it, sign in, and approve access.
After approval, the command finishes on its own and prints the signed-in email. Nothing needs to be copied back.
The link expires after about 10 minutes. If it expires, run the command again for a fresh link.

Start sign-in

purvey auth login --headless

If your shell waits for commands to exit (macOS and Linux)

purvey auth login --headless > /tmp/purvey-login.log 2>&1 &
sleep 3; cat /tmp/purvey-login.log

Message to send the person

Please open this link, sign in to Purveyors, and approve access for this machine:
<approval link>
Tell me when you are done.

Never ask for an API key

Do not ask the person for an API key, password, or session token, and do not accept one pasted into the conversation. Browser approval gives the CLI its own key, stored only on this machine.

Step 3: Confirm the sign-in

Run purvey auth status --json.

Success prints JSON with "authenticated": true, the account email, and its role, and exits with code 0.
If it prints "authenticated": false and exits with code 3, repeat step 2.

Check status

purvey auth status --json

Step 4: Install the Purveyors skill

The skill teaches your agent the Purveyors commands, ID types, output rules, and step-by-step workflows. Pick the command for the agent you are running in: --target claude if you are Claude Code, --target agents if you are Codex, Cursor, or another Agent Skills tool. Installing the skill needs no sign-in or network access.

Claude Code loads skills only from its own skills folder, so use --target claude there even if the project also has an .agents folder.
The skill installs for your user by default. Add --scope project to install it for the current project only.
The skill is a folder with two files: SKILL.md, the guide your agent loads first, and workflows.md, step-by-step command sequences it reads before a multi-step task. The command writes both.
Add --dry-run to see where the files will go without writing them.
Running the command again is safe. It updates both files in place and leaves a file you edited alone unless you pass --force.
Start a new agent session if the skill does not appear right away.

Agent	Command
Claude Code	`purvey skill install --target claude`
Codex, Cursor, or another Agent Skills tool	`purvey skill install --target agents`

Step 5: Run a first command

Run a catalog search to confirm everything works.

This returns five currently stocked Ethiopian green coffees with prices and suppliers. Summarize them for the person.
Then tell the person setup is complete and offer next steps: compare coffees, track inventory, import roasts, or check market prices.
For every command, run purvey context or read https://purveyors.io/docs/cli/overview.

Find stocked Ethiopian coffees

purvey catalog search --origin "Ethiopia" --stocked --limit 5 --pretty

Optional: add Purveyors to a project

To give every agent that works in one repository the Purveyors basics, run this from the project's root folder. It adds a short, marked Purveyors section to AGENTS.md and leaves the rest of the file alone. It changes files in the person's repository, so ask them first.

Codex, Cursor, and other agents that read AGENTS.md pick up the section directly.
Claude Code reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the project folder or any folder above it. --link-claude-md adds a one-line @AGENTS.md import to the project CLAUDE.md, creating one if needed, so Claude Code reads the section too. It never edits CLAUDE.local.md or a CLAUDE.md outside the project.
Without --link-claude-md, only AGENTS.md changes. If Claude Code would not see the section, the JSON output shows "claudeCode": { "visible": false } and a warning names the CLAUDE.md files that hide it.
Running it again is safe, and --dry-run shows every file it would change without writing.

Add the Purveyors section to AGENTS.md

purvey skill install --target agents-md --link-claude-md

Troubleshooting

Problem	What to do
purvey: command not found	npm's global folder is not on PATH. Run npm prefix -g, add its bin folder to PATH, or open a new shell.
EACCES or permission denied during install	Install Node.js with a version manager such as nvm, or set a user-owned npm prefix. Use sudo only if the person approves.
Unsupported engine or syntax errors on start	Upgrade to Node.js 20 or later.
The approval link expired	Run purvey auth login --headless again and send the new link.
purvey auth status says not logged in	Repeat step 2. If PARCHMENT_API_KEY or PURVEYORS_API_KEY is set, it takes priority over browser sign-in; unset it unless the person wants to use that key.
A command exits with code 3 after sign-in	That command needs access the account does not have. Tell the person which command failed; the command's reference page lists the access it needs.
The CLI reports unknown command 'skill'	Update the CLI with npm install -g @purveyors/cli@latest, then run step 4 again.
Your agent cannot run shell commands	This setup needs a shell. Use the Purveyors web app at https://purveyors.io instead.