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

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

Personal Center

Actions

Account

Search Filter Options

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.