Use with AI agents

The Staplehire CLI is built for AI coding agents. Install the bundled skill so agents know the command surface and the non-interactive contract, then let them drive your hiring workflows from their terminal.

staplehire skills install
staplehire commands | jq '.subcommands[].name'
staplehire doctor -q

Install the skill

skills install copies the staplehire skill into the agent skill roots it finds in your current project. It looks for .agents/, .claude/, and .cursor/ and installs into their skills/ directories.

staplehire skills install

The JSON output reports where the skill was installed:

{
  "primary": "/path/to/project/.agents/skills/staplehire",
  "extras": ["/path/to/project/.cursor/skills/staplehire"],
  "created": null
}

primary — the first agent root found; the skill files are copied here.
extras — additional roots; by default these are symlinked to primary (use --copy to copy instead).
created — set to a path (for example .agents/skills) when no agent root existed and the CLI created .agents/skills for you.

Options

Flag	Description
`--copy`	Copy files into every root instead of symlinking the extras to `primary`
`--dry-run`	Print where the skill would be installed without writing anything

staplehire skills install --dry-run

{
  "primary": "/path/to/project/.agents/skills/staplehire",
  "extras": [],
  "created": ".agents/skills",
  "dryRun": true
}

Skills install into the project directory you run the command from (.agents/skills/staplehire, etc.), not a global home directory. Run it inside the repo your agent works in.

The agent protocol

The CLI auto-detects non-TTY environments and emits JSON — no --json flag needed (though -q forces clean JSON-only output). Agents should follow these rules:

Discover, don't guess

Run staplehire commands for the machine-readable command tree that matches the installed version. Don’t hardcode flag shapes.

staplehire commands | jq '.subcommands[] | {name, subcommands: (.subcommands // [] | map(.name))}'

Check the environment first

staplehire doctor -q | jq -e '.ok'

Supply every required flag

The CLI never prompts when stdin is not a TTY. Missing a required flag fails with exit code 8.

Poll async jobs before reading results

JOB_ID=$(staplehire sourcing start <roleId> | jq -r '.job.id')
staplehire jobs poll "$JOB_ID" -q
staplehire sourcing prospects <roleId> | jq '.prospects[]'

Branch on exit codes, not message strings

Read error.code from stderr JSON and the process exit code — never grep error.message.

Authentication for agents

Agents and CI must not use staplehire login (it opens a browser). Set STAPLEHIRE_KEY in the environment, or pass --api-key for a single command.

export STAPLEHIRE_KEY=sh_live_xxx
staplehire whoami | jq '.organization.id'

See Authentication and Use in CI.

Output contract for agents

Success → JSON on stdout, exit 0.
Failure → { "error": { … } } on stderr, non-zero exit code.
Use -q to suppress human status lines so stdout is pure JSON.
Read responses may include a urls object with dashboard deep links.

{"error":{"name":"ValidationError","code":"candidate_email_invalid","message":"…","hint":"…","field":"email","requestId":"req_…","status":400}}

Supported agents

Agent	Setup
Cursor	`staplehire skills install` (detects `.cursor/`); run commands in the agent terminal
Claude Code	`staplehire skills install` (detects `.claude/`); the skill loads automatically
OpenAI Codex	`staplehire skills install` (uses `.agents/`); same CLI and command tree
Hermes Agent	Use the terminal toolset with `STAPLEHIRE_KEY` set; ideal for long-running flows
Any terminal-capable agent	Set `STAPLEHIRE_KEY`, run `staplehire commands` to discover the surface

FAQ

What should an agent run first?

staplehire doctor -q to confirm version, key source, API URL, and a live API validation, then staplehire commands to discover the command tree.

Where does the skill get installed?

Into the agent roots in your current project — .agents/skills/staplehire, .claude/skills/staplehire, and/or .cursor/skills/staplehire. If none exist, the CLI creates .agents/skills.

Should I use `--copy` or symlinks?

Symlinks (the default) keep one source of truth. Use --copy when your environment can’t follow symlinks (some sandboxes and CI runners).

Related: Authentication · Poll jobs · CLI errors

Get started

Workflows

Automation

Reference

Install the skill

Options

The agent protocol

Authentication for agents

Output contract for agents

Supported agents

FAQ

​Install the skill

​Options

​The agent protocol

​Authentication for agents

​Output contract for agents

​Supported agents

​FAQ

Install the skill

Options

The agent protocol

Authentication for agents

Output contract for agents

Supported agents

FAQ