# boss-cli
[](https://pypi.org/project/kabi-boss-cli/)
[](https://github.com/jackwener/boss-cli/actions/workflows/ci.yml)
[](https://pypi.org/project/kabi-boss-cli/)
A CLI for BOSS ็ด่ โ search jobs, view recommendations, manage applications, chat with recruiters, **and manage candidates as a recruiter** via reverse-engineered API ๐ค
[English](#features) | [ไธญๆ](#ๅ่ฝ็นๆง)
## More Tools
- [xiaohongshu-cli](https://github.com/jackwener/xiaohongshu-cli) โ Xiaohongshu CLI for notes, search, and interactions
- [bilibili-cli](https://github.com/jackwener/bilibili-cli) โ Bilibili CLI for videos, users, and search
- [twitter-cli](https://github.com/jackwener/twitter-cli) โ Twitter/X CLI for timelines, bookmarks, and posting
- [discord-cli](https://github.com/jackwener/discord-cli) โ Discord CLI for local-first sync, search, and export
- [tg-cli](https://github.com/jackwener/tg-cli) โ Telegram CLI for local-first sync, search, and export
- [rdt-cli](https://github.com/jackwener/rdt-cli) โ Reddit CLI for feed, search, posts, and interactions
## Features
- ๐ **Auth** โ auto-extract browser cookies (10+ browsers), QR code login, `--cookie-source` explicit browser selection, live validation against real search APIs
- ๐ **Search** โ jobs by keyword with city/salary/experience/degree/industry/scale/stage/job-type filters
- โญ **Recommendations** โ personalized job recommendations based on profile
- ๐ **Detail & Export** โ view full job details, short-index navigation (`boss show 3`), CSV/JSON export
- ๐ **History** โ browse job viewing history
- ๐ค **Profile** โ view personal info, resume status
- ๐ฎ **Applications** โ view applied jobs list
- ๐ **Interviews** โ view interview invitations
- ๐ฌ **Chat** โ view communicated boss list
- ๐ค **Greet** โ send greetings to recruiters, single or batch (with 1.5s rate-limit delay)
- ๐๏ธ **Cities** โ 40+ supported cities
- ๐ค **Agent-friendly** โ structured output envelope (`{ok, schema_version, data}`), Rich output on stderr
- ๐ **Recruiter Mode** โ view posted jobs, manage candidates, chat history, export candidate data (CSV/JSON)
## Installation
```bash
# 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:
```bash
uv tool upgrade kabi-boss-cli
# Or: pipx upgrade kabi-boss-cli
```
From source:
```bash
git clone git@github.com:jackwener/boss-cli.git
cd boss-cli
uv sync
```
## Usage
```bash
# โโโ 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)
```
## Recruiter Mode (้ไธป็ซฏ)
If you are an employer on BOSS็ด่, these commands let you manage candidates from the terminal:
```bash
# โโโ 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
```
### Recruiter Workflow Example
```bash
# 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
```
## Structured Output
All commands with `--json` / `--yaml` use a unified output envelope (see [SCHEMA.md](./SCHEMA.md)):
```json
{
"ok": true,
"schema_version": "1",
"data": { ... }
}
```
- **Non-TTY stdout** โ auto YAML (agent-friendly)
- **`--json`** โ explicit JSON
- **Rich output** โ stderr (won't pollute pipes: `boss search X --json | jq .data`)
## Authentication
boss-cli supports multiple authentication methods:
1. **Saved cookies** โ loads from `~/.config/boss-cli/credential.json`
2. **Browser cookies** โ auto-detects installed browsers (Chrome, Firefox, Edge, Brave, Arc, Chromium, Opera, Vivaldi, Safari, LibreWolf)
3. **QR code login** โ terminal QR output using Unicode half-blocks, scan with Boss ็ด่ APP
`boss 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.
#### Chromium 127+ on Windows (App-Bound Encryption)
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:
```powershell
# 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.
### Cookie TTL & Auto-Refresh
Saved cookies auto-refresh from browser after **7 days**. If browser refresh fails, falls back to stale cookies and logs a warning.
## Rate Limiting & Anti-Detection
- **Gaussian jitter**: request delays with `random.gauss(0.3, 0.15)`
- **Random long pauses**: 5% chance of 2-5s pause to mimic reading
- **Rate-limit auto-cooldown**: code=9 triggers exponential backoff (10sโ20sโ40sโ60s) + request delay doubling
- **Exponential backoff**: auto-retry on HTTP 429/5xx (max 3 retries)
- **Response cookie merge**: `Set-Cookie` headers merged back into session
- **HTML redirect detection**: catches auth redirects to login page
- **Browser fingerprint**: macOS Chrome 145 UA, `sec-ch-ua`, `DNT`, `Priority` headers
- **Request logging**: `boss -v` shows request URLs, status codes, and timing
## Use as AI Agent Skill
boss-cli ships with a [`SKILL.md`](./SKILL.md) that teaches AI agents how to use it.
### [Skills CLI](https://github.com/vercel-labs/skills) (Recommended)
```bash
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 |
### Manual Install
```bash
mkdir -p .agents/skills
git clone git@github.com:jackwener/boss-cli.git .agents/skills/boss-cli
```
### ~~OpenClaw / ClawHub~~ (Deprecated)
> โ ๏ธ ClawHub install method is deprecated and no longer supported. Use [Skills CLI](#skills-cli-recommended) or Manual Install above.
## Project Structure
```text
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
```
## Development
```bash
# 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 .
```
## Troubleshooting
**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๏ผ10+ ๆต่งๅจ๏ผ๏ผไบ็ปด็ ๆซ็ ็ปๅฝ๏ผ`--cookie-source` ๆๅฎๆต่งๅจ
- ๐ **ๆ็ดข** โ ๆๅ
ณ้ฎ่ฏๆ็ดข่ไฝ๏ผๆฏๆๅๅธ/่ช่ต/็ป้ช/ๅญฆๅ/่กไธ/่งๆจก/่่ต้ถๆฎต/่ไฝ็ฑปๅ็ญ้
- โญ **ๆจ่** โ ๅบไบๆฑ่ๆๆ็ไธชๆงๅๆจ่
- ๐ **่ฏฆๆ
& ๅฏผๅบ** โ ่ไฝ่ฏฆๆ
๏ผ็ผๅทๅฏผ่ช (`boss show 3`)๏ผCSV/JSON ๅฏผๅบ
- ๐ **ๅๅฒ** โ ๆฅ็ๆต่งๅๅฒ
- ๐ค **ไธชไบบ** โ ๆฅ็ไธชไบบ่ตๆ
- ๐ฎ **ๆ้** โ ๆฅ็ๅทฒๆ้่ไฝๅ่กจ
- ๐ **้ข่ฏ** โ ๆฅ็้ข่ฏ้่ฏท
- ๐ฌ **ๆฒ้** โ ๆฅ็ๆฒ้่ฟ็ Boss ๅ่กจ
- ๐ค **ๆๆๅผ** โ ๅ Boss ๆๆๅผ/ๆ้๏ผๆฏๆๆน้ๆไฝ๏ผๅ
็ฝฎ 1.5s ้ฒ้ฃๆงๅปถ่ฟ๏ผ
- ๐๏ธ **ๅๅธ** โ 40+ ๅๅธๆฏๆ
- ๐ค **Agent ๅๅฅฝ** โ ็ปๆๅ่พๅบ envelope๏ผRich ่พๅบ่ตฐ stderr
- ๐ **ๆ่ๆนๆจกๅผ** โ ๆฅ็่ไฝใๅ้ไบบ็ฎก็ใ่ๅคฉ่ฎฐๅฝใๅฏผๅบๅ้ไบบๆฐๆฎ (CSV/JSON)
## ไฝฟ็จ็คบไพ
```bash
# ่ฎค่ฏ
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" # ่ฏฆ็ปๆฅๅฟ
```
## ๆ่ๆนๆจกๅผ
```bash
# ๆ็ดข & ๆจ่
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` ๆฅ็ๆฏๆ็ๅๅธ
## License
Apache-2.0