Content
<div align="center">
# Tool List
**A CLI tool designed for AI Agents to interact with BOSS Zhipin (China's largest recruitment platform). Structured JSON output, schema-driven capability discovery, 4-tier login fallback, recruiter workflow support, and a cross-platform adapter layer. See [README.en.md](README.en.md) for the English version.</div>
> A CLI tool designed for AI Agents to interact with BOSS Zhipin (China's largest recruitment platform). Structured JSON output, schema-driven capability discovery, 4-tier login fallback, recruiter workflow support, and a cross-platform adapter layer. See [README.en.md](README.en.md) for the English version.
---
## 💡 Why use boss-agent-cli?
Traditional job search: Open the webpage → Flip through dozens of pages → Check details one by one → Manually send greetings → Forgot to follow up on who.
**boss-agent-cli lets AI Agents do all the work for you**:
```bash
boss search "Golang" --city Guangzhou --welfare "double休,五险一金" # Search + Welfare screening
boss detail <security_id> # View details
boss greet <security_id> <job_id> # One-click greeting
boss pipeline # Pipeline tracking
boss digest # Daily report
```
All output is **structured JSON**, and Agents can understand and act on it with one call.
---
## 🧭 Navigation
- [Why use boss-agent-cli](#-why-use-boss-agent-cli)
- [Core Capabilities](#-core-capabilities)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Login](#-login)
- [Role Mode and Multi-Platform](#-role-mode-and-multi-platform)
- [AI Agent Integration](#-ai-agent-integration)
- [Command Reference](#-command-reference)
- [Troubleshooting](#-troubleshooting)
- [Configuration](#-configuration)
- [Technical Architecture](#-technical-architecture)
- [Contributing](#-contributing)
---
## 🌟 Core Capabilities
### Job Seeker Workflow
- `🔍 Job Discovery`: Keyword search, 8-dimensional screening, personalized recommendation, and numbered review of the same result. Commands: `search` `recommend` `show`
- `🎯 Welfare Screening`: `--welfare "double休,五险一金"` Automatically flip pages, supplement details, and match with AND logic. Commands: `search --welfare`
- `👋 Proactive Attack`: Directly send greetings from job details, batch greetings, and immediately communicate and apply. Commands: `detail` `greet` `batch-greet` `apply`
- `📊 Process Promotion`: Pipeline, follow-up reminders, daily summary, and application conversion funnel. Commands: `pipeline` `follow-up` `digest` `stats`
- `👀 Incremental Monitoring`: Save search conditions, regularly execute, mark new jobs, and precipitate shortlist. Commands: `watch` `preset` `shortlist`
- `💬 Communication Management`: Chat list, message history, structured summary, labels, and contact information exchange. Commands: `chat` `chatmsg` `chat-summary` `mark` `exchange`
- `🤖 AI Job Search Enhancement`: JD analysis, resume polishing, directional optimization, simulated interview, and communication guidance. Commands: `ai analyze-jd` `ai polish` `ai optimize` `ai interview-prep` `ai chat-coach`
### Recruiter Workflow
- `👔 Candidate Operation`: Application submission, candidate search, communication list, online resume viewing, and attachment resume request. Commands: `hr applications` `hr candidates` `hr chat` `hr resume` `hr request-resume`
- `💬 Recruitment Communication`: Directly reply to candidate messages, and integrate HR scenarios into the same JSON protocol. Commands: `hr reply`
- `📌 Job Management`: View jobs, list, and offline, as the smallest operable closed loop for recruiters. Commands: `hr jobs list` `hr jobs online` `hr jobs offline`
### Platform and Integration Foundation
- `🔌 Multi-Platform Abstraction`: `Platform` / `RecruiterPlatform` dual registry has been implemented, BOSS Zhipin available, and Zhilian Recruitment framework has been accessed. Commands: `--platform zhipin|zhilian`
- `📤 Structured Output`: stdout only outputs JSON envelope, suitable for CLI orchestration, Shell Agent, MCP, and Python SDK. Commands: `schema` `export`
- `🧩 Agent Access`: The same capability can be exposed to Agents through Skill, subprocess, MCP, and Python SDK. Documents: `docs/agent-quickstart.md` `docs/agent-hosts.md`
---
## 📦 Installation
```bash
# Recommended: Install via uv (seconds, automatic isolation)
uv tool install boss-agent-cli
# Install browser (for login)
patchright install chromium
```
<details>
<summary>📋 Other installation methods</summary>
```bash
# pipx (isolated environment)
pipx install boss-agent-cli
patchright install chromium
# pip
pip install boss-agent-cli
patchright install chromium
# From source (for development)
git clone https://github.com/can4hou6joeng4/boss-agent-cli.git
cd boss-agent-cli
uv sync --all-extras
uv run patchright install chromium
```
</details>
---
## 🚀 Quick Start
```bash
# 1. Environment self-check
boss doctor
# 2. Login (automatic four-level degradation)
boss login
# 3. Verify login status
boss status
# 4. Search for Golang jobs in Guangzhou, requiring double休 and 五险一金
boss search "Golang" --city Guangzhou --welfare "double休,五险一金"
# 5. View details → Send greetings → Apply
boss detail <security_id>
boss greet <security_id> <job_id>
boss apply <security_id> <job_id>
# 6. Recommendation + Export
boss recommend
boss export "Golang" --city Guangzhou --count 50 -o jobs.csv
# 7. Pipeline + Daily summary
boss pipeline
boss digest
# 8. Incremental monitoring
boss watch add my-golang "Golang" --city Guangzhou --welfare "双休"
boss watch run my-golang
# 9. Recruiter mode (HR perspective)
boss hr applications # Candidate application
boss hr candidates "Golang" # Search candidates
boss hr reply <friend_id> "Hello" # Reply to messages
boss hr jobs list # My posted jobs
```
---
## 🔐 Login
`boss login` adopts a **four-level degradation strategy**, adapting to different environments:
| Level | Method | Description | Requires browser? |
|:---:|------|------|:---:|
| 1 | **Cookie extraction** | Extract from local Chrome/Firefox/Edge and 10+ browsers without scanning | No |
| 2 | **CDP login** | Reuse Chrome with `--remote-debugging-port` | Requires Chrome |
| 3 | **QR httpx** | Pure HTTP QR code scanning, no need to install any browser | No |
| 4 | **patchright** | Anti-detection Chromium as a last resort | Requires Chromium |
<details>
<summary>📖 CDP startup example</summary>
```bash
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222 --user-data-dir=/tmp/boss-chrome
# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/boss-chrome
# Use CDP login
boss --cdp-url http://localhost:9222 login --cdp
```
</details>
---
## 🎭 Role Mode and Multi-Platform
boss-agent-cli covers both job seeker and recruiter roles and abstracts multiple recruitment platforms.
### Role switching
| Option | Description | Typical commands |
|------|------|----------|
| `--role candidate` (default) | Job seeker perspective | `search` / `greet` / `apply` |
| `--role recruiter` | Recruiter perspective | `hr applications` / `hr candidates` |
Quick entry: `boss hr <subcommand>` automatically switches the current session to recruiter mode, no need to explicitly pass `--role`.
```bash
# Method A: Explicitly specify with --role
boss --role recruiter ...
# Method B: Recruiter quick group (automatic role switching)
boss hr applications
boss hr candidates "Golang"
```
### Multi-platform abstraction
`Platform` / `RecruiterPlatform` dual registry makes command layer not coupled with specific platform protocols:
| Platform | Job seeker | Recruiter | Status |
|------|:------:|:------:|------|
| BOSS Zhipin (`zhipin`) | ✅ | ✅ | Default |
| Zhilian Recruitment (`zhilian`) | 🟡 Skeleton | — | Actual implementation tracking [Issue #140](https://github.com/can4hou6joeng4/boss-agent-cli/issues/140) |
```bash
# Specify platform
boss --platform zhilian search "Python"
# Set as default
boss config set platform zhilian
```
Design details see [docs/platform-abstraction.md](docs/platform-abstraction.md).
---
## 🤖 AI Agent Integration
Recommended reading: [Agent Quickstart](docs/agent-quickstart.md) · [Host Examples](docs/agent-hosts.md) · [Capability Matrix](docs/capability-matrix.md)
### Method 1: Skill installation (recommended)
```bash
npx skills add can4hou6joeng4/boss-agent-cli
```
After installation, Agents automatically gain the ability to call `boss` commands without manual configuration.
### Method 2: Manual configuration
Add to AI Agent's rule file:
```markdown
When users require BOSS Zhipin operations such as searching for jobs, applying, or sending greetings, call `boss` CLI through Bash:
1. Run `boss status` to check login status
2. If not logged in, run `boss login` to prompt user to scan QR code
3. Call search / recommend / detail / greet according to user intent
4. Parse stdout JSON, `ok` field to determine success or failure
5. Use `--welfare` parameter when users mention welfare requirements
```
### Method 3: Python direct embedding (no subprocess)
Package released with `py.typed` marker, can be used as a typed Python library:
```python
from boss_agent_cli import AuthManager, BossClient, AuthRequired
auth = AuthManager(data_dir=Path("~/.boss-agent").expanduser())
try:
with BossClient(auth) as client:
result = client.search_jobs("Golang", city="广州")
except AuthRequired:
... # Prompt user to boss login
```
Public API (see `boss_agent_cli.__all__`): `AuthManager` / `BossClient` / `CacheStore` / `JobItem` / `JobDetail` / `AIService` / `ResumeData` and other core types.
### Output protocol
All commands output JSON to stdout, unified envelope format:
```json
{
"ok": true,
"schema_version": "1.0",
"command": "search",
"data": [...],
"pagination": {"page": 1, "has_more": true, "total": 15},
"error": null,
"hints": {"next_actions": ["boss detail <security_id>"]}
}
```
| Convention | Description |
|------|------|
| `stdout` | Only JSON structured data |
| `stderr` | Logs and progress information |
| `exit 0` | Command successful (`ok=true`) |
| `exit 1` | Command failed (`ok=false`) |
---
## 📚 Command Reference
### Basic operations
| Command | Description |
|------|------|
| `boss schema` | Output complete tool capability description JSON (33 top-level commands + hr group expansion, Agent first call) |
| `boss login` | Four-level degradation login |
| `boss logout` | Logout |
| `boss status` | Check login status |
| `boss doctor` | Diagnose environment, dependencies, credential integrity, and network |
| `boss me` | My information (user/resume/expected/application records) |
### Job search
| Command | Description |
|------|------|
| `boss search <query>` | Search for jobs (support `--welfare` screening, `--preset` preset) |
| `boss recommend` | Personalized recommendation |
| `boss detail <security_id>` | Job details (`--job-id` fast channel) |
| `boss show <#>` | View last search results by number |
| `boss cities` | 40 supported cities |
### Job seeker actions
| Command | Description |
|------|------|
| `boss greet <sid> <jid>` | Send greetings |
| `boss batch-greet <query>` | Batch greetings (up to 10) |
| `boss apply <sid> <jid>` | Apply/immediately communicate (idempotent) |
| `boss exchange <sid>` | Exchange mobile/WeChat |
### Communication Follow-up
| Command | Description |
|------|------|
| `boss chat` | Communication list (export html/md/csv/json) |
| `boss chatmsg <sid>` | Chat message history |
| `boss chat-summary <sid>` | Structured summary |
| `boss mark <sid> --label X` | Label management (9 types) |
| `boss interviews` | Interview invitations |
| `boss history` | Browsing history |
### Pipeline Monitoring
| Command | Description |
|------|------|
| `boss pipeline` | Job pipeline (each stage status) |
| `boss follow-up` | Follow-up reminders (timeout not advanced) |
| `boss digest` | Daily summary |
| `boss watch add/list/remove/run` | Incremental monitoring |
| `boss shortlist add/list/remove` | Candidate pool |
| `boss preset add/list/remove` | Search preset |
### Recruiter Mode
| Command | Description |
|------|------|
| `boss hr applications` | View candidate application list |
| `boss hr resume` | View or request candidate resume |
| `boss hr chat` | View communication list with candidate |
| `boss hr jobs list/offline/online` | Job list and online/offline management |
| `boss hr candidates <keyword>` | Search candidates |
| `boss hr reply <friend_id> <message>` | Reply to candidate message |
| `boss hr request-resume <friend_id> --job-id <id>` | Request candidate to share attachment resume |
### Resume and AI
| Command | Description |
|------|------|
| `boss resume init/list/show/edit/delete/export/import/clone/diff/link/applications` | Local resume management |
| `boss ai config` | Configure AI service |
| `boss ai analyze-jd` | Analyze job requirements |
| `boss ai polish` | Polish resume |
| `boss ai optimize` | Optimize for target job |
| `boss ai suggest` | Job search suggestions |
| `boss ai reply` | Generate recruiter message reply draft |
| `boss ai interview-prep` | Generate simulated interview questions based on JD |
| `boss ai chat-coach` | Provide communication suggestions based on chat records |
> Supports latest models including Claude 4.7 / GPT-5 / DeepSeek-V3 / Qwen3, see [Recommended models and entrance](docs/integrations/ai-models.md).
### System Management
| Command | Description |
|------|------|
| `boss config list/set/reset` | Configuration management |
| `boss clean` | Clean cache |
| `boss stats` | Application conversion funnel statistics (greeted/applied/shortlist) |
| `boss export <query>` | Export results (CSV/JSON) |
<details>
<summary>🔎 Search filter parameter details</summary>
```bash
boss search "golang" \
--city Guangzhou \ # City (40 options)
--salary 20-50K \ # Salary range
--experience 3-5 years \ # Experience requirement
--education Bachelor \ # Education requirement
--scale 100-499 people \ # Company scale
--industry Internet \ # Industry
--stage Listed \ # Financing stage
--welfare "Flexible work hours, Five insurance and one fund" # Welfare filter (AND logic)
```
**Welfare filter working principle**:
1. Check job welfare tags (`welfareList`)
2. If tags do not match, automatically search job description
3. Automatic page turning (up to 5 pages)
4. Each result with `welfare_match` to explain match source
Supported keywords: `Flexible work hours` `Five insurance and one fund` `Year-end bonus` `Meal allowance` `Housing allowance` `Regular physical examination` `Stock options` `Overtime compensation` `Paid annual leave`
</details>
---
## 🔧 Diagnostics and Troubleshooting
```bash
boss doctor
```
| Check item | Description |
|--------|------|
| `python` | Python version >= 3.10 |
| `patchright` | CLI installed |
| `patchright_chromium` | Chromium installed |
| `cookie_extract` | Local browser Cookie extractable |
| `auth_session` | Login status exists and can be decrypted |
| `auth_token_quality` | Core credentials (wt2 / stoken) |
| `cookie_completeness` | Auxiliary credentials (wbg / zp_at) |
| `cdp` | Chrome debugging port can be connected |
| `network` | zhipin.com can be accessed |
<details>
<summary>📖 Common problem fixes</summary>
```bash
# Install browser kernel
patchright install chromium
# Rebuild login status
boss logout && boss login
# CDP diagnosis
boss --cdp-url http://localhost:9222 doctor
```
**auth_session shows "damaged"**: Login status comes from old machine fingerprint or file damage → `boss logout && boss login`
**auth_token_quality status meanings**:
- `wt2/stoken both exist`: Complete, can be used normally
- `wt2 exists, stoken missing`: Partially available, interface failure `boss login` refresh
- `wt2 missing`: Invalid → `boss logout && boss login`
</details>
<details>
<summary>📖 Error code and automatic repair</summary>
| Error code | Meaning | Agent automatic repair |
|--------|------|---------------|
| `AUTH_REQUIRED` | Not logged in | `boss login` |
| `AUTH_EXPIRED` | Login expired | `boss login` |
| `RATE_LIMITED` | Frequency too high | Wait and retry |
| `TOKEN_REFRESH_FAILED` | Token refresh failed | `boss login` |
| `ACCOUNT_RISK` | Risk control intercept | CDP Chrome retry |
| `INVALID_PARAM` | Parameter error | Correct parameters |
| `ALREADY_GREETED` | Already greeted | Skip |
| `GREET_LIMIT` | Today's limit used up | Inform user |
| `NETWORK_ERROR` | Network error | Retry |
| `AI_NOT_CONFIGURED` | AI not configured | `boss ai config` |
</details>
---
## ⚙️ Configuration
```bash
boss config list # View all configurations
boss config set default_city Guangzhou # Set default city
boss config reset # Restore default
```
<details>
<summary>📖 Complete configuration items</summary>
`~/.boss-agent/config.json`:
```json
{
"default_city": null,
"default_salary": null,
"request_delay": [1.5, 3.0],
"batch_greet_delay": [2.0, 5.0],
"batch_greet_max": 10,
"log_level": "error",
"login_timeout": 120,
"cdp_url": null,
"export_dir": null
}
```
| Configuration item | Description |
|--------|------|
| `default_city` | Default city |
| `default_salary` | Default salary range |
| `request_delay` | Request interval (seconds), `[min, max]` |
| `batch_greet_delay` | Batch greeting interval |
| `batch_greet_max` | Batch greeting limit |
| `log_level` | Log level (error/warning/info/debug) |
| `login_timeout` | Login timeout (seconds) |
| `cdp_url` | CDP address |
| `export_dir` | Export directory |
</details>
---
## 🏗️ Technical Architecture
```
CLI (Click)
│
├── AuthManager ── Cookie extraction / CDP / QR httpx / patchright
│ └── TokenStore (Fernet + PBKDF2 machine binding encryption)
│
├── Platform abstraction layer (multi-platform registry)
│ ├── BossPlatform (job seeker) / BossRecruiterPlatform (recruiter)
│ └── ZhilianPlatform (skeleton has been accessed, real implementation tracking Issue #140)
│
├── BossClient / BossRecruiterClient ── httpx (low risk) + browser (high risk) dual channel
│ ├── RequestThrottle (Gaussian delay + burst penalty)
│ ├── BrowserSession (CDP / Bridge / patchright)
│ └── BOSS direct employment wapi (job seeker 30 endpoints + recruiter 24 endpoints, 54 endpoints in total)
│
├── CacheStore (SQLite WAL)
├── AIService (OpenAI / Anthropic / compatible API)
└── output.py → JSON envelope → stdout
```
| Level | Selection |
|------|------|
| Language | Python >= 3.10 |
| CLI | Click |
| HTTP | httpx |
| Browser | patchright (Playwright anti-detection fork) |
| Cookie | browser-cookie3 (10+ browsers) |
| Encryption | cryptography (Fernet + PBKDF2) |
| Database | sqlite3 (WAL mode) |
| Rendering | rich |
| AI | OpenAI / Anthropic Chat Completions API |
| Testing | pytest (1042 items) |
---
## 🤝 Contribution
Welcome to submit Issues and Pull Requests.
```bash
# Local development
git clone https://github.com/can4hou6joeng4/boss-agent-cli.git
cd boss-agent-cli
uv sync --all-extras
uv run pytest tests/ -v # Run tests
uv run ruff check src/ # Code check
```
See [CONTRIBUTING.md](CONTRIBUTING.md)
---
## 🙏 Acknowledgements
- [geekgeekrun](https://github.com/geekgeekrun/geekgeekrun) — Browser automation + anti-detection strategy
- [boss-cli](https://github.com/jackwener/boss-cli) — CLI structured output + Agent friendly design
- [opencli](https://github.com/jackwener/opencli) — Browser Bridge architecture concept
---
## ⚠️ Disclaimer
This project is only for learning and communication. Please comply with relevant laws and regulations and BOSS direct employment platform user agreement. All consequences caused by improper use shall be borne by the user and have nothing to do with the project author.
---
## 📑 License
[MIT](LICENSE)
## 👭 Links
- [LINUX DO - New ideal community](https://linux.do/)
