# π§’ zhihu-cli
**The terminal is your new Zhihu HQ.**
*A feature-complete, automation-ready Zhihu CLI & Developer Toolkit.*
```
browse Β· download Β· search Β· publish Β· analyze β all from the command line.
```
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com/KrisTHL181/zhihu-toolkit/stargazers)
---
**zhihu-cli** turns your terminal into a full-featured Zhihu client. Authenticate once, then browse, search, download, publish, and analyze β without ever opening a browser.
> β οΈ This is an **unofficial** CLI for Zhihu. Use at your own risk. Not affiliated with Zhihu Inc.
π Looking for the DSH plugin? β **[`dsh-plugin/`](dsh-plugin/)**
---
## π Quick Start
> **Requirement:** Python 3.10 or newer. Check your version with `python --version` before installing.
```bash
# Install
pip install zhihu-toolkit
```
### 1. Authenticate
```bash
zhihu auth paste # paste a cURL from browser DevTools
zhihu auth login # scan a QR code with the Zhihu App
zhihu auth import # import the session from a local browser (needs: pip install 'zhihu-toolkit[browser]')
```
### 2. Verify
```bash
zhihu auth status # check login status and active profile
```
---
## β¨ What You Can Do
### π Read & Browse
Browse Zhihu's feeds, hot lists, questions, articles, pins, and comments β all rendered in your terminal with a Rich-powered pager. Explore the real-time trending list with excerpts, scroll through your personalized recommend feed, or dive into a question and its full answer thread without clicking a single link. Zhihu Daily (η₯δΉζ₯ζ₯) has its own group: `zhihu daily latest`, `zhihu daily before `, and `zhihu daily story --save`.
### πΎ Download for Offline
Save any Zhihu content (articles, answers, questions, pins, videos, collections) as clean Markdown with YAML frontmatter. Download individual pieces or batch-process from a manifest. Everything lands in `~/.zhihu-cli/downloads/`, organized by type, ready for your note-taking system or offline reading. Re-running a download is incremental by default: items whose file already exists and whose listing timestamp has not advanced are skipped, with state kept in `.zhihu-download.json` in the output directory. Use `--force` to re-download everything, `--since YYYY-MM-DD` to bound the listing walk for `download user`, and `-j/--concurrency` (default 4) to fetch items in parallel.
### π Search
Search questions, articles, users, and topics across Zhihu. Fine-tune result depth and quantity β all from the command line.
### βοΈ Publish & Edit
Write answers and articles in Markdown, publish them to Zhihu with one command. Need to update? Modify existing answers and articles from your local files. Markdown-to-HTML conversion happens automatically via Zhihu's own rendering pipeline.
### π¬ Interact
Vote, thank, follow, block, and comment β full social interaction without the browser. Manage collections: create, populate, and organize them. Send and receive direct messages, and stream real-time notifications and chat via MQTT.
### πΈοΈ Scrape & Export
Batch-export your creations, activity history, answers, and articles as structured JSON. Use the universal converter to merge and normalize across formats for your own data pipeline.
### π Analyze
**Creator analytics** β pull your Zhihu income data and visualize it: monthly summaries, trend charts (with EMA), advanced indicators (Bollinger Bands, MACD), derivative analysis (velocity/acceleration/jerk), weekday breakdowns, and per-content daily metrics. Charts are saved as PNGs.
**NLP tools** β run word frequency analysis, generate word clouds, and perform K-means clustering on your downloaded content. All operate across your full Markdown library.
### π Multi-Account
Save multiple profiles from different accounts, switch between them with a single command. Each profile keeps its own auth credentials and cookies.
---
## ποΈ Architecture
```
src/zhihu_cli/
βββ main.py # Click CLI β command group hub
βββ output.py # styled terminal output (Rich)
βββ content/
β βββ handlers/ # one file per Zhihu domain
β βββ utils/ # HTMLβMarkdown, ZSE v4 signing
βββ creator_tools/ # income analytics + plotting
βββ nlp_tools/ # word count, wordcloud, clustering
βββ extensions/ # plugin system (auto-discovered)
```
| Layer | What It Does |
|---|---|
| **π Auth** | Browser Cookie + User-Agent headers from cURL paste or QR code login, cached per-profile |
| **βοΈ Signing** | Every Zhihu request gets auto-signed with `x-zse-93` / `x-zse-96` headers via ZSE v4 cipher |
| **π Requests** | `curl_cffi` impersonates Chrome's TLS fingerprint to avoid detection |
| **π Extraction** | Prefers direct API calls; falls back to HTML page scraping with `js-initialData` parsing |
| **π Markdown** | HTML β LaTeX preprocessing β recursive traversal β clean Markdown. Reverse for publishing |
| **π Extensions** | Drop a plugin in `extensions/` with `register_cli(group)` β auto-discovered at startup |
---
## π§ͺ Extras
### Optional Dependencies
```bash
pip install "zhihu-toolkit[nlp]" # jieba, matplotlib, wordcloud, scikit-learn...
pip install "zhihu-toolkit[creator]" # matplotlib, numpy, pandas, seaborn...
pip install "zhihu-toolkit[classifier]" # torch, transformers, scikit-learn...
pip install "zhihu-toolkit[llm]" # openai (zhihu agora ai, zhihu chat bot, crank)
pip install "zhihu-toolkit[notify]" # desktop-notifier (zhihu chat interactive --notify)
pip install "zhihu-toolkit[browser]" # browser-cookie3 (zhihu auth import)
pip install "zhihu-toolkit[mcp]" # click2mcp (the zhihu-mcp server entry point)
```
### Shell Completions
Click ships completion for each shell β add the matching line to your rc file:
```bash
# bash
eval "$(_ZHIHU_COMPLETE=bash_source zhihu)"
# zsh
eval "$(_ZHIHU_COMPLETE=zsh_source zhihu)"
# fish
_ZHIHU_COMPLETE=fish_source zhihu | source
```
From a repository clone, `python autocomp.py` detects your shell and prints the right line.
---
## π€ Contributing
PRs welcome! The codebase is structured for extensibility:
- **New command?** Add a file to `commands/` with a `register_(group)` function, import it in `main.py`.
- **New handler?** Add a file to `content/handlers/` β follow the existing patterns.
- **New extension?** Create `extensions//` with an `__init__.py` exposing `register_cli(group)`.
Run the formatter before submitting:
```bash
pre-commit run --all-files
ruff check .
ruff format .
```
---
## π License
MIT
---
*Made with β€οΈ and way too many terminal sessions.*
[Report a bug](https://github.com/KrisTHL181/zhihu-toolkit/issues) Β· [Fork this repository](https://github.com/KrisTHL181/zhihu-toolkit/fork) Β· Star β this repo!