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

# Quickstart

> Go from a fresh install to a sent AI interview in a few minutes — create a role, build a stage, add a candidate, and invite them, all from the terminal.

This walkthrough takes you through a complete hiring loop with the Staplehire CLI: **install → authenticate → create a role → add a stage → add a candidate → send an AI interview.** Every step returns JSON, so you can chain commands with [`jq`](https://jqlang.github.io/jq/).

<Steps>
  <Step title="Install the CLI">
    Install globally with npm and confirm the `staplehire` binary is on your `PATH`.

    ```bash theme={null}
    npm install -g @staplehire/staplehire-cli
    staplehire --version
    ```

    Need details or alternatives? See [Installation](/docs/installation).
  </Step>

  <Step title="Authenticate">
    Log in with browser OAuth. This opens [app.staplehire.com](https://app.staplehire.com), completes a PKCE exchange, and writes `STAPLEHIRE_KEY` to a `.env` file in your current directory.

    ```bash theme={null}
    staplehire login
    staplehire whoami
    ```

    For agents and CI, set `STAPLEHIRE_KEY` instead of logging in. See [Authentication](/docs/authentication).
  </Step>

  <Step title="Verify your environment">
    `doctor` checks your CLI version, API key, gateway URL, and that `GET /v1/me` succeeds.

    ```bash theme={null}
    staplehire doctor
    ```

    All checks should report `pass`. If not, follow the hint in each check's message.
  </Step>

  <Step title="Create a role">
    Pass a job description inline, from a file (`@path`), or from stdin (`-`). Capture the role ID for later steps.

    ```bash theme={null}
    ROLE_ID=$(staplehire roles create \
      --jd "Senior backend engineer. TypeScript, Postgres, remote." \
      | jq -r '.role.id')

    echo "Role: $ROLE_ID"
    ```

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

  <Step title="Add a pipeline stage">
    Candidates live in stages. Create one before adding candidates.

    ```bash theme={null}
    STAGE_ID=$(staplehire stages create "$ROLE_ID" \
      --name "Sourced" --position 0 \
      | jq -r '.stage.id')
    ```

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

  <Step title="Add a candidate">
    Add a candidate by email into the stage you just created. The command is idempotent per role and email.

    ```bash theme={null}
    CANDIDATE_ID=$(staplehire candidates create "$ROLE_ID" \
      --email alex@example.com \
      --name "Alex Chen" \
      --stage "Sourced" \
      | jq -r '.candidate.id')
    ```

    See [Add a candidate](/docs/add-candidate-cli).
  </Step>

  <Step title="Generate an interview design">
    An interview design defines the AI screening round. Generate one for the role.

    ```bash theme={null}
    DESIGN_ID=$(staplehire designs create "$ROLE_ID" \
      --type structured \
      --brief "Async screen for backend fundamentals and system design." \
      --round-title "Backend screen" \
      | jq -r '.interview_design.id')
    ```

    See [Send an interview](/docs/send-interview-cli).
  </Step>

  <Step title="Send the interview">
    Invite the candidate to the AI interview. This emails them an apply link.

    ```bash theme={null}
    staplehire candidates send-interview "$CANDIDATE_ID" --design "$DESIGN_ID"
    ```

    Track responses later with `staplehire sessions list "$ROLE_ID"`.
  </Step>
</Steps>

## The whole thing in one script

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

ROLE_ID=$(staplehire roles create \
  --jd "Senior backend engineer. TypeScript, Postgres, remote." \
  | jq -er '.role.id')

staplehire stages create "$ROLE_ID" --name "Sourced" --position 0 >/dev/null

CANDIDATE_ID=$(staplehire candidates create "$ROLE_ID" \
  --email alex@example.com --name "Alex Chen" --stage "Sourced" \
  | jq -er '.candidate.id')

DESIGN_ID=$(staplehire designs create "$ROLE_ID" \
  --type structured --round-title "Backend screen" \
  | jq -er '.interview_design.id')

staplehire candidates send-interview "$CANDIDATE_ID" --design "$DESIGN_ID"
```

<Note>
  `jq -e` exits non-zero if a field is missing, so the script fails fast instead of passing an empty ID into the next command.
</Note>

## Where to next

<CardGroup cols={2}>
  <Card title="Source candidates" icon="search" href="/docs/source-candidates-cli">
    Let the agent find prospects for a role instead of adding them by hand.
  </Card>

  <Card title="Enrich a candidate" icon="sparkles" href="/docs/enrich-candidate-cli">
    Run deep research on a candidate and read the summary.
  </Card>

  <Card title="Automate with agents" icon="bot" href="/docs/ai-agents">
    Install the skill so Cursor, Claude Code, and Codex run these flows for you.
  </Card>

  <Card title="Command reference" icon="terminal" href="/docs/commands">
    Every command, flag, and exit code in one place.
  </Card>
</CardGroup>