gem-hunter
Language: Python
A CLI for BOSS 直聘 — search jobs, view recommendations, manage applications via reverse-engineered API
A CLI for BOSS 直聘 — search jobs, view recommendations, manage applications, chat with recruiters, and manage candidates as a recruiter via reverse-engineered API 🤝
--cookie-source explicit browser selection, live validation against real search APIsboss show 3), CSV/JSON export{ok, schema_version, data}), Rich output on stderr# Recommended: uv tool (fast, isolated) uv tool install kabi-boss-cli # Or: pipx pipx install kabi-boss-cli # Optional: YAML output support pip install kabi-boss-cli[yaml]
Upgrade to the latest version:
uv tool upgrade kabi-boss-cli
# Or: pipx upgrade kabi-boss-cliFrom source:
git clone git@github.com:jackwener/boss-cli.git
cd boss-cli
uv sync# ─── Auth ───────────────────────────────────────── boss login # Auto-detect browser cookies, fallback to QR boss login --cookie-source chrome # Extract from specific browser boss login --qrcode # QR code login only boss status # Check login status (validates real search session, shows cookie names) boss logout # Clear saved cookies # ─── Search ─────────────────────────────────────── boss search "golang" # Search jobs boss search "Python" --city 杭州 # Filter by city boss search "Java" --salary 20-30K # Filter by salary boss search "前端" --exp 3-5年 # Filter by experience boss search "AI" --degree 硕士 # Filter by degree boss search "后端" --industry 互联网 # Filter by industry boss search "产品" --scale 1000-9999人 # Filter by company size boss search "数据" --stage 已上市 # Filter by funding stage boss search "运维" --job-type 全职 # Filter by job type boss search "后端" --city 深圳 -p 2 # Pagination # ─── Detail & Export ────────────────────────────── boss show 3 # View job #3 from last search boss detail <securityId> # View full job details boss detail <securityId> --json # JSON output (with schema envelope) boss export "Python" -n 50 -o jobs.csv # Export search results to CSV boss export "golang" --format json -o jobs.json # Export as JSON # ─── Recommendations ────────────────────────────── boss recommend # View recommended jobs boss recommend -p 2 --json # Next page, JSON output # ─── Personal Center ───────────────────────────── boss me # View profile boss me --json # JSON output boss applied # View applied jobs boss interviews # View interview invitations boss history # View browsing history boss chat # View communicated bosses # ─── Greet ──────────────────────────────────────── boss greet <securityId> # Send greeting to a boss boss greet <securityId> --json # JSON result boss batch-greet "golang" --city 杭州 -n 5 # Batch greet top 5 boss batch-greet "Python" --salary 20-30K --dry-run # Preview only # ─── Utilities ──────────────────────────────────── boss cities # List supported cities boss --version # Show version boss -v search "Python" # Verbose logging (request timing)
If you are an employer on BOSS直聘, these commands let you manage candidates from the terminal:
# ─── Search & Discover (搜索 & 发现) ───────────── boss recruiter search "golang" --city 深圳 --exp 3-5年 # Search candidates boss recruiter recommend # Recommended candidates boss recruiter recommend --job <encryptJobId> # Switch to different 岗位 boss recruiter recommend -p 2 # Next page # ─── Greet & Communicate (沟通) ────────────────── boss recruiter greet <encryptGeekId> # Initiate chat with candidate boss recruiter batch-view "Python" --city 杭州 -n 10 # Batch view top 10 (triggers "viewed" notice) boss recruiter inbox # View candidate messages boss recruiter inbox --job <encryptJobId> -p 2 # Filter by job, page 2 boss recruiter reply <friendId> "感谢您的关注..." # Reply to candidate boss recruiter chat <friendId> # View chat history # ─── Chat Actions (沟通页操作) ─────────────────── boss recruiter request-resume <friendId> --yes # 求简历 boss recruiter exchange-phone <friendId> --yes # 换电话 boss recruiter exchange-wechat <friendId> --yes # 换微信 boss recruiter invite-interview <geekId> --job <id> # 约面试 boss recruiter mark-unsuitable <geekId> --job <id> # 不合适 # ─── Resume (简历) ─────────────────────────────── boss recruiter resume <encryptGeekId> # View full resume in terminal boss recruiter resume-download <id> --job <jobId> # Download resume as Markdown boss recruiter geek <encryptGeekId> --job-id 526908510 # Quick candidate info # ─── Job Management (职位管理) ─────────────────── boss recruiter jobs # List your posted jobs boss recruiter job-close <encryptJobId> --yes # Take job offline boss recruiter job-reopen <encryptJobId> --yes # Bring job back online # ─── Export & Tags ─────────────────────────────── boss recruiter labels # View candidate tags boss recruiter export -o candidates.csv # Export to CSV boss recruiter export --format json -o out.json # Export to JSON
# 1. Check your posted jobs boss recruiter jobs # 2. Browse recommended candidates for a specific job boss recruiter recommend --job f806096ea327cd610nZ80t21FVNQ # 3. Search for specific skills boss recruiter search "golang" --city 深圳 # 4. View a candidate's full resume boss recruiter resume <encryptGeekId> --job <encryptJobId> # 5. Download resume for offline review boss recruiter resume-download <encryptGeekId> --job <encryptJobId> # 6. Start a conversation boss recruiter greet <encryptGeekId> # 7. Check inbox and reply boss recruiter inbox -p 1 boss recruiter reply <friendId> "感谢您的关注，方便电话聊聊吗？" # 8. Export all candidates boss recruiter export --format json -o candidates.json
All commands with --json / --yaml use a unified output envelope (see SCHEMA.md):
{
"ok": true,
"schema_version": "1",
"data": { ... }
}--json → explicit JSONboss search X --json | jq .data)boss-cli supports multiple authentication methods:
~/.config/boss-cli/credential.jsonboss login auto-extracts browser cookies first, falls back to QR login. Use --cookie-source chrome to specify a browser, or --qrcode to skip browser detection. The command now verifies the saved credential against a real authenticated API before reporting success.
New Chrome/Edge versions may prevent browser-cookie3 from decrypting the on-disk Cookie database. As a safe workaround, let the browser return its own cookies over an explicitly enabled loopback CDP endpoint:
# Use a separate browser profile for CDP. & "${env:ProgramFiles(x86)}\Microsoft\Edge\Application\msedge.exe" ` --remote-debugging-port=9222 ` --user-data-dir="$env:USERPROFILE\.boss-cli-edge" # Log in to zhipin.com in that window, then: $env:BOSS_CDP_URL = "http://127.0.0.1:9222" boss login boss status Remove-Item Env:BOSS_CDP_URL
The CLI tries CDP first when BOSS_CDP_URL is set and no --cookie-source is specified. Both the HTTP and WebSocket addresses must be loopback addresses; proxies and redirects are disabled. CDP lets the browser decrypt its own cookies. If CDP fails, the usual browser-cookie3 and QR login fallbacks still apply. Close the debugging browser after login. The separate profile persists at the path above; delete it when no longer needed.
boss recommend follows the live web app's current recommendation data source and request context, which improves compatibility when the legacy recommendation endpoint is rejected.
boss status --json now reports per-flow health such as search_authenticated and recommend_authenticated, which helps diagnose partial-session issues. To avoid turning repeated checks into their own anti-bot problem, health snapshots are cached briefly in-memory.
Saved cookies auto-refresh from browser after 7 days. If browser refresh fails, falls back to stale cookies and logs a warning.
random.gauss(0.3, 0.15)Set-Cookie headers merged back into sessionsec-ch-ua, DNT, Priority headersboss -v shows request URLs, status codes, and timingboss-cli ships with a SKILL.md that teaches AI agents how to use it.
npx skills add jackwener/boss-cli
| Flag | Description |
|---|---|
-g |
Install globally (user-level, shared across projects) |
-a claude-code |
Target a specific agent |
-y |
Non-interactive mode |
mkdir -p .agents/skills git clone git@github.com:jackwener/boss-cli.git .agents/skills/boss-cli
⚠️ ClawHub install method is deprecated and no longer supported. Use Skills CLI or Manual Install above.
boss_cli/
├── __init__.py # Package version
├── cli.py # Click entry point (lightweight, add_command only)
├── client.py # API client (rate-limit, cooldown, retry, anti-detection)
├── auth.py # Authentication (10+ browsers, QR login, TTL refresh)
├── constants.py # URLs, headers (Chrome 145), city codes, filter enums
├── exceptions.py # Structured exceptions (BossApiError hierarchy)
├── index_cache.py # Short-index cache for `boss show`
└── commands/
├── _common.py # SCHEMA envelope, handle_command, stderr console
├── auth.py # login (--cookie-source/--qrcode), logout, status, me
├── search.py # search, recommend, detail, show, export, history, cities
├── personal.py # applied, interviews
├── social.py # chat, greet (--json), batch-greet (1.5s delay)
└── recruiter.py # recruiter-jobs, inbox, geek, chat, labels, export
# Install dependencies uv sync # Run tests uv run pytest tests/ -v # Smoke tests (need cookies) uv run pytest tests/ -v -m smoke # Lint uv run ruff check .
Q: boss status says not authenticated but local cookies still exist
boss status now verifies the session against a real search API. If authenticated=false, your local credential file exists but the underlying web session is no longer usable.
Q: 环境异常 (__zp_stoken__ 已过期)
Your session cookies have expired. Run boss logout && boss login to refresh. If QR login only returns a partial cookie set, log in from a browser first and then run boss login.
Q: 暂无投递记录 but I have applied
Some features require fresh __zp_stoken__. Try re-logging in from a browser, then boss login.
Q: Search returns no results
Check your city filter. Some keywords are city-specific. Use boss cities to see available cities.
--cookie-source 指定浏览器boss show 3)，CSV/JSON 导出# 认证 boss login # 自动提取浏览器 Cookie，失败则二维码 boss login --cookie-source chrome # 指定浏览器 boss status # 检查登录状态 boss logout # 清除 Cookie # 搜索 & 详情 boss search "golang" --city 杭州 # 按城市搜索 boss search "AI" --industry 互联网 --scale 1000-9999人 # 行业+规模 boss search "数据" --stage 已上市 --salary 30-50K # 融资+薪资 boss show 3 # 按编号查看详情 boss detail <securityId> --json # 指定 ID 查看（JSON envelope） boss export "Python" -n 50 -o jobs.csv # 导出 CSV # 推荐 & 历史 boss recommend # 个性化推荐 boss history # 浏览历史 # 个人中心 boss me --json # 个人资料（JSON） boss applied # 已投递 boss interviews # 面试邀请 boss chat # 沟通列表 # 打招呼 boss greet <securityId> --json # 单个打招呼 boss batch-greet "golang" -n 10 # 批量打招呼 boss batch-greet "golang" --dry-run # 预览 # 工具 boss cities # 城市列表 boss -v search "Python" # 详细日志
# 搜索 & 推荐 boss recruiter search "golang" --city 深圳 --exp 3-5年 boss recruiter recommend --job <encryptJobId> # 按岗位查看推荐牛人 boss recruiter recommend -p 2 # 翻页 # 沟通 boss recruiter greet <encryptGeekId> # 向候选人打招呼 boss recruiter batch-view "Python" -n 10 # 批量查看 (触发被查看通知) boss recruiter inbox -p 1 # 查看候选人消息 boss recruiter reply <friendId> "您好..." # 回复候选人 # 沟通页操作 boss recruiter request-resume <friendId> # 求简历 boss recruiter exchange-phone <friendId> # 换电话 boss recruiter exchange-wechat <friendId> # 换微信 boss recruiter invite-interview <id> --job <id> # 约面试 boss recruiter mark-unsuitable <id> --job <id> # 不合适 # 简历 boss recruiter resume <encryptGeekId> # 终端查看简历 boss recruiter resume-download <id> --job <id> # 下载简历为 Markdown # 职位管理 boss recruiter jobs # 查看招聘职位 boss recruiter job-close <encryptJobId> # 关闭职位 boss recruiter job-reopen <encryptJobId> # 重新开启 # 导出 boss recruiter labels # 查看标签 boss recruiter export -o candidates.csv # 导出候选人
环境异常 — Cookie 过期，执行 boss logout && boss login 刷新boss cities 查看支持的城市Apache-2.0