CLI

These options apply before any subcommand.

docs [global options] <command> [command options]

init, preview, and check do not call the docs.page API.

Initialize docs.page files in a project directory.

docs init [path] [flags]

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.

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]

Requires docs.json or docs.yaml and at least one .mdx file under docs/.

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]

All five severity flags accept off, warn, or error. Default for each: error.

Declare hosts once in docs.json so CI does not repeat the flag:

{
  "check": {
    "ignoreExternalHosts": ["npmjs.org", "stackoverflow.com"]
  }
}

Values from docs.json and --ignore-external-hosts are unioned. --external-links off still skips external checking entirely.

Declare per-host severity once in docs.json so CI does not repeat the flag:

{
  "check": {
    "severityOverrideHosts": {
      "rnfirebase.io": "error",
      "stackoverflow.com": "warn"
    }
  }
}

The flag and the map are unioned; the flag wins when the same host is in both.

Severity for an external-link failure is resolved in this order:

1. --external-links off skips the request. The map does not turn the check back on.
2. If the host matches severityOverrideHosts, that severity is used for every failure: bot-gate (401, 403, 405, 429), 404, 5xx, DNS, and timeout.
3. Otherwise an unverified bot-gate stays a warning.
4. Otherwise the failure uses --external-links.

Hosts that answer 401, 403, 405, or 429 are refusing an automated request rather than reporting a missing page. For hosts not listed in severityOverrideHosts, those responses are reported as warnings so they never fail CI, and the message says the link was not verified. A host override of error makes the same responses fail CI. Missing pages (404), server errors, DNS failures, and timeouts use the override when the host matches, and otherwise remain at the configured --external-links severity.

Each external request is tried at most three times (the first attempt plus two retries) when the response is HTTP 429 or the connection drops (ECONNRESET, ECONNREFUSED, EPIPE, ETIMEDOUT, UND_ERR_SOCKET, UND_ERR_CONNECT_TIMEOUT). Responses such as 401, 403, 404, 405, and 5xx, DNS failures like ENOTFOUND, and this check's own 10s timeout (External link timed out after 10000ms.) are not retried.

On 429, the wait follows Retry-After when it is a delta-seconds value or an HTTP-date. If that header is missing or unparseable, the waits are 200ms then 400ms. Dropped-connection retries use the same 200ms then 400ms backoff (there is no Retry-After for those). Every wait is capped at 2 seconds. There is no flag or docs.json key for this behavior.

If HEAD returns 429 and retries are exhausted, the link is classified as unverified and no GET is sent. A dropped HEAD that still fails after retries falls through to GET, as does a 405 HEAD. That follow-up GET is only retried when the GET itself is a 429 or a dropped connection.

With --debug, each try (including failed ones) produces one debug line.

External link checks run at most 8 at once, and at most 2 against the same hostname. The cap is the hostname only (www.example.com and example.com are different hosts). A slot is held for the whole check of one URL, including retry waits; checking the same URL twice does not take a second slot. There is no flag or docs.json key for this behavior.

Create an in-docs chat agent for a GitHub repository.

docs agent create [flags]

The CLI prints Your documentation agent is ready to use. and a JSON snippet with agent.key to add to docs.json.

Delete the agent configuration for a repository.

docs agent delete [flags]

The CLI prints Deleted agent for org/name.

• CLI: install, init, preview, check, and agent workflows
• Local preview: feature overview
• HTTP endpoints: platform API routes