boss-cli Job Search & Recruiter Tool

---
name: boss-cli-job-search
description: CLI tool for BOSS 直聘 job search, recommendations, applications, and recruiter messaging via reverse-engineered API
triggers:
  - search jobs on boss zhipin
  - find jobs using boss cli
  - send greetings to recruiters on boss
  - export job listings to csv
  - view job recommendations boss zhipin
  - manage job applications boss cli
  - batch greet recruiters boss
  - authenticate boss zhipin cli
---

# boss-cli Job Search & Recruiter Tool

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

A Python CLI for BOSS 直聘 (boss.zhipin.com) that enables job searching, personalized recommendations, application management, and recruiter messaging via a reverse-engineered API. Supports 10+ browsers for cookie extraction, QR login, structured JSON/YAML output for agent pipelines, and anti-detection rate limiting.

## Installation

```bash
# Recommended (fast, isolated)
uv tool install kabi-boss-cli

# Or pipx
pipx install kabi-boss-cli

# With YAML output support
pip install kabi-boss-cli[yaml]

# Upgrade
uv tool upgrade kabi-boss-cli

# From source
git clone [email protected]:jackwener/boss-cli.git
cd boss-cli
uv sync

Authentication

Credentials are stored at ~/.config/boss-cli/credential.json. Cookies auto-refresh from browser after 7 days.

# Auto-detect browser cookies, fallback to QR code
boss login

# Extract from a specific browser
boss login --cookie-source chrome
boss login --cookie-source firefox
boss login --cookie-source edge
boss login --cookie-source brave
boss login --cookie-source arc
boss login --cookie-source safari

# QR code login only (scan with BOSS 直聘 APP)
boss login --qrcode

# Verify session against real API
boss status
boss status --json

# Clear saved credentials
boss logout

boss status --json returns per-flow health:

{
  "ok": true,
  "schema_version": "1",
  "data": {
    "authenticated": true,
    "search_authenticated": true,
    "recommend_authenticated": true,
    "cookie_names": ["__zp_stoken__", "bst", "buid"]
  }
}

Job Search

# Basic search
boss search "golang"
boss search "Python 工程师"

# Filter by city (use `boss cities` for full list)
boss search "Python" --city 杭州
boss search "Java" --city 北京

# Filter by salary range
boss search "Java" --salary 20-30K

# Filter by experience
boss search "前端" --exp 3-5年
boss search "后端" --exp 1-3年

# Filter by degree
boss search "AI" --degree 硕士
boss search "运维" --degree 本科

# Filter by industry
boss search "后端" --industry 互联网

# Filter by company scale
boss search "产品" --scale 1000-9999人
boss search "数据" --scale 500-999人

# Filter by funding stage
boss search "数据" --stage 已上市
boss search "AI" --stage B轮

# Filter by job type
boss search "运维" --job-type 全职
boss search "设计" --job-type 兼职

# Combine multiple filters
boss search "Python" --city 深圳 --salary 15-25K --exp 1-3年 --degree 本科

# Pagination
boss search "后端" --city 深圳 -p 2
boss search "golang" -p 3

# JSON output (structured envelope)
boss search "Python" --json
boss search "golang" --json | jq .data.jobs

Job Details & Export

# Show job #3 from last search (short-index navigation)
boss show 3
boss show 1 --json

# View full job details by securityId
boss detail <securityId>
boss detail <securityId> --json

# Export search results to CSV
boss export "Python" -n 50 -o jobs.csv

# Export as JSON
boss export "golang" --format json -o jobs.json

# Export with filters
boss export "Java" --city 上海 --salary 20-30K -n 100 -o shanghai_java.csv

Recommendations & Personal Data

# Personalized job recommendations
boss recommend
boss recommend -p 2
boss recommend --json

# View profile / resume status
boss me
boss me --json

# View applied jobs
boss applied
boss applied --json

# View interview invitations
boss interviews
boss interviews --json

# View browsing history
boss history

# View communicated bosses list
boss chat

Recruiter Greeting (Apply / Message)

# Send greeting to a single recruiter (by job securityId)
boss greet <securityId>
boss greet <securityId> --json

# Batch greet top N results from a search
boss batch-greet "golang" --city 杭州 -n 5
boss batch-greet "Python" --salary 20-30K -n 10

# Dry run — preview only, no messages sent
boss batch-greet "Python" --salary 20-30K --dry-run

# Batch greet with multiple filters
boss batch-greet "Java" --city 北京 --exp 3-5年 -n 20 --dry-run

Note: Batch greet uses a 1.5s delay between requests to avoid rate limiting.

Supported Cities

# List all 40+ supported cities
boss cities

Common cities: 北京, 上海, 广州, 深圳, 杭州, 成都, 武汉, 西安, 南京, 苏州, 重庆, 天津, 长沙, 郑州, 青岛

Structured Output (Agent Pipelines)

All --json / --yaml commands use a unified envelope:

{
  "ok": true,
  "schema_version": "1",
  "data": { ... }
}

• Rich display → stderr (never pollutes pipes)
• Non-TTY stdout → auto YAML
• --json → explicit JSON
• --yaml → explicit YAML (requires kabi-boss-cli[yaml])

# Pipe-safe patterns
boss search "Python" --json | jq '.data.jobs[] | {title, company, salary}'
boss recommend --json | jq '.data.jobs[0]'
boss me --json | jq '.data.profile.name'

# Check auth in scripts
boss status --json | jq '.data.search_authenticated'

# Export pipeline
boss export "golang" --format json -o - | jq '.[] | select(.salary > 30)'

Verbose / Debug Logging

# Show request URLs, status codes, and timing
boss -v search "Python"
boss -v recommend
boss -v greet <securityId>

Common Patterns

Script: Search and Export

import subprocess
import json

result = subprocess.run(
    ["boss", "search", "Python", "--city", "上海", "--json"],
    capture_output=True, text=True
)
envelope = json.loads(result.stdout)
if envelope["ok"]:
    jobs = envelope["data"]["jobs"]
    for job in jobs:
        print(f"{job['title']} @ {job['company']} — {job['salary']}")

Script: Batch Apply with Logging

import subprocess
import json
import time

def batch_greet(keyword: str, city: str, count: int = 10, dry_run: bool = True):
    cmd = [
        "boss", "batch-greet", keyword,
        "--city", city,
        "-n", str(count),
        "--json"
    ]
    if dry_run:
        cmd.append("--dry-run")
    
    result = subprocess.run(cmd, capture_output=True, text=True)
    envelope = json.loads(result.stdout)
    
    if envelope["ok"]:
        print(f"Greeted {len(envelope['data']['results'])} recruiters")
        return envelope["data"]["results"]
    else:
        print(f"Error: {envelope.get('error')}")
        return []

# Preview first
batch_greet("golang", "深圳", count=5, dry_run=True)

# Then execute
batch_greet("golang", "深圳", count=5, dry_run=False)

Script: Check Auth and Re-login if Needed

import subprocess
import json
import sys

def ensure_authenticated() -> bool:
    result = subprocess.run(
        ["boss", "status", "--json"],
        capture_output=True, text=True
    )
    try:
        envelope = json.loads(result.stdout)
        return envelope.get("ok") and envelope["data"].get("search_authenticated")
    except json.JSONDecodeError:
        return False

if not ensure_authenticated():
    print("Not authenticated. Running boss login...")
    subprocess.run(["boss", "login", "--cookie-source", "chrome"])
    if not ensure_authenticated():
        print("Login failed. Try: boss login --qrcode")
        sys.exit(1)

print("Authenticated. Proceeding...")

Script: Export Multiple Keywords

import subprocess

keywords = ["Python", "golang", "Java", "前端", "数据分析"]
city = "上海"

for kw in keywords:
    output_file = f"jobs_{kw}_{city}.csv"
    subprocess.run([
        "boss", "export", kw,
        "--city", city,
        "-n", "50",
        "-o", output_file
    ])
    print(f"Exported {kw} → {output_file}")

Rate Limiting & Anti-Detection (Built-in)

boss-cli handles this automatically:

Mechanism	Details
Gaussian jitter	random.gauss(0.3, 0.15) delay between requests
Random long pauses	5% chance of 2–5s pause (mimics reading)
Rate-limit cooldown	Code 9 → exponential backoff 10s→20s→40s→60s
HTTP 429/5xx retry	Auto-retry up to 3 times
Browser fingerprint	macOS Chrome 145 UA, sec-ch-ua, DNT, Priority headers
Cookie merge	Set-Cookie headers merged back into session

Troubleshooting

boss status reports authenticated=false but credential file exists

# Session expired server-side; re-authenticate
boss logout && boss login

环境异常 (__zp_stoken__ 已过期)

# Cookies expired — log into boss.zhipin.com in browser first, then:
boss logout && boss login
# If browser cookies work but QR gives partial set, prefer browser method:
boss login --cookie-source chrome

暂无投递记录 despite having applied

# Requires fresh __zp_stoken__ — re-login from browser, then:
boss login --cookie-source chrome
boss applied

Search returns no results

# Verify city spelling
boss cities
boss search "Python" --city 上海   # exact city name from cities list

Rate limited / code=9 errors

# Use verbose mode to see timing
boss -v search "Python"
# The CLI will auto-backoff; wait for cooldown to complete
# Avoid running multiple boss commands in parallel

QR code not rendering in terminal

# Ensure terminal supports Unicode half-blocks (most modern terminals do)
# Try iTerm2, Warp, or Windows Terminal
boss login --qrcode

Project Structure (for Contributors)

boss_cli/
├── cli.py          # Click entry point
├── client.py       # API client (rate-limit, retry, anti-detection)
├── auth.py         # Browser cookie extraction, QR login, TTL refresh
├── constants.py    # URLs, headers, city codes, filter enums
├── exceptions.py   # BossApiError hierarchy
├── index_cache.py  # Short-index cache for `boss show`
└── commands/
    ├── _common.py  # Schema envelope, handle_command, stderr console
    ├── auth.py     # login, logout, status, me
    ├── search.py   # search, recommend, detail, show, export, history, cities
    ├── personal.py # applied, interviews
    └── social.py   # chat, greet, batch-greet

# Development setup
uv sync
uv run pytest tests/ -v          # Unit tests
uv run pytest tests/ -v -m smoke # Smoke tests (requires valid cookies)
uv run ruff check .               # Lint