# Set up your agent

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

HTML version: https://www.purveyors.io/docs/agents/setup

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.

## 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:

```bash
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:

```bash
purvey auth login --headless
```

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

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

Message to send the person:

```text
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:

```bash
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:

```bash
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:

```bash
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. |

## Related

- [CLI overview](https://www.purveyors.io/docs/cli/overview): Every command group and common workflows.
- [Agent integration](https://www.purveyors.io/docs/cli/agent-integration): What agents can do with Purveyors and patterns that work well.
- [Auth, config, and output](https://www.purveyors.io/docs/cli/auth-output): Exit codes, error envelopes, and the ID reference.