Skip to main content

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 from a job description and get a role ID plus apply URL back as JSON. 
staplehire roles create --jd "Senior backend engineer. TypeScript, remote."

​
Quickstart

staplehire roles create --jd "Staff engineer. Go, Kubernetes, on-call."
Example output: 
{
  "role": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Staff Engineer",
    "organization_id": "org_...",
    "status": "active"
  },
  "apply_url": "https://staplehire.com/apply/550e8400-e29b-41d4-a716-446655440000"
}
Extract the role ID for later commands: 
ROLE_ID=$(staplehire roles create --jd @job-description.md | jq -r '.role.id')

​
Parameters

FlagRequiredDescription
--jd <text>YesJob description string, file path, @path, or - for stdin

​
Examples

​
Create a role from inline text

staplehire roles create --jd "Senior SDR. B2B SaaS, outbound, Sydney."

​
Create a role from a Markdown file

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

​
Create a role from stdin

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

​
List and inspect roles

staplehire roles list --status active
staplehire roles get <roleId>
staplehire roles candidates <roleId>
roles list returns: 
{ "roles": [ { "id": "...", "title": "Backend Engineer", "status": "active" } ] }

​
Common errors

ErrorCauseFix
ValidationErrorMissing or empty --jdPass a JD string, @file, or -
AuthenticationErrorAPI key is missingRun staplehire login or set STAPLEHIRE_KEY
PermissionErrorKey cannot create rolesCheck organization permissions

​
FAQ

​
Can the CLI parse a job description file?

Yes. Use --jd @./job-description.md.

​
What value do I pass to candidate and sourcing commands?

Use .role.id from the roles create, roles list, or roles get output.

​
Does role creation return an apply URL?

Yes. Read .apply_url from the JSON output. Related: Add a candidate with the Staplehire CLI · Source candidates with the Staplehire CLI · Command reference