Skip to content

feat(cli): add phala docs — explore live docs from the terminal (agent-friendly) - #485

Merged
Marvin-Cypher merged 2 commits into
mainfrom
feat/cli-docs-command
Jul 31, 2026
Merged

feat(cli): add phala docs — explore live docs from the terminal (agent-friendly)#485
Marvin-Cypher merged 2 commits into
mainfrom
feat/cli-docs-command

Conversation

@Marvin-Cypher

Copy link
Copy Markdown
Contributor

Summary

Adds a phala docs command group so users — and especially AI coding agents driving the CLI — can explore everything on docs.phala.com directly from the terminal, with zero setup. No MCP registration, no links to paste: if the agent has the phala CLI, it has the current docs.

Command What it does
phala docs search <query> Relevance-ranked full-text search (titles, links, excerpts)
phala docs read <page> Read full pages by path or docs.phala.com URL
phala docs tree [path] -L <depth> Browse the docs site as a directory tree
phala docs grep <pattern> [path] Ripgrep across all docs content (--files for paths only)
phala docs feedback <page> <msg> Report incorrect/outdated docs to the docs team

All subcommands support --json, require no authentication, exit non-zero with actionable hints on failure, and human output cross-links the sibling subcommands so an agent that discovers one discovers them all.

How it works

The hosted docs MCP server (https://docs.phala.com/mcp) is a stateless streamable-HTTP endpoint, so each call is a single JSON-RPC POST — implemented in a ~180-line wire-format client (cli/src/lib/docs-mcp.ts) with no MCP SDK dependency.

  • search uses the server's search_phala tool
  • read / tree / grep use query_docs_filesystem_phala, a virtual filesystem over the published docs that accepts cat / tree / rg commands
  • read normalizes URLs → paths, strips anchors, and auto-resolves pagepage.mdxpage/index.mdx
  • PHALA_DOCS_MCP_URL overrides the endpoint

Because everything is served live, docs updates are visible to the CLI immediately — bundled phala help topics stay version-pinned to the installed CLI, while phala docs is the freshness channel.

Testing

  • Unit tests for the filesystem-output parser, shell quoting, and path normalization (cli/src/lib/docs-mcp.test.ts)
  • Full CLI suite: 416 pass / 0 fail; biome format + lint clean; tsc --noEmit clean
  • Live-tested against docs.phala.com: search, tree, read (path + URL + fallback resolution), grep (--files), JSON mode, and error paths (missing page, bad tree path) all verified

Follow-ups (not in this PR)

  • Mention phala docs in the top-level --help epilogue and in error remediation hints
  • Document it in skills/phala-cli/SKILL.md so agents learn about it up front

🤖 Generated with Claude Code

Adds a `phala docs` command group that lets users — and especially AI
coding agents — explore the live documentation on docs.phala.com
directly from the terminal, with zero setup:

- `phala docs search <query>` — relevance-ranked full-text search
- `phala docs read <page>` — read full pages by path or docs URL
- `phala docs tree [path] -L <depth>` — browse the docs site structure
- `phala docs grep <pattern> [path]` — ripgrep across all docs content
- `phala docs feedback <page> <msg>` — report doc issues to the docs team

The commands talk to the hosted docs MCP server (https://docs.phala.com/mcp)
over its stateless streamable-HTTP transport via a minimal wire-format
client (src/lib/docs-mcp.ts) — no MCP SDK dependency. search uses the
search_phala tool; read/tree/grep use the query_docs_filesystem_phala
virtual filesystem tool.

All subcommands support --json, require no authentication, and return
actionable hints on failure. PHALA_DOCS_MCP_URL overrides the endpoint.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@Marvin-Cypher
Marvin-Cypher requested a review from Leechael July 30, 2026 21:14
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@Marvin-Cypher
Marvin-Cypher merged commit d8da13c into main Jul 31, 2026
8 checks passed
@Marvin-Cypher
Marvin-Cypher deleted the feat/cli-docs-command branch July 31, 2026 17:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants