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

# Create a role

> Create a Staplehire role from a job description file, stdin, or inline text using the CLI, then list, inspect, and view candidates on it.

Create a role from a job description and get back a role ID plus an apply URL as JSON. The role is the anchor for stages, candidates, sourcing, and interviews.

```bash theme={null}
staplehire roles create --jd "Senior backend engineer. TypeScript, remote."
```

## Create a role

The `--jd` flag accepts inline text, a file path, an `@path`, or `-` for stdin.

<CodeGroup>
  ```bash Inline text theme={null}
  staplehire roles create --jd "Staff engineer. Go, Kubernetes, on-call."
  ```

  ```bash From a file theme={null}
  staplehire roles create --jd ./job-description.md
  ```

  ```bash From @path theme={null}
  staplehire roles create --jd @./job-description.md
  ```

  ```bash From stdin theme={null}
  cat job-description.md | staplehire roles create --jd -
  ```
</CodeGroup>

Example output:

```json theme={null}
{
  "role": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Staff Engineer",
    "organization_id": "org_…",
    "status": "active"
  },
  "apply_url": "https://app.staplehire.com/apply/550e8400-e29b-41d4-a716-446655440000"
}
```

Capture the role ID for later commands:

```bash theme={null}
ROLE_ID=$(staplehire roles create --jd @job-description.md | jq -r '.role.id')
```

### Parameters

| Flag           | Required | Description                                                          |
| -------------- | -------- | -------------------------------------------------------------------- |
| `--jd <value>` | Yes      | Job description: inline string, file path, `@path`, or `-` for stdin |

## List and inspect roles

```bash theme={null}
staplehire roles list                       # all roles
staplehire roles list --status active        # filter by status
staplehire roles list --q "engineer"         # search title/description
staplehire roles list --limit 10             # cap results
staplehire roles get <roleId>                # one role
staplehire roles candidates <roleId>         # candidates on the role
```

`roles list` returns:

```json theme={null}
{
  "roles": [
    { "id": "550e8400-…", "title": "Backend Engineer", "status": "active" }
  ]
}
```

### List candidates on a role

Filter the pipeline view by stage or source:

```bash theme={null}
staplehire roles candidates <roleId> --stage-id <stageId>
staplehire roles candidates <roleId> --source sourcing
```

```json theme={null}
{ "candidates": [ { "id": "cand_…", "email": "alex@example.com", "stage_id": "stage_…" } ] }
```

## Common errors

| Error                 | Exit code | Fix                                                          |
| --------------------- | --------- | ------------------------------------------------------------ |
| `ValidationError`     | `3`       | Missing or empty `--jd` — pass a string, `@file`, or `-`     |
| `AuthenticationError` | `2`       | Run `staplehire login` or set `STAPLEHIRE_KEY`               |
| `PermissionError`     | `6`       | The key cannot create roles — check organization permissions |

## FAQ

<AccordionGroup>
  <Accordion title="Can the CLI read a job description from a file?">
    Yes. Use `--jd @./job-description.md` (the `@` prefix), a plain path, or pipe via `--jd -`.
  </Accordion>

  <Accordion title="What value do candidate and sourcing commands need?">
    The `.role.id` from `roles create`, `roles list`, or `roles get`.
  </Accordion>

  <Accordion title="Does creating a role return an apply URL?">
    Yes. Read `.apply_url` — it points at `app.staplehire.com/apply/<roleId>`.
  </Accordion>
</AccordionGroup>

Related: [Manage stages](/docs/stages-cli) · [Add a candidate](/docs/add-candidate-cli) · [Source candidates](/docs/source-candidates-cli)