dxb — the Doxbrix CLI

Docs-as-code from the command line. Author Doxbrix documentation locally as files (docs.json + .mdx), preview it like the live site, validate it, and push to your Doxbrix project in one command — with or without GitHub/GitLab.

npm install --global @doxbrix/cli
dxb --help

For a one-off run without a global install:

npx --yes @doxbrix/cli@latest --help

Requires Node ≥ 22.

Quick start

dxb init my-docs                # scaffold marked starter pages
cd my-docs
dxb docs setup --source product=../app # stable source ID; path stays local/ignored
dxb docs status                 # brief, reader coverage, contracts, links, evidence
dxb docs verify                 # safe static example checks
dxb docs check                  # complete local documentation CI gate
dxb dev                         # preview + Review drawer at http://localhost:4000
dxb link --create               # first login: create a hosted project and link it
dxb push --publish              # publish — search + AI update immediately

For a separate agent-first authoring workflow, use the standalone Docloom project. Docloom has its own implementation and connects to Doxbrix only through a public HTTP API:

npm install --global @pateladesh/docloom
docloom init my-docs --source product=../app
cd my-docs
docloom create
docloom preview
docloom test
docloom deploy

Generate docs from a product repository

Initialize Doxbrix at the product repository root so the local agent can inspect both the implementation and documentation:

cd your-product-repository
docloom init . --source product=. --title "Product documentation"
docloom create

The docs can also live in a separate directory or repository:

cd your-docs-repository
docloom init . --title "Product documentation" \
  --source product=/path/to/your-product-repository
docloom create

The source binding is stored as a local path. Docloom deploys documentation files only; configured product source is never included in its deployment payload.

The introduction and quickstart created by dxb init are intentionally marked as unfinished scaffolds. The authoring agent must replace them with a researched landing page and a quickstart that reaches one real, verifiable outcome. dxb lint reports any starter page that remains as an error, so unfinished scaffolds cannot be pushed or published.

Before asking the agent, check out the product version you intend to document and ensure the configured source path contains the code and tests that prove current behavior.

Migrating from Mintlify or GitBook?

dxb init . --from auto          # detects Mintlify, GitBook, native, or generic
dxb dev                         # verify the migrated design and content locally
dxb lint && dxb link --create && dxb push

Migration and local authoring do not require an account. Doxbrix keeps the source navigation, components, reusable snippets, languages and versions, brand assets, fonts, colours, banners, and layout measurements where the source format exposes them. Sign in only when you are ready to create/link a hosted project and deploy.

The local format

A Doxbrix docs project is a folder with:

docs/                           # basePath (configurable)
├── docs.json                   # navigation manifest (authoritative)
├── images/                     # media (also assets/ media/ img/ static/)
└── <space>/<group>/page.mdx    # pages with --- frontmatter ---

docs.json covers every nav type — page, group, label, divider, link, api. Page frontmatter: title, sidebarTitle, description, slug, icon, tags, status, hidden, locale, and pageType. Page contracts include landing, quickstart, how-to, concept, troubleshooting, configuration-reference, rest-api, cli-reference, code-api, migration, release-notes, faq, and reference.

Commands

| Group | Commands | |---|---| | Workflow | init, dev, lint, link, push, pull, status, diff, new page | | Documentation system | docs setup/brief/coverage/inventory/status/impact/verify/review/check | | Import | import repo, import file, init --from <dialect> | | Structure (local) | space list/create, nav tree/add-link/add-label/add-divider/remove | | Git sync | git status/connect/sync/pause/resume/disconnect/conflicts | | Auth | login, logout, whoami, auth status/token/switch | | Content | project list/view/use, page list/get/create, search, review queue | | AI | ai ask, keys list/create/revoke | | Utilities | open, doctor, completion, config, version |

Run dxb <command> --help for details. Every read command supports --json.

Authentication

Authentication is only required for hosted operations such as link, push, pull, project APIs, and Git sync. init, repository migration, authoring, preview, linting, documentation checks, and agent setup all work offline.

• dxb login — browser device flow (default).
• dxb login --with-token dxb_… — paste a Personal Access Token (CI-friendly).
• DOXBRIX_TOKEN env always wins; DOXBRIX_API_URL overrides the host.
• Tokens are stored at ~/.doxbrix/config.json (mode 0600). Manage with dxb auth token create/list/revoke and switch accounts with dxb auth switch. Token-management commands require a PAT with the explicit tokens:manage scope; the normal browser-login token intentionally does not receive it.

Configuration & precedence

Highest → lowest: command flags → env (DOXBRIX_TOKEN, DOXBRIX_API_URL, DOXBRIX_PROJECT, DOXBRIX_PROFILE) → global ~/.doxbrix/config.json → built-in defaults. Project selection and basePath come from the commit-safe project .doxbrix/config.json, but API hosts and tokens never do.

The default cloud host is https://app.doxbrix.com. Remote overrides must use HTTPS; plain HTTP is accepted only for localhost development.

Use in CI

# .github/workflows/docs.yml
name: Publish docs
on: { push: { branches: [main] } }
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npx @doxbrix/cli@latest docs check --strict
      - run: npx @doxbrix/cli@latest push --publish --yes
        env:
          DOXBRIX_TOKEN: ${{ secrets.DOXBRIX_TOKEN }}
          DOXBRIX_PROJECT: my-docs

dxb docs check is local and auth-free. It aggregates manifest/page lint, the persistent brief and coverage, page contracts, local links, evidence receipt validity/freshness, and safe example verification. Add --source <path> --base <ref> when product code is checked out separately and CI should also enforce change impact. In strict mode, unmatched source changes and candidate-only page matches require review. A legitimate no-docs result is recorded against the exact source path and reviewed head commit in documentation.json's impact.noDocs, so a later change must be reviewed again.

Exit codes

0 ok · 1 generic · 2 usage/validation · 3 auth · 4 entitlement (402/403) · 5 conflict · 6 network. Scriptable: dxb status --json | jq .clean.

Shell completion

eval "$(dxb completion bash)"      # bash
eval "$(dxb completion zsh)"       # zsh
dxb completion fish | source       # fish

License

UNLICENSED (internal). See the repository root.