boss-cli

name	boss-cli
description	Use boss-cli for ALL BOSS 直聘 operations — searching jobs, viewing recommendations, managing applications, chatting with recruiters, and batch greeting. Invoke whenever the user requests any job search or recruitment platform interaction on BOSS 直聘.
author	jackwener
version	0.3.0
tags	["boss","zhipin","boss直聘","job-search","recruitment","cli"]

boss-cli — BOSS 直聘 CLI Tool

Binary: boss Credentials: browser cookies (auto-extracted from 10+ browsers) or QR code login (--qrcode)

Setup

# Install (requires Python 3.10+)
uv tool install kabi-boss-cli
# Or: pipx install kabi-boss-cli

# Upgrade to latest (recommended)
uv tool upgrade kabi-boss-cli
# Or: pipx upgrade kabi-boss-cli

Authentication

IMPORTANT FOR AGENTS: Before executing ANY boss command, check if credentials exist first. Do NOT assume cookies are configured.

Step 0: Check if already authenticated

boss status --json 2>/dev/null | jq -r '.authenticated' | grep -q true && echo "AUTH_OK" || echo "AUTH_NEEDED"

If AUTH_OK, skip to Command Reference. If AUTH_NEEDED, proceed to Step 1.

Step 1: Guide user to authenticate

Ensure user is logged into zhipin.com in any supported browser (Chrome, Firefox, Edge, Brave, Arc, Chromium, Opera, Vivaldi, Safari, LibreWolf). Then:

boss login                              # auto-detect browser with valid cookies
boss login --cookie-source chrome       # specify browser explicitly
boss login --qrcode                     # QR code login — scan with Boss app

Verify with:

boss status
boss me --json | jq '.data.name'

Step 2: Handle common auth issues

Symptom	Agent action
环境异常 (__zp_stoken__ 已过期)	Run boss logout && boss login
未登录	Run boss login
Rate limited (code=9)	Auto-cooldown built-in; wait and retry
API timeout	Check network, retry

Agent Defaults

All machine-readable output uses the envelope documented in SCHEMA.md. Payloads live under .data.

• Non-TTY stdout → auto YAML
• --json / --yaml → explicit format
• Rich output → stderr (safe for pipes: boss search X --json | jq .data)

Command Reference

Search & Browse

Command	Description	Example
boss search <keyword>	Search jobs with filters	boss search "golang" --city 杭州 --salary 20-30K
boss show <index>	View job #N from last search	boss show 3
boss detail <securityId>	View full job details	boss detail abc123 --json
boss export <keyword>	Export search results to CSV/JSON	boss export "Python" -n 50 -o jobs.csv
boss recommend	Personalized recommendations	boss recommend -p 2 --json
boss history	View browsing history	boss history --json
boss cities	List supported cities	boss cities

Personal Center

Command	Description	Example
boss me	View profile (name, age, degree)	boss me --json
boss applied	View applied jobs	boss applied -p 1 --json
boss interviews	View interview invitations	boss interviews --json
boss chat	View communicated bosses	boss chat --json

Actions

Command	Description	Example
boss greet <securityId>	Greet a boss / apply	boss greet abc123 --json
boss batch-greet <keyword>	Batch greet from search	boss batch-greet "Python" --city 杭州 -n 5
boss batch-greet <keyword> --dry-run	Preview without sending	boss batch-greet "golang" --dry-run

Account

Command	Description
boss login	Extract cookies from browser (auto-detect, fallback QR)
boss login --cookie-source <browser>	Extract from specific browser
boss login --qrcode	QR code login only (terminal QR output)
boss status	Check authentication status (shows cookie names)
boss logout	Clear saved credentials

Search Filter Options

Filter	Flag	Values
City	--city	北京, 上海, 杭州, 深圳, etc. (use boss cities for full list)
Salary	--salary	3K以下, 3-5K, 5-10K, 10-15K, 15-20K, 20-30K, 30-50K, 50K以上
Experience	--exp	不限, 在校/应届, 1年以内, 1-3年, 3-5年, 5-10年, 10年以上
Degree	--degree	不限, 大专, 本科, 硕士, 博士
Industry	--industry	互联网, 电子商务, 游戏, 人工智能, 金融, 教育培训, 医疗健康, etc.
Company Scale	--scale	0-20人, 20-99人, 100-499人, 500-999人, 1000-9999人, 10000人以上
Funding Stage	--stage	未融资, 天使轮, A轮, B轮, C轮, D轮及以上, 已上市, 不需要融资
Job Type	--job-type	全职, 兼职, 实习

Agent Workflow Examples

Search → Batch Greet pipeline

# Preview first
boss batch-greet "golang" --city 杭州 --salary 20-30K --dry-run
# Then execute
boss batch-greet "golang" --city 杭州 --salary 20-30K -n 10 -y

Search → Detail pipeline (structured)

# Search and extract securityId
SEC_ID=$(boss search "golang" --city 杭州 --json | jq -r '.data.jobList[0].securityId')
# Get full detail
boss detail "$SEC_ID" --json | jq '.data.jobInfo | {jobName, salaryDesc, skills}'

Daily job check workflow

boss recommend --json | jq '.data.jobList | length'  # Check recommendations count
boss search "Python" --city 杭州 --json               # Search specific jobs
boss show 1                                            # View top result details
boss applied --json                                    # Check application status
boss interviews --json                                 # Check interview invitations
boss chat --json                                       # Check messages
boss history --json                                    # Review browsing history

Export pipeline

boss export "golang" --city 杭州 --salary 20-30K -n 50 -o jobs.csv
boss export "Python" -n 100 --format json -o jobs.json

Profile check

boss me --json | jq '.data | {name, age, degreeCategory}'

Error Codes

Structured error codes returned in the error.code field (see SCHEMA.md):

• not_authenticated — cookies expired or missing
• rate_limited — too many requests (auto-cooldown built-in)
• invalid_params — missing or invalid parameters
• api_error — upstream API error
• unknown_error — unexpected error

Limitations

• No message sending — cannot send chat messages (MQTT/Protobuf required)
• No resume editing — cannot edit resume from CLI
• No company search — company pages return HTML (need zp_stoken)
• Single account — one set of cookies at a time
• Rate limited — batch-greet has built-in 1.5s delay between greetings

Anti-Detection Notes for Agents

• Do NOT parallelize requests — built-in Gaussian jitter delays exist for account safety
• Rate-limit auto-recovery: if code=9 occurs, client auto-cools-down with increasing delays (10s→20s→40s→60s) and retries once
• Use -v flag for debugging: boss -v search "Python" shows request timing
• Batch greet limit: recommend ≤ 10 greetings per session to avoid detection
• Cookies auto-refresh: if ≥ 7 days old, boss-cli auto-tries browser extraction
• Re-login if __zp_stoken__ expires: run boss logout && boss login

Safety Notes

• Do not ask users to share raw cookie values in chat logs.
• Prefer local browser cookie extraction over manual secret copy/paste.
• If auth fails, ask the user to re-login via boss login.
• Agent should treat cookie values as secrets (do not echo to stdout).
• Built-in rate-limit delay protects accounts; do not bypass it.