Zhiwho

Zhiwho is a local-first command-line client for Zhihu. It provides a terminal UI for browsing the follow feed, reading questions and articles, managing personal content, and publishing Markdown back to Zhihu from an authenticated browser session.

The project is designed for users who prefer keyboard-driven workflows and want their Zhihu session, cookies, and cache to stay on their own machine.

Features

• Keyboard-driven TUI for the Zhihu follow feed.
• Top refresh: newly discovered feed items are inserted at the top instead of replacing older content.
• Local cache for faster startup and offline-friendly feed/profile previews.
• Personal data view with categories for dynamics, answers, articles, questions, pins, and videos.
• Richer terminal rendering for headings, quotes, lists, links, and code-like content.
• Question, answer, article, pin, and video detection from Zhihu URLs.
• Read Zhihu questions/articles from the CLI.
• Publish Markdown articles and answers through a logged-in browser session.
• Manage Zhihu collections from the command line.
• Optional AI-agent command entrypoint for higher-level workflows.

Status

Zhiwho is early-stage software. It automates parts of Zhihu's web experience through Playwright, so UI selectors and behavior may need updates when Zhihu changes its site.

The project stores authentication cookies and cache files under ~/.zhiwho by default.

Requirements

• Node.js 20 or newer.
• npm.
• A Zhihu account for authenticated features.
• Playwright Chromium.

Installation

Clone the repository and install dependencies:

git clone git@github.com:ChenMiaoi/zhiwho.git
cd zhiwho
npm ci
npx playwright install chromium

Build the project:

npm run build

Run from source during development:

npm run dev

Run the built CLI:

npm start -- --help

Login

Interactive login opens a browser so you can sign in to Zhihu:

npm run dev -- login

Import cookies from a JSON file:

npm run dev -- login --import cookies.json

Run login in headless mode:

npm run dev -- login --headless

Usage

Open the TUI:

npm run dev

Or explicitly open the feed:

npm run dev -- feed

Common TUI shortcuts:

Key	Action
↑ / ↓	Move selection
PgUp / PgDn	Move by page
Enter	Open selected item
Space	Load more feed items
r	Refresh from the top
m	Open personal data
Esc	Go back
q	Quit

Read a question or article:

npm run dev -- read "https://www.zhihu.com/question/123456"
npm run dev -- read "https://zhuanlan.zhihu.com/p/123456"

Publish a Markdown article:

npm run dev -- publish article.md
npm run dev -- publish article.md --collection "My Collection"

Answer a question from Markdown:

npm run dev -- answer "https://www.zhihu.com/question/123456" -f answer.md

Manage collections:

npm run dev -- collection list
npm run dev -- collection create "New Collection"

Configuration:

npm run dev -- config show
npm run dev -- config get headless
npm run dev -- config set headless true

AI-agent entrypoint:

npm run dev -- agent "搜索 Rust 相关的高赞回答"
npm run dev -- agent --interactive

Local Data

Zhiwho writes local runtime files to ~/.zhiwho:

File	Purpose
cookies.json	Browser cookies used for authenticated Zhihu requests
cache-db.json	TUI feed/profile cache
config.json	CLI configuration

Do not commit these files. They may contain private account data.

Development

Install dependencies:

npm ci

Run type checking:

npm run typecheck

Build:

npm run build

Run the default test target:

npm test

Run the TUI locally:

npm run dev

Project layout:

src/
  cli/       Commander command definitions
  core/      Browser, auth, cache, formatting, and Zhihu operations
  tui/       Terminal feed and profile UI

Continuous Integration

GitHub Actions runs on pushes and pull requests. The workflow installs dependencies with npm ci, type-checks the project, builds TypeScript, and verifies the built CLI can print help.

Release

Releases are tag-driven. Pushing a semver tag such as v0.1.0 starts the release workflow.

The release workflow:

1. Verifies that the tag matches package.json version.
2. Installs dependencies with npm ci.
3. Runs type checking and build.
4. Runs a built CLI smoke test.
5. Publishes the package to npm with provenance through npm Trusted Publishing/OIDC.
6. Creates a GitHub Release with generated notes.

Create a release:

npm version patch
git push origin main
git push origin v0.1.1

For prereleases, use a prerelease version such as v0.2.0-beta.1; npm will publish it with the next dist-tag.

The first npm version must be published manually before npm Trusted Publishing can be enabled for this package. After enabling Trusted Publishing on npm, the GitHub release workflow does not require an NPM_TOKEN secret.

Security And Privacy

• Zhiwho is not affiliated with Zhihu.
• Treat cookies as secrets.
• Prefer a dedicated browser session or imported cookie file when testing.
• Review generated content before publishing or answering.
• Respect Zhihu's terms and rate limits.

Contributing

Issues and pull requests are welcome. For substantial changes, open an issue first so the behavior and scope can be discussed.

Before opening a pull request, run:

npm test
npm run build

License

Zhiwho is released under the MIT License.