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 login                       # browser sign-in (or: dxb login --with-token dxb_…)
dxb init my-docs                # scaffold docs.json + starter pages
cd my-docs
dxb dev                         # local preview at http://localhost:4000 (hot reload)
dxb lint                        # validate docs.json, frontmatter, links, orphans
dxb link --create               # create a Doxbrix project and link this folder
dxb push --publish              # publish — search + AI update immediately

Migrating from Mintlify or GitBook?

dxb init . --from mintlify      # or gitbook | generic
dxb lint && dxb link --create && dxb push

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.

Commands

| Group | Commands | |---|---| | Workflow | init, dev, lint, link, push, pull, status, diff, new page | | 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

• 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 lint
      - run: npx @doxbrix/cli@latest push --publish --yes
        env:
          DOXBRIX_TOKEN: ${{ secrets.DOXBRIX_TOKEN }}
          DOXBRIX_PROJECT: my-docs

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.