> ## Documentation Index
> Fetch the complete documentation index at: https://staplehire.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Command reference

> Every Staplehire CLI command for roles, stages, candidates, sourcing, interviews, jobs, search, authentication, and utilities — with global flags and exit codes.

Run `staplehire <resource> <action>` to drive hiring workflows from the terminal. Data commands return JSON on stdout; errors are JSON on stderr with [stable exit codes](/docs/cli-errors).

```bash theme={null}
staplehire commands | jq '.subcommands[].name'
```

<Tip>
  `staplehire commands` prints the live, machine-readable command tree for your installed version. It's the source of truth — agents should call it instead of memorizing command shapes.
</Tip>

## Authentication & account

| Command             | What it does                                                          |
| ------------------- | --------------------------------------------------------------------- |
| `staplehire login`  | Browser PKCE login; writes `STAPLEHIRE_KEY` to `.env` (alias: `init`) |
| `staplehire logout` | Removes `STAPLEHIRE_KEY` from `.env`                                  |
| `staplehire whoami` | Verifies the API key and returns user + organization (alias: `me`)    |
| `staplehire doctor` | Checks version, key source, API URL, and `GET /v1/me`                 |

See [Authentication](/docs/authentication).

## Roles

```bash theme={null}
staplehire roles create --jd <text|@file|->
staplehire roles list [--status <s>] [--q <text>] [--limit <n>]
staplehire roles get <roleId>
staplehire roles candidates <roleId> [--stage-id <id>] [--source <s>]
```

See [Create a role](/docs/create-role-cli).

## Stages

```bash theme={null}
staplehire stages create <roleId> --name <name> --position <n>
staplehire stages list <roleId>
staplehire stages candidates <roleId> <stageId>
```

See [Manage stages](/docs/stages-cli).

## Candidates

```bash theme={null}
staplehire candidates list [--role-id <id>] [--email <e>] [--source <s>] [--q <text>] [--limit <n>]
staplehire candidates get <candidateId>
staplehire candidates create <roleId> --email <e> (--stage <name> | --stage-id <id>) [--name <n>] [--phone <p>] [--linkedin-url <u>] [--portfolio-url <u>] [--current-location <loc>]
staplehire candidates move <candidateId> --stage-id <id>
staplehire candidates enrich <candidateId> [--prompt <text>] [--force]
staplehire candidates research <candidateId>
staplehire candidates screening-result <candidateId>
staplehire candidates send-interview <candidateId> --design <designId> [--mode <mode>]
staplehire candidates interview-link <candidateId> --design <designId>
staplehire candidates send-email <candidateId> --subject <s> --title <t> --body <text|@file|-> [--description <d>] [--cta <label>] [--url <u>] [--brand-name <n>] [--dry-run]
```

`candidates add` is a deprecated alias for `create`; `send-message` is a deprecated alias for `send-email`.

See [Add a candidate](/docs/add-candidate-cli), [Enrich a candidate](/docs/enrich-candidate-cli), [Send an interview](/docs/send-interview-cli), and [Send an email](/docs/send-email-cli).

## Interview designs

```bash theme={null}
staplehire designs create <roleId> [--type structured|conversational] [--brief <text>] [--round-title <title>]
staplehire designs list <roleId>
staplehire designs get <designId>
```

`interview-design` is a deprecated alias for `designs`.

## Interview sessions

```bash theme={null}
staplehire sessions list <roleId> [--candidate-email <email>]
```

`interview-sessions` is a deprecated alias for `sessions`.

## Sourcing

```bash theme={null}
staplehire sourcing start <roleId> [--prompt <text>] [--force]
staplehire sourcing prospects <roleId>
```

`sourcing list` is an alias for `sourcing prospects`. See [Source candidates](/docs/source-candidates-cli).

## Search

```bash theme={null}
staplehire search --q <text>
```

See [Search](/docs/search-cli).

## Jobs

```bash theme={null}
staplehire jobs get <jobId>
staplehire jobs list [--role-id <id>] [--candidate-id <id>] [--type enrich|source_role_prospects] [--status pending|claimed|done|failed] [--include-history]
staplehire jobs poll <jobId> [--interval <ms>] [--timeout <ms>]
```

See [Poll jobs](/docs/poll-agent-jobs).

## Utilities

| Command                                          | Description                                                          |
| ------------------------------------------------ | -------------------------------------------------------------------- |
| `staplehire doctor`                              | Diagnose version, API key, API URL, and reachability                 |
| `staplehire open [path]`                         | Open the dashboard (optionally at a subpath)                         |
| `staplehire docs`                                | Open the documentation in your browser                               |
| `staplehire update`                              | Check npm for a newer CLI version                                    |
| `staplehire commands`                            | Print the machine-readable command tree                              |
| `staplehire skills install [--copy] [--dry-run]` | Install the agent skill into `.agents` / `.claude` / `.cursor` roots |

See [Use with AI agents](/docs/ai-agents).

## Global options

These work on every command and can appear in any position.

| Flag               | Description                                             |
| ------------------ | ------------------------------------------------------- |
| `--api-key <key>`  | Override `STAPLEHIRE_KEY` for this invocation           |
| `--api-url <url>`  | Override the API gateway base URL                       |
| `--app-url <url>`  | Override the dashboard URL (for `login` and `open`)     |
| `--json`           | Force JSON output (also automatic when stdout is piped) |
| `-q, --quiet`      | Suppress human messages; implies `--json`               |
| `-h, --help`       | Show help                                               |
| `-v, --version`    | Print the CLI version                                   |
| `--profile <name>` | Reserved for multi-profile auth (not active yet)        |

## Environment variables

| Variable             | Description                                     |
| -------------------- | ----------------------------------------------- |
| `STAPLEHIRE_KEY`     | API key (`sh_live_…` / `sh_test_…`)             |
| `STAPLEHIRE_API_URL` | Override the API gateway base URL               |
| `STAPLEHIRE_APP_URL` | Override the dashboard URL for `login` / `open` |

The CLI also reads these from a `.env` file in the current directory.

## Exit codes

| Code | Meaning                        |
| ---- | ------------------------------ |
| `0`  | Success                        |
| `1`  | Generic or internal error      |
| `2`  | Authentication (usually `401`) |
| `3`  | Validation (usually `400`)     |
| `4`  | Not found (usually `404`)      |
| `5`  | Conflict (usually `409`)       |
| `6`  | Permission (usually `403`)     |
| `7`  | Upstream (usually `502`)       |
| `8`  | CLI usage / bad arguments      |
| `9`  | `jobs poll` timeout            |

Related: [CLI errors](/docs/cli-errors) · [Use with AI agents](/docs/ai-agents)