recruitcrm-cli

RecruitCRM CLI

Free, open-source, JSON-first CLI for connecting local AI agents to RecruitCRM, built by Talent Sourcer AI.

Use it to connect Claude Code, OpenAI Codex, OpenCode, OpenClaw, Hermes Agent, and other locally running AI agents to RecruitCRM. The CLI gives agents a safe, predictable terminal interface for searching and managing RecruitCRM candidates, contacts, companies, jobs, deals, placements, notes, tasks, custom fields, and more.

If you are looking for how to connect Claude Code to RecruitCRM, how to use Codex with RecruitCRM, or how to let an AI agent work with RecruitCRM data, this package is designed for that workflow.

Setup

Install from npm:

npm install -g @talentsourcer/recruitcrm-cli

Or run without installing:

npx @talentsourcer/recruitcrm-cli candidates search --country Germany

Install the agent skill with skills.sh:

npx skills add talentsourcer-ai/recruitcrm-cli

Auth

The CLI supports four auth sources, checked in this order:

1. --api-key
2. RECRUIT_CRM_API_KEY
3. Local .env
4. Saved user config at ~/.config/recruitcrm-cli/config.json

For one-off usage, set an environment variable:

RECRUIT_CRM_API_KEY=your_api_key_here

For persistent local usage, save the token to user config:

RECRUIT_CRM_API_KEY=your_api_key_here recruitcrm auth token set

auth token set validates the token before saving it with a lightweight GET /candidates?limit=1 request. Use --no-validate only when you need to save credentials without network access.

Or pipe the token from a local secret manager:

printf '%s' "$RECRUIT_CRM_API_KEY" | recruitcrm auth token set

Check auth status:

recruitcrm auth status --pretty

Remove the saved token:

recruitcrm auth token remove

The CLI never prints the token in command output.

The official API base URL is https://api.recruitcrm.io and endpoints are under /v1. The CLI default is https://api.recruitcrm.io/v1; if you pass --base-url https://api.recruitcrm.io, the CLI automatically appends /v1.

Operational commands always return JSON. --help returns human-readable text. Use --pretty for readable JSON output.

Upgrade

Upgrade the CLI to the latest npm version:

recruitcrm upgrade

After updating the npm package, the command asks whether to update/reinstall the RecruitCRM agent skill from talentsourcer-ai/recruitcrm-cli. This keeps the CLI and SKILL.md instructions in sync.

Useful non-interactive variants for AI agents:

recruitcrm upgrade --yes
recruitcrm upgrade --no-skills
recruitcrm upgrade --dry-run --pretty

Use --global with upgrade --yes or upgrade --skills to pass --global to skills.sh when reinstalling the skill globally.

JSON Contract

Every successful command returns a stable envelope:

{
  "success": true,
  "schemaVersion": "recruitcrm-cli/v1",
  "resource": "candidates",
  "action": "search",
  "count": 3,
  "data": [],
  "rateLimit": {
    "limit": "60",
    "remaining": "59"
  }
}

Every failed command returns JSON and exits non-zero:

{
  "success": false,
  "schemaVersion": "recruitcrm-cli/v1",
  "error": {
    "name": "ApiError",
    "message": "Unauthorized",
    "status": 401,
    "details": {},
    "rateLimit": {}
  }
}

Agent parsing rules:

• Read success first.
• Use data as the primary result payload.
• Use count for list/search result size when present.
• Use pagesFetched to understand paginated --all or search-all calls.
• Use filters to audit what was requested and what was actually sent to RecruitCRM.
• Use rateLimit.remaining to decide whether to pause before follow-up calls.
• List/search commands summarize common entities to keep responses compact; get and request return fuller API payloads.

Commands

recruitcrm candidates search --country Philippines --position Engineer --limit 20 --pretty
recruitcrm candidates search-all --country Philippines --city Manila --skills-all React,TypeScript --max-pages 5 --pretty
recruitcrm candidates list --limit 25 --pretty
recruitcrm candidates get <candidateSlug> --include-notes --include-activities --pretty
recruitcrm candidates create --from-file .recruitcrm-agent/candidate.json --pretty
recruitcrm candidates apply-to-job <candidateSlug> --job <jobSlug> --pretty
recruitcrm candidates add-to-job <candidateId> --job <jobId> --stage Applied --pretty

recruitcrm contacts search --company-slug <companySlug> --limit 50 --pretty
recruitcrm companies list --name "Acme" --pretty
recruitcrm jobs list --status Open --limit 25 --pretty
recruitcrm deals search --limit 25 --pretty
recruitcrm placements list --limit 25 --pretty
recruitcrm invoices list --limit 25 --pretty
recruitcrm custom-fields map --entity candidate --pretty

Create and update commands accept JSON either inline or from a file:

recruitcrm contacts create --data-json '{"first_name":"Ada","last_name":"Lovelace","email":"ada@example.com"}' --pretty
recruitcrm candidates update <candidateSlug> --from-file candidate-update.json --pretty

For endpoints not yet modeled as a first-class command, use the raw request command:

recruitcrm request GET /candidates?limit=1 --pretty
recruitcrm request POST /notes --from-file note.json --pretty

Candidate Search Notes

RecruitCRM does not support every useful filter server-side. The CLI mirrors the SDK workaround by applying these filters client-side after fetching candidates:

• --city Manila
• --skills-all React,TypeScript
• --skills-any Python,Java
• --experience-min 3
• --experience-max 8
• --salary-min 50000
• --salary-max 120000

Use search-all with --max-pages when client-side filters should be applied to more than one API page.

Custom field searches use RecruitCRM's GET-with-body workaround:

recruitcrm candidates search \
  --country Philippines \
  --custom-field 9:contains:React \
  --pretty

When --custom-field is present, the CLI sends custom fields in the request body and avoids combining normal filters in the URL. This matches the more reliable RecruitCRM/Postman behavior observed in production. Requested standard filters such as --country, --position, and date filters are then applied client-side to the returned candidates.

AI Agent Guidelines

• Prefer --pretty only for human review; compact JSON is easier for machine parsing.
• If auth is missing, ask the user to run recruitcrm auth token set locally rather than requesting the API key in chat.
• Use slugs returned by get, search, and list for follow-up commands.
• Use search for targeted queries and search-all --max-pages <n> for sourcing runs.
• Check success before using data; failed commands still return JSON with error.message and a non-zero exit code.
• Keep write payloads in .recruitcrm-agent/ when generated by an agent.
• Do not store API keys in generated payload files or chat transcripts.

About Talent Sourcer AI

Talent Sourcer AI helps professional recruiters and recruitment agencies evaluate large LinkedIn Recruiter searches in minutes instead of hours. Export candidates, define role-specific requirements, and get AI-ranked A/B/C shortlists with reasoning so your team can spend more time building relationships and closing placements.