Command reference

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.

staplehire commands | jq '.subcommands[].name'

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.

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.

Roles

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.

Stages

staplehire stages create <roleId> --name <name> --position <n>
staplehire stages list <roleId>
staplehire stages candidates <roleId> <stageId>

See Manage stages.

Candidates

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, Enrich a candidate, Send an interview, and Send an email.

Interview designs

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

staplehire sessions list <roleId> [--candidate-email <email>]

interview-sessions is a deprecated alias for sessions.

Sourcing

staplehire sourcing start <roleId> [--prompt <text>] [--force]
staplehire sourcing prospects <roleId>

sourcing list is an alias for sourcing prospects. See Source candidates.

Search

staplehire search --q <text>

See Search.

Jobs

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.

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.

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 · Use with AI agents

Get started

Workflows

Automation

Reference

Authentication & account

Roles

Stages

Candidates

Interview designs

Interview sessions

Sourcing

Search

Jobs

Utilities

Global options

Environment variables

Exit codes

​Authentication & account

​Roles

​Stages

​Candidates

​Interview designs

​Interview sessions

​Sourcing

​Search

​Jobs

​Utilities

​Global options

​Environment variables

​Exit codes

Authentication & account

Roles

Stages

Candidates

Interview designs

Interview sessions

Sourcing

Search

Jobs

Utilities

Global options

Environment variables

Exit codes