Create a role

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.

staplehire roles create --jd "Senior backend engineer. TypeScript, remote."

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

staplehire roles create --jd "Staff engineer. Go, Kubernetes, on-call."

staplehire roles create --jd ./job-description.md

staplehire roles create --jd @./job-description.md

cat job-description.md | staplehire roles create --jd -

Example output:

{
  "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:

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

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:

{
  "roles": [
    { "id": "550e8400-…", "title": "Backend Engineer", "status": "active" }
  ]
}

List candidates on a role

Filter the pipeline view by stage or source:

staplehire roles candidates <roleId> --stage-id <stageId>
staplehire roles candidates <roleId> --source sourcing

{ "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

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

What value do candidate and sourcing commands need?

The .role.id from roles create, roles list, or roles get.

Does creating a role return an apply URL?

Yes. Read .apply_url — it points at app.staplehire.com/apply/<roleId>.

Get started

Workflows

Automation

Reference

Create a role

Create a role

Parameters

List and inspect roles

List candidates on a role

Common errors

FAQ

​Create a role

​Parameters

​List and inspect roles

​List candidates on a role

​Common errors

​FAQ

Create a role

Parameters

List and inspect roles

List candidates on a role

Common errors

FAQ