HireSquire CLI

AI-powered candidate screening from the command line

HireSquire CLI enables AI agents and developers to screen candidates directly from the terminal. Built for integration with Claude Code, OpenCode, OpenClaw, Codex, and any CLI-capable agent.

Features

• 🤖 Agent-Ready: Works with Claude Code, OpenCode, OpenClaw, Codex, and more
• 📋 Full Workflow: Submit jobs, check status, get results, generate emails
• 🔄 Watch Mode: Poll for completion with progress updates
• 📄 JSON Output: Machine-readable output for automation
• ⚙️ Config Management: Easy API token setup and storage
• 🔗 Webhook Support: Conditional webhooks for automated workflows

Installation

Global Installation

npm install -g hiresquire-cli

Using npx (No Installation)

npx hiresquire-cli --version

Development Installation

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

Quick Start

1. Configure API Token

hiresquire init --token YOUR_API_TOKEN

Or set via environment variable:

export HIRESQUIRE_API_TOKEN=your_token_here

2. Submit a Screening Job

hiresquire screen \
  --title "Senior Python Developer" \
  --description "We are looking for a Senior Python Developer..." \
  --resumes ./resumes/

3. Check Results

hiresquire results --job 123

Commands

| Command | Description | |---------|-------------| | init | Initialize configuration with API token | | screen | Submit a candidate screening job | | jobs | List all screening jobs | | results | Get results for a job | | status | Check job status | | email | Generate an email for a candidate | | configure | Update configuration settings | | cancel | Cancel a running job | | compare | Compare candidates side-by-side | | outcome | Report hiring outcome | | webhook-test | Test a webhook endpoint | | rate-limit | Check API rate limit status | | candidate | Get candidate details | | set-status | Update candidate status | | schema | Get API schema |

init

Initialize configuration with your API token:

hiresquire init --token YOUR_API_TOKEN

Options:

• -t, --token <token> - API token from HireSquire dashboard (required)
• -u, --base-url <url> - API base URL (default: https://api.hiresquireai.com/api/v1)
• -w, --webhook <url> - Default webhook URL
• -y, --yes - Skip confirmation

screen

Submit a candidate screening job:

hiresquire screen --title "Job Title" --description "Job description..." --resumes ./resumes/

Options:

• -t, --title <title> - Job posting title (required)
• -d, --description <description> - Job description (string or @file) (required)
• -r, --resumes <paths> - Resume files or directory (comma-separated or @file)
• -l, --leniency <1-10> - Screening leniency (1=strict, 10=loose), default: 5
• -w, --webhook <url> - Webhook URL for notifications
• --watch - Poll for completion and show results
• --min-score <number> - Minimum score threshold (0-100)
• --only-top-n <number> - Only return top N candidates

jobs

List all screening jobs:

hiresquire jobs
hiresquire jobs --status completed
hiresquire jobs --page 2 --limit 20

Options:

• -s, --status <status> - Filter by status (pending, processing, completed, failed)
• -p, --page <number> - Page number
• -l, --limit <number> - Results per page

results

Get results for a screening job:

hiresquire results --job 123
hiresquire results --job 123 --min-score 80
hiresquire results --job 123 --only-top-n 5

Options:

• -j, --job <id> - Job ID (required)
• --min-score <number> - Filter by minimum score
• --only-top-n <number> - Only return top N candidates

status

Check status of a screening job:

hiresquire status --job 123
hiresquire status --job 123 --watch

Options:

• -j, --job <id> - Job ID (required)
• -w, --watch - Watch for status changes

email

Generate an email for a candidate:

hiresquire email --job 123 --candidate 1 --type invite
hiresquire email --job 123 --candidate 2 --type rejection --message "We decided to move forward with another candidate"

Options:

• -j, --job <id> - Job ID (required)
• -c, --candidate <id> - Candidate ID (required)
• -t, --type <type> - Email type: invite, rejection, followup (required)
• -m, --message <text> - Custom message to include

configure

Update configuration settings:

hiresquire configure --token NEW_TOKEN
hiresquire configure --webhook https://your-webhook.com
hiresquire configure --clear

Options:

• -t, --token <token> - API token
• -u, --base-url <url> - API base URL
• -w, --webhook <url> - Default webhook URL
• -l, --leniency <number> - Default leniency level
• --clear - Clear all configuration

Agent Integration Examples

OpenClaw

OpenClaw (https://openclaw.ai/) can execute CLI commands directly:

// Add to your OpenClaw tools
{
  name: "screen_candidates",
  description: "Screen candidates for a job using HireSquire AI",
  parameters: {
    type: "object",
    properties: {
      job_title: { type: "string" },
      job_description: { type: "string" },
      resumes_path: { type: "string" },
      min_score: { type: "number", minimum: 0, maximum: 100 }
    },
    required: ["job_title", "job_description", "resumes_path"]
  },
  execute: async (params) => {
    const { stdout } = await exec(`npx hiresquire-cli screen 
      --title "${params.job_title}" 
      --description "${params.job_description}" 
      --resumes ${params.resumes_path}
      --json`);
    return JSON.parse(stdout);
  }
}

Claude Code

# Screen candidates
npx hiresquire-cli screen \
  --title "Senior Developer" \
  --description "We are looking for a Senior Developer..." \
  --resumes ./resumes/ \
  --json

Custom Scripts

const { spawn } = require('child_process');

function screenCandidates(jobTitle, jobDescription, resumePath) {
  return new Promise((resolve, reject) => {
    const process = spawn('npx', [
      'hiresquire-cli',
      'screen',
      '--title', jobTitle,
      '--description', jobDescription,
      '--resumes', resumePath,
      '--json'
    ]);

    let output = '';
    process.stdout.on('data', (data) => output += data);
    process.on('close', (code) => {
      if (code === 0) {
        resolve(JSON.parse(output));
      } else {
        reject(new Error(output));
      }
    });
  });
}

Environment Variables

| Variable | Description | |----------|-------------| | HIRESQUIRE_API_TOKEN | API token for authentication | | HIRESQUIRE_BASE_URL | API base URL (default: https://api.hiresquireai.com/api/v1) | | HIRESQUIRE_WEBHOOK_URL | Default webhook URL |

JSON Output

All commands support --json flag for machine-readable output:

hiresquire screen --title "Job Title" --description "Job description..." --resumes ./resumes/ --json

{
  "success": true,
  "job_id": 123,
  "status": "processing",
  "status_url": "https://api.hiresquireai.com/api/v1/jobs/123"
}

Configuration File

Configuration is stored in ~/.hiresquire/config.json:

{
  "apiToken": "your_api_token",
  "baseUrl": "https://api.hiresquireai.com/api/v1",
  "webhookUrl": "https://your-webhook.com",
  "defaultLeniency": 5
}

Security Warning: The API token is stored in plain text. On shared systems, consider using environment variables instead: export HIRESQUIRE_API_TOKEN=your_token_here

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev -- screen --job "..." --resumes ./resumes/

# Run tests
npm test

License

MIT License - see LICENSE for details.

Support

• Email: [email protected]
• Website: https://hiresquireai.com
• Docs: https://hiresquireai.com/docs/agents