These options apply before any subcommand.
docs [global options] <command> [command options]Base docs.page API URL for agent commands. When unset, the CLI uses the production API.
Environment variable: DOCS_PAGE_API_BASE
Show help for the command.
Print the CLI version.
init, preview, and check do not call the docs.page API.
Initialize docs.page files in a project directory.
docs init [path] [flags]Project directory to initialize. Defaults to ..
Project name written into docs.json. Inferred from package.json, pubspec.yaml, or the folder name when omitted in interactive mode.
Create starter docs/**/*.mdx files. Default in non-interactive mode when neither --docs nor --no-docs is passed.
Write docs.json only; skip starter page files.
Replace existing files created by docs.page init.
In an interactive terminal, the CLI prompts for missing values. In non-interactive mode (CI or piped stdin), pass --name, --docs or --no-docs, and --overwrite when replacing existing files; otherwise the command exits with a Missing --<flag> error.
| Condition | Message |
|---|---|
docs.json exists in non-interactive mode without --overwrite | docs.json already exists. Re-run with --overwrite to replace it. |
docs/ conflicts in non-interactive mode | docs/ already exists. … Re-run with --overwrite … or --no-docs … |
| Init templates missing from the package | Unable to find docs.page init templates. |
| Required flag missing in non-interactive mode | Missing --<flag>. Pass it as an option when running non-interactively. |
On success, the CLI prints created file paths or No docs.page files were changed. when all targets already exist.
Start a local preview server and open the docs.page preview UI.
docs preview [flags]TCP port for the local WebSocket server. When omitted, the CLI binds an ephemeral port on localhost (OS-assigned).
Do not open the preview URL automatically.
Requires docs.json or docs.yaml and at least one .mdx file under docs/.
| Condition | Message |
|---|---|
| Missing config file | No docs.json or docs.yaml file was found in the current directory. |
Missing docs/ directory | No docs/ directory was found in the current directory. |
| No page files | No .mdx files were found in the docs/ directory. |
Invalid --port value | `--port` must be a valid TCP port. |
| Port bind failure | Node.js EADDRINUSE or related bind error |
On success, the CLI prints Local preview server started., the WebSocket URL (ws://localhost:<port>), and a Preview URL shaped like https://docs.page/preview?url=ws://localhost:<port>. The server runs until you stop it with Ctrl+C (exit code 0).
Check documentation for broken links and missing assets.
docs check [path] [flags]Project directory to check. Defaults to ..
Check internal links and frontmatter redirect, next, and previous paths. Default: error.
Check that referenced local image and asset files exist. Default: error.
Fetch external URLs and report failures. Default: error.
Validate that each page's MDX renders without errors. Default: error.
Warn when title or description is missing on pages that use auto-generated social preview images. Also checks site name and description in docs.json. Default: error.
All five severity flags accept off, warn, or error. Default for each: error.
| Code | Meaning |
|---|---|
0 | No error-level issues found. |
1 | One or more error-level issues found. |
| Condition | Message |
|---|---|
| Missing config | No docs.json or docs.yaml file was found. |
Invalid docs.json | docs.json is not valid JSON: … |
Invalid docs.yaml | docs.yaml is not valid YAML: … |
| No page files | No docs/**/*.mdx files were found. |
| Broken internal link | Internal link points to a missing docs page. (or frontmatter variant) |
| Missing asset | Referenced asset does not exist. |
| Unreachable external URL | Unable to reach external link: … or External link returned <status> … |
Create an in-docs chat agent for a GitHub repository.
docs agent create [flags]Target GitHub repository. Prompted when omitted in an interactive terminal.
LLM provider: openai, anthropic, google, or xai.
Provider API key. Encrypted locally before upload. Prompted as a password when omitted in an interactive terminal.
GitHub token instead of gh auth token.
Overwrite an existing agent configuration.
The CLI prints Your documentation agent is ready to use. and a JSON snippet with agent.key to add to docs.json.
| Condition | Message |
|---|---|
Missing --repo in non-interactive mode | Missing --repo. |
| Invalid repository format | `--repo` must be in the form `org/name`. |
| Invalid provider | `--provider` must be one of: xai, openai, anthropic, google. |
| API key too short | `--apikey` must be longer than 1 character. |
gh not installed | GitHub CLI (\gh`) is required when `--gh-auth` is not provided.` |
gh not authenticated | Unable to read a GitHub auth token from \gh`. Run `gh auth login`, or pass `--gh-auth`.` |
| API error response | Server \error` string or Agent creation failed (<status> …).` |
| Missing token in response | Agent creation failed: response did not include a token. |
Delete the agent configuration for a repository.
docs agent delete [flags]Target GitHub repository. Prompted when omitted in an interactive terminal.
GitHub token instead of gh auth token.
The CLI prints Deleted agent for org/name.
| Condition | Message |
|---|---|
Missing --repo in non-interactive mode | Missing --repo. |
| Invalid repository format | `--repo` must be in the form `org/name`. |
| GitHub auth failure | Same messages as agent create |
| API error response | Server \error` string or Agent deletion failed (<status> …).` |
- CLI: install, init, preview, check, and agent workflows
- Local preview: feature overview
- HTTP endpoints: platform API routes