repowiki-cli

Query DeepWiki, Google Code Wiki, and zread.ai documentation for any public GitHub repository from your terminal.

中文文档见 README.zh-CN.md · Chinese docs: README.zh-CN.md

What it is

repowiki-cli is a Python/Typer CLI that reads AI-generated repository documentation and answers questions about code, from the terminal. It speaks to three wiki services behind a single uniform command surface, one namespace per service:

Service	Namespace	Transport	Auth
DeepWiki	deepwiki	MCP (Streamable HTTP) + reverse REST/WebSocket	none
Google Code Wiki	codewiki	Google batchexecute RPC	none
Zread	zread	JSON REST + SSE	ask / submit need a token

DeepWiki is served by two interchangeable backends:

Backend	Transport	Commands	Richness
MCP (official)	Streamable HTTP	structure, contents, ask, cp	body only
Reverse (api.devin.ai)	REST + WebSocket	ask (with flags) + list / status / warm / get / stat	body, summary, references, sources, stats

The MCP backend is the official, documented DeepWiki server and is free for public repos with no auth. The reverse backend is the underlying engine api.devin.ai (same as the DeepWiki web app) — it is not a documented public API, but it exposes engine selection (fast/deep/codemap), streaming, conversation threading, and index-management endpoints that MCP does not.

Install

uvx repowiki-cli --help

From source:

git clone <this-repo> && cd <this-repo>
uv sync
uv run repowiki-cli --help

Quick start

repowiki-cli deepwiki structure facebook/react          # table of contents
repowiki-cli deepwiki contents vercel/next.js           # full documentation
repowiki-cli deepwiki ask facebook/react "What is Fiber?"
repowiki-cli codewiki ask facebook/react "What is Fiber?"
repowiki-cli zread contents vercel/next.js              # overview page

Command overview

Command	Purpose	Service
structure REPO	Print the documentation table of contents	DeepWiki (MCP)
contents REPO	Print the full documentation	DeepWiki (MCP)
ask REPO [QUESTION]	Answer a question (single-shot or interactive)	DeepWiki (MCP / reverse)
list SEARCH	Search indexed public repos	DeepWiki (reverse)
status REPO	Report a repo's indexing status	DeepWiki (reverse)
warm REPO	Pre-warm a repo's docs cache	DeepWiki (reverse)
get QUERY_ID	Replay a past answer by query id	DeepWiki (reverse)
stat REPO	Report a repo's index metadata	DeepWiki (reverse)
cp REPO [OUTPUT_DIR]	Export the whole wiki as Markdown + llms.txt/README.md	DeepWiki (MCP)
structure REPO	Print the documentation table of contents	CodeWiki
contents REPO	Print the full documentation	CodeWiki
ask REPO [QUESTION]	Answer a question (single-shot or interactive)	CodeWiki
stat REPO	Show the commit the wiki was generated from	CodeWiki
cp REPO [OUTPUT_DIR]	Export the whole wiki as Markdown + llms.txt/README.md	CodeWiki
structure REPO	Print the documentation table of contents	Zread
contents REPO [SLUG]	Print a page of documentation (default: overview)	Zread
ask REPO [QUESTION]	Answer a question (single-shot or interactive, needs token)	Zread
find QUERY	Search repositories	Zread
stat REPO	Report a repo's info and index status	Zread
top [WEEKS]	Show the trending list	Zread
rand [TOPIC]	Get a random repository recommendation	Zread
cp REPO [OUTPUT_DIR]	Export the whole wiki as Markdown + llms.txt/README.md	Zread
submit REPO	Submit a repo for indexing (needs token)	Zread

Each service is documented in its own section below: DeepWiki, CodeWiki, Zread.

Repo formats

REPO accepts any of:

• owner/repo
• github.com/owner/repo
• www.github.com/owner/repo
• https://github.com/owner/repo (optionally with /tree/main or .git)

Everything is normalized to owner/repo.

JSON output

Main commands emit an envelope with repo and command:

{
  "repo": "facebook/react",
  "command": "ask",
  "question": "What is Fiber?",
  "answer": "..."
}

DeepWiki ask additionally includes summary, references, sources, stats, and query_id when the reverse backend provides them. Management commands (list / status / warm / get / stat) omit repo and use command + fields only. Errors go to stderr as {"error": ..., "kind": ...}.

Saving (--save)

--save writes answers to a Markdown file:

• --save PATH writes to (and appends to) the given path, creating parent directories. CodeWiki and Zread ask take a required path.
• DeepWiki ask also accepts a bare --save, which auto-names the file repowiki-<owner>-<repo>_<timestamp>.md in the current directory.
• In interactive mode all answers in the session append to one file; single-shot answers append when the file already exists.
• Combine with --json to keep stdout as JSON while writing Markdown to the file.

Environment variables

Variable	Purpose	Default
DEEPWIKI_MCP_URL	DeepWiki MCP endpoint	https://mcp.deepwiki.com/mcp
DEEPWIKI_API_URL	DeepWiki reverse backend endpoint	https://api.devin.ai
DEEPWIKI_REPL_RETRIES	DeepWiki reverse REPL retry attempts	4
DEEPWIKI_TIMEOUT	DeepWiki reverse answer timeout in seconds	120 (300 for --mode deep)
CODEWIKI_CACHE_DIR	CodeWiki bootstrap cache directory	$XDG_CACHE_HOME or ~/.cache
ZREAD_TOKEN	Zread auth token for ask / submit	—
ZREAD_LANG	Zread default language	en
ZREAD_MODEL	Zread ask model	glm-5.1
REPOWIKI_MOCK_TEXT	mock MCP result (tests)	—
REPOWIKI_DEVIN_MOCK	mock reverse answer (tests)	—
REPOWIKI_CODEWIKI_MOCK	mock CodeWiki result (tests)	—
REPOWIKI_ZREAD_MOCK	mock Zread result (tests)	—

DeepWiki

DeepWiki is the primary service, exposed under the deepwiki namespace. It reads public repositories with no auth.

deepwiki structure

repowiki-cli deepwiki structure REPO [--json]

Prints the documentation table of contents (MCP read_wiki_structure).

deepwiki contents

repowiki-cli deepwiki contents REPO [--page TITLE] [--rich] [--json]

Prints the full documentation (MCP read_wiki_contents), which can be large.

• --page TITLE — print only the page whose title matches (case-insensitive exact match). The # Page: delimiter is dropped, so the selected page shows a single heading. If no page matches, the available titles are listed (to stderr) and the command exits with error kind page_not_found.
• --rich — render Markdown with color/formatting via rich.
• --json — emit a JSON envelope instead of Markdown.

deepwiki ask

repowiki-cli deepwiki ask REPO [QUESTION] \
  [--rich] [--json] [--save [PATH]] \
  [--mode fast|deep|codemap] [--id QUERY_ID] \
  [--sources] [--no-summary] [--context TEXT] [--repo REPO]... \
  [--mermaid] [--stream] [--timeout SECONDS]

With a QUESTION, it answers once and exits. Without one, it enters an interactive REPL (type /exit to quit).

Backend routing. ask uses the MCP backend unless at least one reverse flag is present. Any of --mode, --id, --sources, --repo, --context, --no-summary, or --stream switches it to the reverse backend. --mermaid alone does not switch backends — pair it with --mode codemap.

• --mode fast|deep|codemap — engine selection. Mapping to the underlying engine id: fast → multihop_faster, deep → agent, codemap → codemap.
• --id QUERY_ID — reuse a previous query id to continue the same conversation thread.
• --sources — append line-numbered source-code slices for each citation.
• --context TEXT — pass additional context alongside the question.
• --no-summary — skip summary generation.
• --repo REPO — repeatable; ask one question against multiple repos at once (the positional repo plus every --repo).
• --mermaid — render a codemap answer as a Mermaid flowchart TB. If the answer is not a codemap, it warns and falls back to plain text. Paste the output into mermaid.live, GitHub, or VS Code to view it.
• --stream — stream answer text chunk-by-chunk over a WebSocket instead of waiting for the full answer, then append the summary and sources. Output is plain text, so --rich has no effect. A mid-answer drop falls back to polling. No effect with --json.
• --timeout SECONDS — answer timeout for the reverse backend. Defaults to 120, or 300 for --mode deep. Overrides DEEPWIKI_TIMEOUT.
• --save [PATH] — save each answer to a Markdown file (see Saving).
• --rich — render the answer's Markdown with rich. No effect with --stream.
• --json — emit a JSON envelope. Ignored in interactive mode.

deepwiki list

repowiki-cli deepwiki list SEARCH [--json]

Searches DeepWiki's public index (reverse list_public_indexes).

deepwiki status

repowiki-cli deepwiki status REPO [--json]

Reports a repo's indexing state (reverse public_repo_indexing_status). unknown is a normal result for an unindexed repo and exits 0.

deepwiki warm

repowiki-cli deepwiki warm REPO [--json]

Pre-warms a repo's docs cache (reverse warm_public_repo).

deepwiki get

repowiki-cli deepwiki get QUERY_ID [--rich] [--sources] [--json] [--mermaid]

Replays a past answer by query id (reverse get_query).

deepwiki stat

repowiki-cli deepwiki stat REPO [--human] [--stale] [--json]

Shows a repo's index metadata from the reverse list_public_indexes — the short commit sha (last segment of the index id) and last_modified (the "Last indexed" timestamp shown on deepwiki.com).

• --human — render last_modified as a local, space-separated time.
• --stale — compare the indexed short sha against GitHub HEAD (via api.github.com/.../commits/HEAD) and print 最新/过期. Note: a refresh (re-index) has no public endpoint — index_public_repo is reCAPTCHA-gated — so stat can only detect staleness, not fix it.
• --json — emit a JSON envelope (with stale when --stale is set).

deepwiki cp

repowiki-cli deepwiki cp REPO [OUTPUT_DIR]

Exports the full wiki (MCP read_wiki_contents) as one Markdown file per # Page: section, plus llms.txt / README.md (index) and llms-full.txt (concatenated). OUTPUT_DIR defaults to owner_repo.

Implementation: the raw Markdown is split on # Page: delimiters by shared/output.py::split_pages (a payload with no delimiters becomes a single Overview page). Files are written by the shared shared/export.py::export_pages helper, which names each page NN-slug.md and also emits llms.txt (index of - [title](NN-slug.md) links), a README.md with the same index for GitHub auto-rendering, and llms-full.txt (the whole concatenated text).

DeepWiki design

The whole CLI shares one result type, Answer, so both backends feed the same formatting layer:

@dataclass
class Answer:
    body: str                          # main answer text
    summary: str | None = None         # reverse backend only
    references: list[Reference] = []   # {file_path, range_start, range_end}
    sources: list[SourceFile] = []     # {repo, path, content}
    stats: dict[str, float] = {}       # reverse backend only
    query_id: str | None = None        # reverse backend only

The MCP backend produces a bare Answer(body=...). The reverse backend fills in summary, references, sources, stats, and query_id — all carried by --json.

DeepWiki backends in detail

MCP backend (services/deepwiki/client.py)

• Endpoint: DEEPWIKI_MCP_URL, default https://mcp.deepwiki.com/mcp.
• Speaks Streamable HTTP (the SSE endpoint is deprecated).
• Tools: read_wiki_structure, read_wiki_contents, ask_question.
• Tool arguments use camelCase: repoName (and question for ask_question).
• Connection lifecycle:
  • One-shot commands open/close a session per call.
  • The interactive REPL opens one session and reuses it across questions.
  • The initial connect is retried once on failure; a mid-session drop is recovered by reopening once.

Reverse backend (services/deepwiki/devin.py)

• Endpoint: DEEPWIKI_API_URL, default https://api.devin.ai.
• Answer flow (ask):
  1. POST /ada/query with the payload below, then either stream or poll.
  2. Streaming — open wss://…/ada/ws/query/{query_id} and assemble the answer from events.
  3. Polling — GET /ada/query/{query_id} on an interval until state is done or error.

Request payload (POST /ada/query):

{
  "engine_id": "agent",
  "user_query": "...",
  "keywords": [],
  "repo_names": ["owner/repo"],
  "additional_context": "",
  "query_id": "<uuid>",
  "use_notes": false,
  "attached_context": [],
  "generate_summary": true
}

Engine mapping: fast → multihop_faster, deep → agent, codemap → codemap.

WebSocket event types observed on the stream: snapshot, file_contents, stats, chunk, reference, summary_chunk, summary_done, done. The stream carries the complete answer, so no follow-up GET is needed after streaming — parse_response assembles the Answer directly from the events.

Management endpoints:

Method	Path	Used by
GET	/ada/list_public_indexes?search_repo=	list
GET	/ada/public_repo_indexing_status?repo_name=	status
POST	/ada/warm_public_repo?repo_name=	warm
GET	/ada/query/{query_id}	get

DeepWiki error handling and exit codes

Exceptions are classified into a small taxonomy and mapped to an exit code:

Error kind	Meaning	Exit code
success	—	0
not_indexed	repo is not indexed on DeepWiki	2
connection	could not connect to the server	3
tool / error / invalid_repo / invalid_input / page_not_found / unexpected	anything else	1

ConnectionError (transport-level failure) and ToolError (a {"detail": …} or tool error surfaced from the server) are the two core exception types. HTTP error bodies are surfaced via FastAPI's detail field so the CLI can classify "not indexed" vs. a generic tool error.

With --json, errors go to stderr as a single line:

{"error": "Could not connect to DeepWiki server...", "kind": "connection"}

DeepWiki streaming, retry, and citations

This applies to the reverse backend only.

Single-shot --stream streams chunks over the WebSocket to stdout, then prints the summary/sources tail. Inline [i] citation markers are emitted the moment each reference event arrives, so the streamed body shows citations that line up with the ## Sources list printed at the end.

Interactive reverse REPL polls for each answer and renders the complete result, so inline [i] citations, the summary, and sources all line up. Each follow-up question reuses the previous query_id, keeping one conversation thread (/new starts a fresh thread).

Retry. Both single-shot ask and the interactive REPL retry transient failures — ConnectionError or a ToolError containing HTTP 5 — with jittered exponential backoff: delay = 1.0s × 2^attempt + random(0 … 0.5s). The default is 4 attempts, overridable with DEEPWIKI_REPL_RETRIES. Retries happen only while nothing has streamed yet. If a single-shot --stream drops mid-answer, the CLI falls back to polling the same query_id and re-prints the complete answer (body, citations, summary, sources); the part already streamed appears twice, but the answer is never lost.

Why retry matters: the reverse endpoint is unofficial and occasionally refuses the WebSocket handshake (a millisecond-fast connection reset, not a slow timeout). Retry with backoff absorbs one-off blips.

Citation line numbers. The range_start/range_end attached to each citation are model-estimated, so treat them as approximate rather than exact:

1. Precision — the range points at the region the model associated with a claim, not necessarily the exact lines that back it; it can be off.
2. Version drift — the numbers reflect whatever snapshot DeepWiki indexed, which may not match your local checkout.

The CLI passes these numbers through unchanged; it does not offset or re-interpret them.

DeepWiki Mermaid

--mode codemap returns a codemap (a {"traces": [...]} JSON blob). --mermaid renders it as a flowchart TB with per-trace subgraphs and color styling. Paste the output into mermaid.live, GitHub, or VS Code to view it. If the answer is not a codemap, --mermaid warns and prints the plain text.

DeepWiki usage recipes

The combinations below are grouped by intent. All assume facebook/react as the repo unless noted.

Read documentation (MCP)

repowiki-cli deepwiki structure facebook/react
repowiki-cli deepwiki contents vercel/next.js
repowiki-cli deepwiki contents vercel/next.js --page "Getting Started"   # one page only
repowiki-cli deepwiki contents vercel/next.js --rich                      # rendered

Ask questions (MCP)

repowiki-cli deepwiki ask facebook/react "What is Fiber?"
repowiki-cli deepwiki ask facebook/react "What is Fiber?" --rich
repowiki-cli deepwiki ask facebook/react                                  # interactive

Machine-readable output

repowiki-cli deepwiki structure facebook/react --json
repowiki-cli deepwiki contents vercel/next.js --json
repowiki-cli deepwiki ask facebook/react "What is Fiber?" --json
repowiki-cli deepwiki ask facebook/react "What is Fiber?" --json --save out.md   # JSON + Markdown file

Save answers to files

repowiki-cli deepwiki ask facebook/react "What is Fiber?" --save            # auto-named
repowiki-cli deepwiki ask facebook/react "What is Fiber?" --save notes/answers.md

Reverse backend — engine and depth

repowiki-cli deepwiki ask facebook/react "What is Fiber?" --mode deep
repowiki-cli deepwiki ask facebook/react "Quick facts?" --mode fast
repowiki-cli deepwiki ask facebook/react "Show the data flow" --mode codemap --mermaid

Reverse backend — sources and summary

repowiki-cli deepwiki ask facebook/react "What is Fiber?" --mode deep --sources
repowiki-cli deepwiki ask facebook/react "What is Fiber?" --mode deep --no-summary

Reverse backend — streaming and context

repowiki-cli deepwiki ask facebook/react "What is Fiber?" --mode deep --stream
repowiki-cli deepwiki ask facebook/react "What is Fiber?" --mode deep --context "answer in Chinese"

Reverse backend — timeout

repowiki-cli deepwiki ask facebook/react "Deep dive?" --mode deep --timeout 600   # allow 10 min for deep answers
repowiki-cli deepwiki ask facebook/react "Quick facts?" --mode fast --timeout 30
DEEPWIKI_TIMEOUT=600 repowiki-cli deepwiki ask facebook/react "Deep dive?" --mode deep   # or via env var

Reverse backend — threads and multi-repo

repowiki-cli deepwiki ask facebook/react "Follow-up?" --id <query-id>      # continue a thread
repowiki-cli deepwiki ask facebook/react "diff?" --repo remix-run/react-router --repo TanStack/router
repowiki-cli deepwiki ask facebook/react --mode deep                        # interactive, auto-threads

Management

repowiki-cli deepwiki list react
repowiki-cli deepwiki status facebook/react
repowiki-cli deepwiki warm facebook/react
repowiki-cli deepwiki get <query-id>
repowiki-cli deepwiki get <query-id> --sources
repowiki-cli deepwiki get <query-id> --mermaid
repowiki-cli deepwiki stat Junjie-Zhu/IDPFold2 --human --stale
repowiki-cli deepwiki stat facebook/react --stale

Scripting with exit codes

repowiki-cli deepwiki ask some/repo "q?" --json > out.json
case $? in
  0) ;;                       # success
  2) echo "not indexed" ;;
  3) echo "connection error" ;;
  *) echo "other error" ;;
esac

DeepWiki MCP server

The official DeepWiki MCP server is free and requires no auth for public repos. It exposes two wire protocols: Streamable HTTP (/mcp, recommended) and SSE (/sse, deprecated). repowiki-cli speaks Streamable HTTP.

To add it to Claude Code:

claude mcp add -s user -t http deepwiki https://mcp.deepwiki.com/mcp

Private repositories are out of scope for repowiki-cli; use the Devin MCP server with a Devin API key. The full documentation index lives at https://docs.devin.ai/llms.txt.

DeepWiki related tools

These are reference/alternative CLIs for the same space — worth consulting before re-implementing anything:

• Zread CLI — generates wiki docs locally from your repo via an LLM (config ~/.zread/config.yaml).
• readmeX CLI — official CLI.
• deepwiki-open — open-source DeepWiki CLI.

If the goal is generating a wiki from your own API rather than querying the public DeepWiki index, the official CLIs above already solve it — don't reinvent the wheel.

CodeWiki

Google Code Wiki is a second wiki service, exposed under the codewiki namespace. CodeWiki reads public repositories only and requires no auth — it does not support private repos.

repowiki-cli codewiki structure REPO [--json]
repowiki-cli codewiki contents REPO [--page TITLE] [--rich] [--json]
repowiki-cli codewiki ask REPO [QUESTION] [--rich] [--json] [--save PATH]
repowiki-cli codewiki stat REPO [--stale] [--json]
repowiki-cli codewiki cp REPO [OUTPUT_DIR]

Quick start:

repowiki-cli codewiki structure facebook/react          # table of contents
repowiki-cli codewiki contents vercel/next.js           # full documentation
repowiki-cli codewiki ask facebook/react "What is Fiber?"

codewiki structure

Prints the CodeWiki table of contents for a repository.

• --json — emit a JSON envelope instead of text.

codewiki contents

Prints the full CodeWiki documentation for a repository, which can be large.

• --page TITLE — print only the page whose title matches (case-insensitive exact match). If no page matches, the available titles are listed (to stderr) and the command exits with error kind page_not_found.
• --rich — render Markdown with color/formatting via rich.
• --json — emit a JSON envelope instead of Markdown.

codewiki ask

repowiki-cli codewiki ask REPO [QUESTION] [--rich] [--json] [--save PATH]

With QUESTION, ask answers once and exits. Without it, ask starts an interactive REPL — type one question per line and /exit (or /quit//q) to quit. CodeWiki's ask is stateless, so each question is independent (no thread continuation).

• --rich — render the answer's Markdown with rich.
• --json — emit a JSON envelope. Ignored in interactive mode.
• --save PATH — save the answer to a Markdown file (see Saving). A path is required (CodeWiki's ask does not auto-name on a bare --save).

codewiki stat

repowiki-cli codewiki stat REPO [--stale] [--json]

Shows the commit sha the CodeWiki documentation was generated from (parsed from the wiki payload header by codewiki/wiki.py::parse).

• --stale — compare the wiki commit against GitHub HEAD (via api.github.com/.../commits/HEAD) and print 最新/过期. CodeWiki has no timestamp, so there is no --human; the wiki sha is a prefix of the full GitHub sha when the wiki is current.
• --json — emit a JSON envelope (with stale when --stale is set).

Implementation: staleness is checked by CodeWikiClient.github_head(), which calls GET https://api.github.com/repos/{owner}/{name}/commits/HEAD (with follow_redirects=True to survive renamed-repo 301s) and returns the full 40-char sha plus commit.committer.date. A wiki is current when the GitHub sha startswith the wiki's (possibly short) sha.

codewiki cp

repowiki-cli codewiki cp REPO [OUTPUT_DIR]

Exports the full wiki as one Markdown file per section, plus llms.txt / README.md (index) and llms-full.txt (concatenated). OUTPUT_DIR defaults to owner_repo.

Implementation: each Section is rendered via codewiki/wiki.py::render_section (heading + body + dot diagrams) and the full text via render_markdown; both feed the shared shared/export.py::export_pages helper (see deepwiki cp).

Zread

zread.ai is a third wiki service, exposed under the zread namespace. Zread serves pre-generated docs for public repositories, and all read commands need no auth. The commands ask and submit require a token (see below).

Implementation note: structure/contents fetch the wiki outline and page Markdown from zread's JSON REST API (GET /api/v1/wiki/{id} and /api/v1/wiki/{id}/page/{slug}), not by scraping the Next.js RSC flight payload. REST is more stable and faster than parsing self.__next_f.push. If those endpoints ever change, the previous RSC-scraping implementation is preserved in git history (git log) rather than kept as a fragile in-code fallback.

repowiki-cli zread structure REPO [--lang zh|en] [--json]
repowiki-cli zread contents REPO [SLUG] [--file PATH] [--start N] [--end M] [--lang zh|en] [--rich] [--json]
repowiki-cli zread ask REPO [QUESTION] [--model MODEL] [--lang zh|en] [--rich] [--json] [--save PATH]
repowiki-cli zread find QUERY [--limit N] [--lang zh|en] [--json]
repowiki-cli zread stat REPO [--lang zh|en] [--human] [--stale] [--json]
repowiki-cli zread search REPO QUERY [--lang zh|en] [--json]
repowiki-cli zread top [WEEKS] [--lang zh|en] [--json]
repowiki-cli zread rand [TOPIC] [--lang zh|en] [--json]
repowiki-cli zread cp REPO [OUTPUT_DIR] [--concurrency N] [--lang zh|en]
repowiki-cli zread submit REPO [--json]
repowiki-cli zread refresh REPO [--json]

Quick start:

repowiki-cli zread structure facebook/react          # table of contents
repowiki-cli zread contents vercel/next.js           # overview page
repowiki-cli zread find react                        # search repositories

The --lang zh|en flag selects the documentation language (default en, or the ZREAD_LANG environment variable).

zread structure

Prints the zread.ai table of contents for a repository.

• --lang zh|en — language.
• --json — emit a JSON envelope instead of text.

zread contents

Prints a single page of Markdown documentation. With no SLUG, it prints the overview (first) page.

The REPO argument also accepts a GitHub blob URL with an optional line fragment, which reads that source file instead of a wiki page:

repowiki-cli zread contents https://github.com/o/r/blob/main/src/a.py#L10-L20

• --file PATH — read a source file from the repository instead of a wiki page (mutually exclusive with SLUG).
• --start N / --end M — with --file, restrict to a line range.
• --lang zh|en — language.
• --rich — render Markdown with rich.
• --json — emit a JSON envelope instead of Markdown.

zread ask

repowiki-cli zread ask REPO [QUESTION] [--model MODEL] [--rich] [--json] [--save PATH]

With QUESTION, ask answers once and exits. Without it, ask starts an interactive REPL — type one question per line and /exit (or /quit//q) to quit.

Unlike the other commands, ask requires an auth token (a JWT). Log in to zread.ai, open the browser DevTools console, and run JSON.parse(localStorage.getItem("CGX_AUTH_STORAGE")).state.token — this returns the token. Set it as the ZREAD_TOKEN environment variable.

• --model MODEL — model (default glm-5.1, or the ZREAD_MODEL environment variable). This maps to the web UI's CGX_CHAT_MODEL (e.g. glm-5.1, claude-sonnet-4.6).
• --lang zh|en — language.
• --rich — render the answer's Markdown with rich.
• --json — emit a JSON envelope. Ignored in interactive mode.
• --save PATH — save the answer to a Markdown file (see Saving).

zread find

Searches zread.ai for repositories.

• --limit N — cap the number of results.
• --lang zh|en — language.
• --json — emit a JSON envelope.

zread stat

Prints repository info and index status on zread.ai.

• --lang zh|en — language.
• --human — render the timestamps (created_at, updated_at, last_commit.when) as human-readable local times.
• --stale — fetch GitHub HEAD and compare its commit sha against last_commit.hash, printing an up-to-date / stale verdict.
• --json — emit a JSON envelope.

❯ repowiki-cli zread stat google-deepmind/alphafold3 --human
## Zread: google-deepmind/alphafold3 (stat)

- repo_id: 5fa748a6-6785-11f0-817c-3a18d81350c2
- owner: google-deepmind
- name: alphafold3
- url: https://github.com/google-deepmind/alphafold3
- description: AlphaFold 3 inference pipeline.
- description_zh: AlphaFold 3 推理管线实现
- star_count: 8570
- language: python
- topics: []
- wiki_id: 89e1aa24-7878-494b-95a1-7de0c860b94e
- status: success
- visibility: public
- created_at: 1753248298 (2025-07-23 13:24:58 CST)
- updated_at: 1789875263 (2026-09-20 11:34:23 CST)
- last_commit: {'hash': 'c0f97eda2f1f482fd94d3a38bece18c7069b4a5c', 'when': 1787154197 (2026-08-19 23:43:17 CST)}

❯ repowiki-cli zread stat google-deepmind/alphafold3 --stale
## Zread: google-deepmind/alphafold3 (stat)

- repo_id: 5fa748a6-6785-11f0-817c-3a18d81350c2
- owner: google-deepmind
- name: alphafold3
- url: https://github.com/google-deepmind/alphafold3
- description: AlphaFold 3 inference pipeline.
- description_zh: AlphaFold 3 推理管线实现
- star_count: 8570
- language: python
- topics: []
- wiki_id: 89e1aa24-7878-494b-95a1-7de0c860b94e
- status: success
- visibility: public
- created_at: 1753248298
- updated_at: 1789875263
- last_commit: {'hash': 'c0f97eda2f1f482fd94d3a38bece18c7069b4a5c', 'when': 1787154197}

最新 (up-to-date): c0f97eda2f1f482fd94d3a38bece18c7069b4a5c

zread search

Searches within a repository's wiki documentation for matching text, returning the page title and highlighted matches.

repowiki-cli zread search REPO QUERY [--lang zh|en] [--json]

• --lang zh|en — language.
• --json — emit a JSON envelope.

zread top

Prints the zread.ai trending list. WEEKS limits the number of week-groups shown.

• --lang zh|en — language.
• --json — emit a JSON envelope.

zread rand

Prints a random repository recommendation, optionally filtered by TOPIC.

• --lang zh|en — language.
• --json — emit a JSON envelope.

zread cp

Exports the whole wiki as Markdown (NN-slug.md files) plus llms.txt, README.md, and llms-full.txt into OUTPUT_DIR (defaults to the repository name).

• --concurrency N — parallel page fetches (default 5).
• --lang zh|en — language.

zread submit

Submits a repository for indexing on zread.ai. Requires a token (a JWT): log in to zread.ai, run JSON.parse(localStorage.getItem("CGX_AUTH_STORAGE")).state.token in the DevTools console, and set the result as ZREAD_TOKEN. Without it, submit prints a warning and skips. On success it also reports the indexing queue wait (backlog repos ahead, estimate_minutes ETA).

• --json — emit a JSON envelope (includes an eta field).

zread refresh

Requests a re-index (refresh) of a repository's wiki. No auth required.

repowiki-cli zread refresh REPO [--json]

• --json — emit a JSON envelope.

Development

uv sync
uv run pytest