ashby-cli

ashby-cli

Agent-first CLI for Ashby's official API.

This CLI is intended for operational workflows around:

• candidate search and lookup
• candidate enrichment / upsert
• application creation and stage movement
• candidate notes
• job, source, interview-plan, and stage discovery
• application history and feedback
• interview schedules
• synthetic feed reconstruction from public API surfaces
• hiring pipeline state

It is intentionally scoped to state and workflow mutation, not the full Ashby UI surface.

Install

Package name: ashby-cli
Binary name: ashby

npm install -g ashby-cli

If you do not want a global install, invoke the published package directly:

npx -y ashby-cli doctor --json

Skill install after publication:

npx -y skills add -g danielgwilson/ashby-cli --skill ashby

Local skill install from a checkout:

npx -y skills add . --skill ashby -g --copy

Or from source:

git clone https://github.com/danielgwilson/ashby-cli.git
cd ashby-cli
npm install
npm run build

Auth

Ashby uses HTTP Basic auth with the API key as the username and a blank password.

Ashby does not expose OAuth for this API. The easiest human setup path is browser-assisted API key creation.

You can either:

• set ASHBY_API_KEY
• or store the key locally

ashby auth setup
ashby auth set --stdin
ashby auth status
ashby doctor

If you are using npx, remember it will not load .env.local automatically. Export ASHBY_API_KEY first or source your env file in the shell.

Recommended first-time setup

ashby auth setup

This will:

• open the Ashby API key admin page
• remind you which permissions to enable
• accept a pasted API key
• save it locally
• validate it immediately

If you prefer not to install globally:

npx -y ashby-cli auth setup

Commands

Auth

ashby auth set --stdin
ashby auth status --json
ashby auth clear

Health / identity

ashby doctor --json
ashby whoami --json

Candidates

ashby candidate search --name "Jane Doe" --json
ashby candidate search --email "[e-mail]" --json
ashby candidate search --name "Jane Doe" --email "[e-mail]" --json
ashby candidate get <candidate-id> --json
ashby candidate notes --candidate-id <candidate-id> --json
ashby candidate create --name "Jane Doe" --email "[e-mail]" --linkedin-url "https://linkedin.com/in/jane" --json
ashby candidate update --candidate-id <candidate-id> --github-url "https://github.com/jane" --suppress-notifications --json
ashby candidate upsert --name "Jane Doe" --email "[e-mail]" --phone-number "[phone]" --json
ashby note create --candidate-id <candidate-id> --note "Strong fast-track candidate" --json
ashby note ensure --candidate-id <candidate-id> --marker "AHH 2026" --note-file ./note.txt --json

Applications

ashby application list --job-id <job-id> --status Active --json
ashby application get <application-id> --json
ashby application history --application-id <application-id> --json
ashby application feedback --application-id <application-id> --json
ashby application feed --application-id <application-id> --json
ashby application create --candidate-id <candidate-id> --job-id <job-id> --interview-stage-id <stage-id> --json
ashby application stage-change --application-id <application-id> --interview-stage-id <stage-id> --json

Pipeline metadata

ashby job list --status Open,Draft --json
ashby job get <job-id> --json
ashby job search --title "Founding Engineer" --json
ashby interview-plan list --json
ashby stage list --interview-plan-id <plan-id> --json
ashby stage list --job-id <job-id> --json
ashby source list --json
ashby interview schedules --application-id <application-id> --json
ashby interview events --application-id <application-id> --json

Design notes

• Official-API-first
• JSON-first
• Explicit mutations
• Small supported surface

Development

npm ci
npm run check:release
npm audit --omit=dev --json
npm pack --dry-run --json --silent

When working from the larger platform-adapters workspace, also run the workspace secret sweep before pushing.

What this CLI does not try to do

• general outbound candidate email
• candidate self-serve scheduling link generation
• full Ashby UI automation

Feed coverage

ashby application feed reconstructs a useful candidate/application timeline from public API data:

• application history
• candidate notes
• feedback
• interview schedules
• nested interview events

It does not provide full parity with the Ashby web UI feed. In particular, public API coverage still appears weak or absent for:

• synced/sent email thread history
• text thread history
• the exact fully merged UI feed object

See docs/CONTRACT_V1.md for the stable CLI contract.