Complete Guide to HireSquire CLI: The Fastest Way for AI Agents to Screen Candidates

The HireSquire CLI is the fastest integration method for autonomous AI agents performing candidate screening. Whether you're Claude Code, OpenClaw, Codex, or any CLI-capable agent - this guide covers everything you need to submit screening jobs, poll for results, and process candidates at scale.

npm install -g hiresquire-cli
hiresquire init --token YOUR_API_TOKEN

Why CLI for AI Agents?

The CLI is purpose-built for autonomous agents because it:

• No session management - Tokens work directly, no OAuth flows
• JSON output - Machine-parseable responses for agent workflows
• Watch mode - Built-in polling with progress tracking
• File globbing - Read resumes from directories automatically
• Zero dependencies - Works with any agent that can execute shell commands

Initial Setup

Before running any commands, initialize your configuration:

# Full initialization with all options
hiresquire init --token YOUR_API_TOKEN --base-url https://hiresquireai.com/api/v1

# Or use environment variables (recommended for agents)
export HIRESQUIRE_API_TOKEN=your_token_here
export HIRESQUIRE_BASE_URL=https://hiresquireai.com/api/v1

Core Commands

1. Submit a Screening Job

The primary command for submitting candidate resumes for AI screening:

# Basic usage
hiresquire screen \
  --title "Senior Developer" \
  --description "We are looking for a Python developer with 5+ years experience..." \
  --resumes ./resumes/

Command Options

2. Check Job Status

# Check status
hiresquire status --job 123

# Watch for completion
hiresquire status --job 123 --watch

3. Get Results

# Get all results
hiresquire results --job 123

# Filter by minimum score
hiresquire results --job 123 --min-score 80

# Get top 5 candidates only
hiresquire results --job 123 --only-top-n 5

4. Generate Candidate Emails

Generate personalized outreach emails for your top candidates:

# Generate interview invitation
hiresquire email --job 123 --candidate 456 --type invite --tone professional

# Generate keep-warm follow-up
hiresquire email --job 123 --candidate 456 --type keep-warm --tone friendly

Agent Workflow Examples

OpenClaw Workflow

For OpenClaw or Claude Code agents, here's a complete workflow:

# Step 1: Read job description from file
DESCRIPTION=$(cat job_description.txt)

# Step 2: Submit screening with watch mode
RESULT=$(hiresquire screen \
  --title "Senior Engineer" \
  --description "$DESCRIPTION" \
  --resumes ./candidates/ \
  --watch \
  --json)

# Step 3: Parse the JSON response
JOB_ID=$(echo $RESULT | jq -r '.job_id')
CANDIDATES=$(echo $RESULT | jq -r '.results.candidates[] | select(.score >= 80) | .name')

echo "Qualified candidates: $CANDIDATES"

Python Agent Integration

For Python-based agents using subprocess:

import subprocess
import json
import os

def screen_candidates(title, description, resume_dir):
    # Set API token
    os.environ["HIRESQUIRE_API_TOKEN"] = os.getenv("HIRESQUIRE_API_TOKEN")
    
    # Submit job
    result = subprocess.run([
        "hiresquire", "screen",
        "--title", title,
        "--description", description,
        "--resumes", resume_dir,
        "--json"
    ], capture_output=True, text=True)
    
    if result.returncode == 0:
        return json.loads(result.stdout)
    else:
        raise Exception(f"CLI error: {result.stderr}")

# Usage
job = screen_candidates(
    title="Backend Engineer",
    description="Looking for Python expert with Django experience...",
    resume_dir="./resumes/"
)

print(f"Job submitted: {job['job_id']}")

CI/CD Pipeline Integration (GitHub Actions)

Automate screening for incoming applications via your CI/CD pipeline:

# .github/workflows/screen-candidates.yml
name: Screen New Candidates
on:
  push:
    paths:
      - 'applications/**/*.pdf'

jobs:
  screen:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install CLI
        run: npm install -g hiresquire-cli
      - name: Screen Candidates
        env:
          HIRESQUIRE_API_TOKEN: ${{ secrets.HIRESQUIRE_API_TOKEN }}
        run: |
          hiresquire screen \
            --title "Frontend Developer" \
            --description "React & Vue experience required..." \
            --resumes ./applications/ \
            --json > screening_results.json
      - name: Save Results
        uses: actions/upload-artifact@v4
        with:
          name: screening-results
          path: screening_results.json

Batch Processing Script (Bash)

For processing large backlogs of resumes with rate limiting in mind:

#!/bin/bash
# Process resumes in batches of 50 to respect rate limits
BATCH_SIZE=50
mkdir -p ./processed
mkdir -p ./results

ls ./resumes/*.pdf | xargs -n $BATCH_SIZE | while read BATCH; do
  echo "Processing batch..."
  JOB_JSON=$(hiresquire screen \
    --title "Data Scientist" \
    --description "ML and Python experience..." \
    --resumes $BATCH \
    --json)
    
  JOB_ID=$(echo $JOB_JSON | jq -r '.job_id')
  hiresquire status --job $JOB_ID --watch
  
  hiresquire results --job $JOB_ID --json > ./results/job_${JOB_ID}.json
  mv $BATCH ./processed/
  
  echo "Waiting 60s before next batch to respect limits..."
  sleep 60
done

Resume File Handling

The CLI supports multiple ways to specify resumes:

# Single file
--resumes john_doe_resume.pdf

# Multiple files (comma-separated)
--resumes resume1.pdf,resume2.pdf,resume3.pdf

# Directory (reads all .txt, .pdf, .doc, .docx)
--resumes ./resumes/

# From file containing filenames (one per line)
--resumes @candidate_list.txt

Leniency Levels Explained

The --leniency flag controls how strictly candidates are evaluated:

Default is 5 (balanced). Higher numbers result in stricter evaluation and fewer passing candidates.

JSON Output for Agents

For agent processing, use the --json flag for machine-parseable output:

hiresquire screen \
  --title "Software Engineer" \
  --description "Looking for React developer..." \
  --resumes ./resumes/ \
  --watch \
  --json

Response format:

{
  "type": "job_completed",
  "success": true,
  "job_id": 123,
  "results": {
    "job_id": 123,
    "title": "Software Engineer",
    "status": "completed",
    "total_candidates": 15,
    "candidates": [
      {
        "id": 1,
        "name": "John Doe",
        "score": 92,
        "summary": "Strong match with 5 years React experience...",
        "strengths": ["React", "TypeScript", "Node.js"],
        "interview_questions": [
          {"question": "Tell me about your React architecture decisions...", "seeking": "Technical depth"}
        ],
        "icebreaker": "I noticed your impressive work on Open Source..."
      }
    ]
  }
}

Error Handling

Common errors and solutions:

Agent API Keys (Cost Control)

For AI agents running in production, create dedicated API keys with spend limits to control costs:

# Create agent key with daily limit ($1.00) and specific permissions
hiresquire agent-keys --action create --name "My Agent" --daily-limit 1.00 --permissions "read,screen,email"

# List all agent keys
hiresquire agent-keys --action list

# Check agent key usage
hiresquire agent-keys --action usage --id 1

# Revoke an agent key
hiresquire agent-keys --action revoke --id 1

Agent keys are measured in dollars. A daily_spend_limit of 1.00 means the agent can spend up to $1.00/day (100 credits).

Prepaid Credits for Agents

Purchase prepaid credits for pay-as-you-go agent usage without subscription:

# Check credit balance
hiresquire credits --action balance

# View transaction history
hiresquire credits --action transactions

# Purchase a credit pack
hiresquire credits --action checkout --pack pouch   # pouch, satchel, or chest

# Direct purchase with saved payment method (no browser)
hiresquire credits --action purchase --pack satchel --payment-method-id pm_xxx

# Enable auto-reload (triggers when balance drops below threshold)
hiresquire credits --action auto-reload-enable --threshold 10 --amount 25 --payment-method-id pm_xxx

# Disable auto-reload
hiresquire credits --action auto-reload-disable

Credit Packs

Next Steps

Now that you understand the CLI, here are recommended next steps:

• MCP Integration - Set up the Model Context Protocol for Claude Desktop
• Python SDK - Use the native Python library for LangChain integration
• REST API - Build custom integrations with the full API reference
• Webhooks - Configure automatic notifications for large-scale screening

The CLI is the fastest path to production for any CLI-capable agent. With copy-paste commands and built-in async handling, you can have a fully autonomous hiring workflow running in minutes.