boss-cli: driving the BOSS直聘 job search from a terminal

Authentication by cookie extraction, with a QR fallback

boss-cli is a command line client for BOSS Zhipin, the Chinese job platform, and its authentication story is the first thing to understand because it determines how the tool is installed and how it breaks.

The documented login command auto-detects browser cookies, with a fallback to QR code login, and there is a --cookie-source option for explicit browser selection when the auto-detection picks the wrong one. The features list puts the number at 10+ browsers supported for auto-extraction, and it also claims live validation against real search APIs, which is the detail that matters in practice: the tool does not merely read a cookie file, it checks the session against the actual service.

The status and logout commands complete the picture. `boss status` checks login status, validates a real search session and shows the cookie names, which is what you want when a session goes stale and you need to see whether the tool still holds something usable. `boss logout` clears the saved cookies.

The dependency behind this is browser-cookie3 at 0.19 or newer, and the packaging offers an optional browser extra with camoufox, which suggests the project also supports a more evasive browser profile when the straightforward extraction is not enough. The project is Apache-2.0 licensed in the manifest, though the licence reported for the repository is one GitHub cannot classify, the package version is 0.3.6, the classifier says Development Status :: 3 - Alpha, and the last push to the main branch was on 2026-10-09.

A search with a filter per job attribute

The search surface is where most of the practical value sits, and the number of filters is the thing to notice. The features list names city, salary, experience, degree, industry, scale, stage and job type as the available filters, and the usage examples show one flag per attribute.

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

Two things are worth pulling out of that. The filters are in the vocabulary of the platform itself, so a company scale filter takes a headcount range and a funding stage filter takes a stage name, which means a query can express what a human would type into the site's own filter panel. And pagination is a flag, -p, so the search is a stream of pages rather than a single response, which is what a script needs.

The other commands in the same group complete the flow. `boss show 3` views job number 3 from the last search, which is a short index rather than an identifier, and `boss detail <securityId>` pulls the full details for one posting. The `boss export` command writes results to CSV or JSON, with a count and an output path, so a search becomes a local dataset.

The job identifiers are the site's own encrypted identifiers, securityId for a posting and encryptGeekId for a candidate, and they appear throughout the command set.

The rest of the applicant surface, and the greet commands

Beyond search, the tool covers the parts of a job search that live in the account rather than in a query.

There is `boss recommend` for personalised recommendations based on the profile, with its own pagination and a JSON mode. `boss me` shows personal information and resume status. `boss applied` lists applied jobs, `boss interviews` shows interview invitations, `boss history` browses the job viewing history, and `boss chat` lists the bosses you have communicated with.

The greet commands are the ones that write rather than read. `boss greet <securityId>` sends a greeting to a boss, and `boss batch-greet` does the same to the top results of a search, with a count and the same filters the search uses. The batch variant has a --dry-run flag that previews without sending, and the features list notes a 1.5 second rate-limit delay between sends.

That rate limit is the detail that shows the author's thinking. Batch greeting is the classic way to get an account flagged, and a tool that fires a hundred greetings in a second would burn the session you spent authenticating. A deliberate delay and a dry run are the two features that make the feature usable.

There is also a small set of utilities: `boss cities` lists the supported cities, 40+ of them, `boss --version` prints the version, and `boss -v search "Python"` turns on verbose logging with request timing, which is the first thing to reach for when a query returns something you did not expect.

One detail about the interface is worth naming. The features list says the tool is agent-friendly, with a structured output envelope of {ok, schema_version, data} and Rich output on stderr. The JSON modes on the individual commands then produce that envelope, which means the human-readable rendering and the machine-readable payload are separate streams rather than the same text in two shapes.

Recruiter mode, and the candidate-facing commands

The other half of the tool is for the other side of the marketplace, and it is the more unusual half of the project.

If you are an employer on BOSS Zhipin, the recruiter subcommands let you work with candidates from the terminal.

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 inbox                                        # View candidate messages
boss recruiter reply <friendId> "感谢您的关注..."            # Reply to candidate
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>          # 不合适

The design detail is the --yes flag on the actions that have consequences. Requesting a resume, exchanging a phone number and exchanging a WeChat contact each take a --yes confirmation flag. A script that batch-processes candidates will not silently contact five hundred of them; it will error out unless the caller passes --yes deliberately.

There is also a bulk view command, `boss recruiter batch-view`, which views the top N candidates and, as the README notes, triggers a viewed notice on the platform side. That is a one-way door in the other direction, since a viewed notice is visible to the candidate, so it is the command to be careful with.

Candidate data can be exported as CSV or JSON, and a resume can be viewed in the terminal or downloaded. The features list mentions candidate data export and chat history alongside posted-job management.

The project also carries a SCHEMA.md and a SKILL.md at the top level, which suggests the output schema is documented formally and that there is an agent skill definition alongside it, and the tests directory has a smoke marker for end-to-end tests requiring live cookies, deselected with -m "not smoke".

Installation, packaging and the dependency set

The install instructions give three routes, and the first two are the interesting ones.

# 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]

The package name on PyPI is kabi-boss-cli even though the command is boss, and the tool is recommended over pipx because uv tool installs in an isolated environment and is faster. The yaml extra adds PyYAML support, which is separate from the JSON output, and the yaml extra is listed in the manifest alongside dev and browser extras.

Upgrading is a matching pair of commands, `uv tool upgrade kabi-boss-cli` or `pipx upgrade kabi-boss-cli`, and from source it is a clone, a cd and a `uv sync`.

The runtime dependencies are six and each maps to a feature. click at 8.0 or newer is the command line interface, rich at 13.0 or newer is the terminal rendering, httpx at 0.27 or newer is the HTTP client for the API calls, browser-cookie3 is the cookie extraction, websocket-client at 1.8 or newer handles the realtime connection, and qrcode at 7.0 or newer renders the login QR code.

The build backend is hatchling with the boss_cli package, the console script is boss = boss_cli.cli:cli, and ruff is configured with a target of py310 and a line length of 140. The project requires Python 3.10 or newer.

The repository also points to a family of related tools by the same author, for Xiaohongshu, Bilibili, Twitter, Discord, Telegram and Reddit, all described in the same shape, which tells you the author has built this pattern several times and the schema-and-agent framing is a house style rather than a one-off.

Editorial conclusion

Adopt boss-cli if you want your job search on BOSS直聘 to be scriptable, or if you are building an agent that has to read job postings as structured data rather than scrape a web page, because the {ok, schema_version, data} envelope and the JSON output modes exist for exactly that. Do not adopt it for anything high frequency, since it talks to a reverse-engineered API that a site can change at any time and the batch greet is deliberately rate limited. Before you build on it, check that your platform's terms allow scripted access, and expect to re-authenticate, because the authentication method is cookie extraction from a browser rather than a token you own.

Frequently asked questions

Official sources

1. Issues
2. jackwener/boss-cli on GitHub
3. README