# boss-agent-cli: a BOSS Zhipin job-search CLI built for AI agents

> boss-agent-cli wraps BOSS Zhipin job discovery, welfare filtering and recruiter workflows in a Python CLI that returns a JSON envelope on stdout. It is a local-assist tool, not a scraper you point at the site and forget.

**can4hou6joeng4/boss-agent-cli** — Local-assist BOSS Zhipin CLI for AI agents, search, welfare filtering, shortlist, JSON-envelope output; low-risk & compliant by default.

- Repository: https://github.com/can4hou6joeng4/boss-agent-cli
- Website: https://can4hou6joeng4.github.io/boss-agent-cli/
- Stars: 2,035 · Forks: 172
- Language: Python
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/can4hou6joeng4-boss-agent-cli

## What boss-agent-cli actually solves for a job seeker or a recruiter

Job platforms are built for humans clicking through pages. An agent that wants to search, filter and shortlist has to either drive a browser or reverse-engineer an undocumented HTTP surface. boss-agent-cli takes the second route but keeps the first as a fallback: the README describes it as a CLI that unifies job discovery, welfare filtering, a local resume store, AI assistance, application messaging, recruiter-side candidate handling and resumable crawling into one command tree. A human runs boss and lands in a pure terminal wizard. An agent calls the same workflows through JSON, schema, MCP or the Python API.

The audience is narrow and specific. It is for people who already have a BOSS Zhipin account and want their job search to be a scriptable, inspectable process rather than a browser session. It is also for tool builders who want a job-search capability inside an MCP host such as Claude Desktop or Cursor. The README states that boss schema exposes 39 top-level commands plus 9 first-level recruiter subcommands, grouped by workflow, and that schema is always the source of truth for what the tool can do. That framing matters: the project is not selling a scraping library, it is selling a described capability surface.

## The JSON envelope and why stdout is kept clean

Every command writes a structured envelope to stdout with the keys ok, data, pagination, error and hints, and exits 0 or 1. That is the whole contract. An agent does not parse human-readable tables, it checks ok, reads data, and follows hints when something failed. The README is explicit that stdout carries only the envelope, which is what makes the tool composable in shell pipelines and MCP hosts.

The project separates two kinds of failure. Capabilities the platform has not implemented return NOT_SUPPORTED, so a caller can distinguish "this tool cannot do that" from "this call went wrong". Authentication expiry, account risk and network errors keep structured errors plus recovery actions. Long-running flows stay under timeout, retry, budget, checkpoint and stop controls.

One design note worth flagging: the README says the historical operating_mode values assisted and research remain compatible, but both modes can now call every implemented capability, and mode-level COMPLIANCE_BLOCKED is no longer produced. That is a real change in posture. The earlier mode split implied a hard boundary; the current text says the boundary is now per-capability rather than per-mode. If you adopted this tool expecting assisted mode to be a safety gate, re-read the current README, because that gate is described as gone.

## Installing boss-agent-cli and running a welfare-filtered search

The README recommends uv and notes that the browser engine is only needed for user-initiated login and local export. Install the CLI first, then the Chromium build that patchright drives.

```bash
uv tool install boss-agent-cli
patchright install chromium
```

After that, the human entry point is the bare command, which opens a wizard for role, platform and goal. Agents and advanced users can skip the wizard and call commands directly. Start with the environment self-check and the login flow, then verify the session before searching.

```bash
boss doctor
boss login
boss status
```

The search command takes a keyword, a city and a welfare list. The README gives this exact example, which filters for two-day weekends and full social insurance.

```bash
boss search "Golang" --city 广州 --welfare "双休,五险一金"
boss detail <security_id>
boss shortlist add <security_id> <job_id> --tags 后端,远程
boss shortlist compare
```

The welfare flag is the differentiating feature. According to the README, it automatically paginates to fetch additional results, matches with AND logic against actual listing welfare data, and supports --sort score to order by a local match score. The detail command takes the security_id returned by search, and shortlist add writes the job into a local candidate pool with your own tags. shortlist compare is an offline comparison across that pool. Nothing in that sequence posts to the platform on your behalf.

If you want to embed it rather than shell out, the package ships py.typed and exposes a typed client.

```python
from boss_agent_cli import AuthManager, BossClient, AuthRequired
with BossClient(AuthManager(...)) as client:
    result = client.search_jobs("Golang", city="广州")
```

## MCP integration, and the browser-less container

The recommended agent path is MCP. The README gives a host configuration that runs the server through uvx and states it exposes 73 implemented tools.

```json
{ "mcpServers": { "boss-agent": { "command": "uvx", "args": ["--from", "boss-agent-cli[mcp]", "boss-mcp"] } } }
```

If you would rather not maintain a Python toolchain locally, the repository ships a compose service. The README and docker-compose.yml both state that the image deliberately contains no browser engine, so login must happen on the host first, and the data directory is then mounted into the container.

```bash
BOSS_UID=$(id -u) BOSS_GID=$(id -g) docker compose run --rm boss-mcp
```

The Dockerfile explains the reasoning: a container with a browser stuffed into it would produce an image that looks like it works but cannot log in. It also documents that HOME is /data inside the image, so the CLI default of ~/.boss-agent resolves to /data/.boss-agent whether you run boss-mcp or override the entrypoint with boss. The runtime stage creates a non-root user with UID 1000 and keeps /data traversable for other users, because the primary use is a mounted data directory and a mismatched host UID would otherwise hit a permission error.

There is a second integration style for source projects. The README shows copying examples/opencode/opencode.json and running the server with --data-dir ./.boss-agent, which keeps review, pending and log state isolated per project.

## Where the local-assist model breaks down

The first limitation is stated in the README's own platform table. BOSS Zhipin is the default and supports both the candidate and recruiter roles. Zhilian is marked as candidate-side read-only plus local-assist peer, with a recruiter-side agent described as V1 browser/CDP automation. Qiancheng is a registered placeholder that returns NOT_SUPPORTED uniformly. So the multi-platform abstraction is real in the code layout, but the working surface today is BOSS Zhipin, with Zhilian as a partial second. If your search spans several boards, this tool covers one of them well.

The second limitation is the recruiter command tree. The README says boss hr currently supports only the default recruiter platform zhipin-recruiter, and that Zhilian's recruiter side goes through the agent command and a browser/CDP adapter instead. Two different mechanisms for two platforms means two different failure modes and two sets of docs to read.

The third is the container boundary. Because the image has no browser engine, boss login cannot run inside it. That is a deliberate trade-off, but it means any workflow that needs a fresh login cannot be fully containerized.

The fourth is crawling. Bulk collection requires an extra dependency group, uv sync --extra crawl, and it runs against its own <data-dir>/crawl/chrome-profile rather than your daily Chrome profile. Hooks are not injected by default; using a local script requires both an explicit hook profile and a directory containing SHA256SUMS. Requests, detail fetches, wall-clock time and retries are all capped by fixed budgets you configure up front. If you want unbounded collection, this is the wrong tool by design.

## How it differs from driving the site with Playwright yourself

The obvious alternative is writing your own Playwright or patchright script against BOSS Zhipin. The difference is not the browser, since boss-agent-cli depends on patchright anyway. The difference is what sits above it.

A hand-rolled script gives you total control over selectors and request timing, and no abstraction to fight. What it does not give you is a capability contract. With boss-agent-cli, boss schema tells your agent what exists, and unimplemented features return NOT_SUPPORTED instead of a stack trace, so an agent can plan around gaps. A custom script has no equivalent: every capability is implicit in the code, and every failure is whatever exception your selectors raise.

The second difference is state. The shortlist, favorites, stats, watch and preset commands keep a local candidate pool with tags and notes that survives across runs, and the crawl subsystem persists SQLite checkpoints with JSON, CSV and XLSX incremental artifacts so a run can be resumed with boss crawl resume <run_id>. Building that yourself is a project, not an afternoon.

The third is the welfare filter. The README describes automatic pagination plus AND matching plus a local score sort. Replicating that means reverse-engineering how welfare data appears across listing pages, which is exactly the work the project has already done. The trade-off is that you inherit its model of what welfare data means, and you cannot easily change the matching semantics without forking.

## Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-08-27, which is recent. The releases listed alongside it are v1.19.1 and v1.19.0, both dated 2026-08-27, following v1.18.0 on 2026-07-28. That cadence suggests active work, and the pyproject.toml in the repository declares version 1.20.0, which is ahead of the newest listed release. Treat the release list as the stable surface and the pyproject version as the development line.

The licence is MIT, declared both in pyproject.toml and in the Dockerfile image label. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and permission notice are preserved. That is a statement about the licence text, not advice about your situation. If you plan to redistribute a modified build, read LICENSE yourself.

Upgrade cost is mostly driven by the dependency set rather than the command surface. The runtime depends on click, httpx with the socks extra, cryptography, patchright, browser-cookie3, rich, prompt-toolkit, pyyaml and websockets, with Python 3.10 or newer required and classifiers listing through 3.14. The pyproject comment explains that httpx[socks] pulls socksio so that an ALL_PROXY=socks5:// environment does not fail at client construction time, a failure mode the comment notes would never appear on a clean CI runner. If your team runs behind a SOCKS proxy, that dependency is load-bearing.

The Dockerfile pins installation to uv.lock with --frozen, so a container build fails rather than silently drifting when the lock cannot be satisfied. If you vendor the image, that is the behaviour to expect on dependency updates. The schema-driven design also means upgrades can change what boss schema reports; an agent that hardcodes a command list rather than reading schema will break quietly on a release that adds or renames a command.

## Conclusion

Adopt boss-agent-cli if you already have a BOSS Zhipin account and want a scriptable, schema-described surface for job discovery, welfare filtering and a local shortlist, with MCP or Python embedding as the integration path. Do not adopt it if you need a platform other than BOSS Zhipin today: the README lists Zhilian as a candidate-side read-only plus local-assist peer and Qiancheng as a registered placeholder that returns NOT_SUPPORTED. Before writing code against it, run boss schema and read the capability matrix, because the README states that schema is the source of truth and that unimplemented features return NOT_SUPPORTED rather than failing silently.

## FAQ

### What does CLI agent mean in the context of boss-agent-cli?

In this project it means a command-line tool whose output is designed to be consumed by an AI agent rather than read by a person. boss-agent-cli writes a JSON envelope with the keys ok, data, pagination, error and hints to stdout, exits 0 or 1, and exposes its capabilities through boss schema, so an agent can discover and call workflows programmatically.

### How do I install boss-agent-cli?

The README recommends uv: run uv tool install boss-agent-cli, then patchright install chromium for the browser engine used by user-initiated login and local export. After that, boss doctor checks the environment and boss login starts the authentication flow.

### What does the --welfare flag do in boss-agent-cli?

It filters search results by welfare conditions. The README states that the flag automatically paginates to fetch additional results, matches with AND logic against actual listing welfare data, and can be combined with --sort score to order results by a local match score.

### Can boss-agent-cli run inside Docker?

Yes, but only for the MCP server and read-only or local commands. The Dockerfile and README both state the image deliberately excludes a browser engine, so boss login must be completed on the host first and the ~/.boss-agent directory mounted into the container.

## Sources

- [Official documentation](https://can4hou6joeng4.github.io/boss-agent-cli/)
- [Official README](https://github.com/can4hou6joeng4/boss-agent-cli#readme)
- [Project repository](https://github.com/can4hou6joeng4/boss-agent-cli)
- [Release notes](https://github.com/can4hou6joeng4/boss-agent-cli/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/can4hou6joeng4-boss-agent-cli