# Setup

The user needs only their Shepherd account with sources connected on the website (https://sources.askshepherd.ai). No cloud account, API key
or deployment is involved; the CLI signs in as the user in their browser.

## CLI (Node.js 22.13+)

```sh
mkdir -p ~/.local/bin
curl -fsSL https://sources.askshepherd.ai/downloads/shepherd.mjs -o ~/.local/bin/shepherd
chmod +x ~/.local/bin/shepherd
export PATH="$HOME/.local/bin:$PATH"     # add this line to ~/.zshrc or ~/.bashrc to keep it
shepherd login                           # the user signs in in the browser that opens
shepherd whoami
```

The download's sha256 is in its `x-content-sha256` response header and on the website's CLI & MCP page. The CLI
defaults to https://sources-api.askshepherd.ai; `--server URL` or `SHEPHERD_SERVER` choose another. Tokens live in
`~/.config/shepherd/credentials.json` (0600) and refresh automatically; `shepherd logout` removes them.
`shepherd login --no-browser` prints the sign-in URL instead of opening it (the callback still goes to 127.0.0.1 on the
machine running the CLI).

## MCP clients (stdio server from the CLI; no token in the client's config)

| Client | Command |
| --- | --- |
| Claude Code | `claude mcp add shepherd -- node ~/.local/bin/shepherd mcp` |
| Codex CLI | `codex mcp add shepherd -- node ~/.local/bin/shepherd mcp` |
| Pi | `pi mcp add shepherd -- node ~/.local/bin/shepherd mcp` |
| Cursor, Claude Desktop, others | `shepherd mcp-config` prints the JSON block (`mcpServers.shepherd` with absolute paths) |

`shepherd mcp` serves the tools in [tools.md](tools.md) over stdio with the signed-in user's token.

The service also has a remote MCP endpoint, `https://sources-api.askshepherd.ai/mcp`, for clients that sign in with OAuth themselves (it publishes
RFC 9728 protected-resource metadata). The stdio route above is the tested one.

## This skill

`shepherd skill install` copies this skill into `~/.agents/skills/shepherd-sources` (Pi and other Agent Skills
clients) and, when those tools are present, `~/.claude/skills/` and `${CODEX_HOME:-~/.codex}/skills/`.
`shepherd skill install --target DIR` installs into one directory instead. Files you edited are kept unless you pass
`--force`.