CLI

The @docs.page/cli package is the local companion to docs.page hosting. Run it from your project root to create starter files, see edits in the browser before you push, catch broken links and missing assets, and provision the in-docs AI chat agent for a GitHub repository.

docs.page serves documentation from a public GitHub repository. There is no separate deploy dashboard. The CLI fits that Git-native model: scaffold into an existing repo, lint before push or in CI, and preview work in progress without opening a branch on GitHub.

Local preview renders page content on your machine while the browser loads the production preview shell. You see real theme and layout without embedding a full copy of the docs.page app. check improves quality before push; it does not upload or publish anything.

npx @docs.page/cli init
npx @docs.page/cli preview
npx @docs.page/cli check

For flag-level detail and exit codes, see CLI.

Install @docs.page/cli once, then run commands from any docs.page project on your machine.

Before you begin: Node.js installed and a terminal open at your project root.

To try a command without a global install, prefix it with npx:

npx @docs.page/cli [command]

npx downloads the package when needed and runs it immediately. This works well for one-off scaffolding or CI jobs.

To use the shorter docs command everywhere, install the package globally:

npm install -g @docs.page/cli

pnpm add -g @docs.page/cli

After install, both docs and docs.page binaries point to the same CLI:

docs --help
docs.page preview

Reinstall the latest version when preview behavior or flags change:

npm install -g @docs.page/cli@latest

pnpm add -g @docs.page/cli@latest

For a single project, npx @docs.page/cli@latest [command] always resolves the newest release.

Run docs --version to print the installed CLI version. Run docs <command> --help for flags on a specific command.

Run docs init to create the files docs.page expects: a docs.json configuration file and, by default, starter content under docs/. Templates use your project name so you can push and open a live URL quickly.

For a full first-publish walkthrough including GitHub push, follow Quickstart.

• Open a terminal at your project root

  Use an empty directory or the root of an existing repository.

  cd my-docs

• Run init

  The CLI scaffolds docs.page files in the current directory.

  npx @docs.page/cli init

  In an interactive terminal, the CLI prompts for your project name and whether to create starter pages. Accept the defaults unless you already have a docs/ directory you want to keep.

• Review the created files

  With default choices, init writes:

  docs.json
  docs/
    index.mdx
    next-steps.mdx

  • docs.json: site name, description, sidebar, and theme
    • docs/index.mdx: home page (served at /)
    • docs/next-steps.mdx: second page (served at /next-steps)
• Initialize a subdirectory or skip starter pages when scripting

  Pass flags to avoid prompts in CI or scripts:

  npx @docs.page/cli init ./my-project --name "My Project"
  npx @docs.page/cli init --no-docs

  Use --no-docs when you only need docs.json and will add page files yourself.

• Re-run init safely in an existing project

  When docs.page files already exist, init skips them unless you pass --overwrite:

  npx @docs.page/cli init --overwrite

  Warning

  --overwrite replaces files created by docs.page init. Review the skipped-file list before confirming in interactive mode.

Confirm docs.json exists at the project root and at least one .mdx file lives under docs/ if you created starter pages. See Introduction for how paths map to URLs.

Run docs preview when you want to see layout and theme changes before pushing to GitHub. The CLI watches docs.json (or docs.yaml) and docs/**/*.mdx on your machine, renders each page with the same production content pipeline, and streams updates to the hosted preview UI.

For shareable branch and pull request previews after you push, see Branch preview.

• Open a terminal at your project root

  Use the directory that contains docs.json.

• Start the preview server

  npx @docs.page/cli preview

  The CLI starts a local WebSocket server, prints the socket URL, and opens your browser to a preview URL shaped like:

  https://docs.page/preview?url=ws://localhost:57250

  The browser loads the production preview shell while file reads and bundling stay on localhost.

• Edit and save

  Change any watched file under docs/ or update docs.json. The preview reloads without a Git push.

• Customize port or browser behavior when needed

  npx @docs.page/cli preview --port 4000
  npx @docs.page/cli preview --no-browser

  Use --no-browser in remote development or when you want to copy the printed URL manually.

After the server starts, confirm the terminal shows Local preview server started, the browser renders your home page with the correct sidebar, and saving a change in docs/index.mdx updates the preview within a few seconds.

Local asset resolution in preview mode has known gaps. Prefer relative paths that match how files are laid out in your repository.

Run docs check after preview looks right and before you push. The command reads your configuration, scans docs/**/*.mdx, and reports link and asset problems you can fix locally or block in CI.

• Open a terminal at your project root

  Use the directory that contains docs.json or docs.yaml.

• Run check

  npx @docs.page/cli check

  The CLI checks that docs.json or docs.yaml is readable, then scans your pages for:

  • Broken internal links: paths that do not resolve to another page or asset in the repo
    • Missing assets: images and other referenced files that are not on disk
    • Unreachable external links: HTTP targets that fail when fetched

  Frontmatter fields redirect, next, and previous are included in link scanning.

• Fix reported issues

  The CLI prints file paths and targets for each problem. Address error-level findings before you push.

• Tune severity when external links are flaky or you want warnings only

  npx @docs.page/cli check --external-links warn --internal-links error --assets error

  Each category accepts off, warn, or error. All three default to error.

• Check a subdirectory or monorepo package

  npx @docs.page/cli check ./packages/docs

• Wire check into CI

  The command exits with code 1 when any error-level issue is found:

  - name: Check documentation
    run: npx @docs.page/cli check

  check does not publish or upload anything. Public GitHub hosting updates the live site when you push to your default branch.

A clean run ends with no error-level output and exit code 0. Re-run after each fix until check passes.

Agent commands call the docs.page API. Set the API base URL with a global flag or environment variable:

docs --api-url https://your-api.example.com agent create --repo org/repo

export DOCS_PAGE_API_BASE=https://your-api.example.com
docs agent create --repo org/repo

When neither is set, the CLI uses the production docs.page API. init, preview, and check do not need an API URL.

Use docs agent to provision the in-docs AI chat panel for a repository. The CLI encrypts your LLM provider API key locally, verifies you have GitHub admin access, and registers the agent with the docs.page API.

Before you begin: Admin access to the target GitHub repository, a provider API key from OpenAI, Anthropic, Google, or xAI, and GitHub CLI authenticated (gh auth login) or a token you can pass with --gh-auth.

• Run create from your project root or any directory

  npx @docs.page/cli agent create --repo org/repo --provider openai --apikey sk-...

  Omit flags in an interactive terminal to be prompted for the repository, provider, and API key.

• Copy the agent key into docs.json

  On success, the CLI prints an agent.key value to add to your repository:

  "agent": {
    "key": "your-agent-key"
  }

  Commit and push docs.json so the live site enables the reader-facing panel.

• Overwrite an existing agent when rotating keys

  npx @docs.page/cli agent create --repo org/repo --provider anthropic --apikey sk-ant-... --force

Supported providers: openai, anthropic, google, xai.

Remove stored agent credentials for a repository:

npx @docs.page/cli agent delete --repo org/repo

Pass --gh-auth <token> when gh auth token is unavailable.

After create, the CLI prints Your documentation agent is ready to use and a JSON snippet for docs.json. After delete, the agent panel no longer loads on the live site once credentials are removed. See Ask AI for placeholder text, starter questions, and rate limits on the reader-facing panel.

• CLI: flags, severities, and exit codes
• Local preview: feature overview for browser preview
• Branch preview: shareable ref URLs after you push
• Quickstart: get a live site in minutes
• Ask AI: configure the in-docs chat panel