dxb CLI

dxb command reference

Every dxb command, subcommand, option, global option, environment variable and exit code in the Doxbrix CLI.

Use this page to look up the exact syntax of any dxb command. It lists every command group, its subcommands and options, the global options that every command accepts, the environment variables the CLI reads, and the exit codes that scripts and CI jobs can branch on.

To install the CLI and sign in for the first time, see Install the dxb CLI and sign in. For a guided walkthrough, see Tutorial: author docs locally with dxb.

Command overview

dxb is the Doxbrix command-line interface. Running dxb without a command prints help. Add --help (or -h) to any command to print its usage.

Group	Commands
Authentication	`login`, `logout`, `whoami`, `auth`
Local workflow	`init`, `dev`, `lint`, `link`, `push`, `pull`, `status`, `diff`, `quality`, `new`, `import`, `sync`, `docs`
Local structure	`space`, `nav`
Git and review	`git`, `review`
Hosted features	`ai`, `keys`, `project`, `page`, `search`
Utilities	`open`, `doctor`, `completion`, `config`, `version`

Commands in the local workflow and local structure groups work on files in your docs folder. Commands that talk to your Doxbrix workspace need a personal access token; see Global options and Environment variables.

Global options

Every command accepts these options. They are parsed before the command's own options.

Option	Type	Description
`-p`, `--project <slug\|id>`	string	Project slug or id to act on.
`--profile <name>`	string	Auth profile to use.
`--api-url <url>`	string	Override the API base URL. The default is `https://app.doxbrix.com`.
`--token <dxb_…>`	string	Personal access token. Overrides the stored token.
`--cwd <dir>`	string	Run as if the CLI started in this directory.
`--json`	boolean	Write machine-readable JSON to standard output.
`-y`, `--yes`	boolean	Skip confirmation prompts.
`-q`, `--quiet`	boolean	Suppress non-essential output.
`-v`, `--verbose`	boolean	Show verbose output, including request ids and stack traces.
`--color`, `--no-color`	boolean	Force color output on or off.
`-h`, `--help`	boolean	Show help for a command.
`--version`	boolean	Print the CLI version.

How the CLI resolves settings

The CLI resolves each connection setting from the first source that has a value:

Setting	Resolution order
Profile	`--profile` → `DOXBRIX_PROFILE` → the current profile in the global config → the default profile
API URL	`--api-url` → `DOXBRIX_API_URL` → the profile's API URL → `https://app.doxbrix.com`
Token	`--token` → `DOXBRIX_TOKEN` → the profile's stored token
Project	`--project` → `DOXBRIX_PROJECT` → the project linked in `.doxbrix/config.json`

📝The CLI never reads a token from the project file .doxbrix/config.json. Tokens live only in the global config file, in DOXBRIX_TOKEN, or in the --token option.

Environment variables

Variable	Effect
`DOXBRIX_TOKEN`	Personal access token to use when `--token` is not given. Use this in CI.
`DOXBRIX_API_URL`	API base URL to use when `--api-url` is not given.
`DOXBRIX_PROFILE`	Auth profile to use when `--profile` is not given.
`DOXBRIX_PROJECT`	Project slug or id to use when `--project` is not given.
`DOXBRIX_CONFIG_HOME`	Directory for the global config. The default is `~/.doxbrix`.
`NO_COLOR`	Disables colored output.
`FORCE_COLOR`	Forces colored output.

The global config file is ~/.doxbrix/config.json (or $DOXBRIX_CONFIG_HOME/config.json). It stores profiles and tokens with file permissions 0600.

Output and exit codes

With --json, the command writes its result as JSON to standard output so scripts can parse it. Every command exits with one of these stable codes:

Code	Meaning	Typical cause
`0`	Success	The command completed.
`1`	General error	The API returned an unexpected error.
`2`	Usage or validation error	Unknown command, missing or invalid option, not inside a docs project, or a failed `dxb docs check`.
`3`	Authentication error	No token, a rejected token, or a token missing a required scope.
`4`	Entitlement error	Your plan does not include the feature. Upgrade to Pro or Business.
`5`	Conflict	The request conflicts with the current state.
`6`	Network error or rate limit	The API is unreachable, or you were rate limited.

Authentication

login

Authenticate the CLI with a personal access token and store it in the active profile. By default, the command opens a browser approval page that requests the scopes the CLI needs: docs:read, docs:write, project:read, project:admin, ai:use and tokens:manage.

bash

dxb login [--with-token <dxb_…>] [--paste]

Option	Type	Description
`--with-token <dxb_…>`	string	Store this token value and skip the browser flow.
`--paste`	boolean	Paste a token at a prompt instead of using the browser flow.

bash

dxb login
dxb login --with-token dxb_xxx
dxb login --profile work --api-url https://docs-api.example.com

dxb auth login is the same command.

logout

Remove the stored credentials for the active profile.

bash

dxb logout

whoami

Show the authenticated user.

bash

dxb whoami

auth

Manage authentication and profiles. dxb auth login, dxb auth logout and dxb auth whoami match the top-level commands.

bash

dxb auth status
dxb auth switch <profile>
dxb auth token create <name> [--scopes <scope>]... [--expires-in-days <n>]
dxb auth token list
dxb auth token revoke <id>

Subcommand	Description
`auth status`	Show authentication and config status: profiles, API URL, and whether a token is present and where it comes from (flag, environment or profile).
`auth switch <profile>`	Switch the active auth profile.
`auth token create <name>`	Create a personal access token with a human-readable label. `--scopes <scope>` is repeatable. `--expires-in-days <n>` expires the token after `n` days.
`auth token list`	List your personal access tokens.
`auth token revoke <id>`	Revoke a personal access token by id.

You can also manage tokens in the app; see Create and manage access tokens.

Local workflow

init

Scaffold a new local docs project with a docs.json manifest and starter pages.

bash

dxb init [dir] [--name <name>] [--base-path <dir>] [--from auto|generic] [--force]

Argument or option	Type	Description
`dir`	positional	Target directory. The default is the current directory.
`--name <name>`	string	Project display name.
`--base-path <dir>`	string	Docs subfolder. The default is the project root.
`--from <dialect>`	`auto` \| `generic`	Convert an existing docs tree. The dialect is auto-detected.
`--force`	boolean	Write into a non-empty directory.

bash

dxb init my-docs --name "Acme Docs"

dev

Run a local preview server for the docs.

bash

dxb dev [--port <n>] [--open]

Option	Type	Default	Description
`--port <n>`	number	`4000`	Port for the preview server.
`--open`	boolean	—	Open a browser on start.

lint

Validate the local docs project: docs.json, page references, navigation, duplicate slugs, orphan files, frontmatter, unfinished starter pages, components and local images. See docs.json and page format reference for the rules.

bash

dxb lint [--strict]

Option	Type	Description
`--strict`	boolean	Treat warnings as errors and exit non-zero.

link

Link the current folder to a Doxbrix project. Attach an existing project by slug or id, or create a new one with --create. You can also set up Git sync for the project in the same step.

bash

dxb link [project] [--create] [--name <name>] [--slug <slug>] [--visibility public|private] [--editor block|wysiwyg] [git options]

Argument or option	Type	Default	Description
`project`	positional	—	Existing project slug or id (attach mode).
`--create`	boolean	—	Create a new project and link it.
`--name <name>`	string	—	New project name (with `--create`).
`--slug <slug>`	string	—	New project slug (with `--create`).
`--visibility`	`public` \| `private`	—	New project visibility.
`--editor`	`block` \| `wysiwyg`	—	Editor mode.
`--git-repo <owner/name>`	string	—	Set up Git sync to this repository.
`--git-provider`	`github` \| `gitlab` \| `github_enterprise` \| `gitlab_self_managed`	`github`	Git provider.
`--git-create-repo`	boolean	—	Create the repository from the current pages instead of connecting an existing one.
`--git-branch <branch>`	string	—	Tracked branch.
`--git-base-path <dir>`	string	—	Docs subfolder in the repository.
`--git-token <token>`	string	—	Provider personal access token or OAuth token.
`--git-account <id>`	string	—	Connected Git account id. Preferred over `--git-token`.
`--git-conflict-policy`	`git_wins` \| `editor_wins`	—	Which side wins on conflict.
`--git-mode`	`push` \| `pr`	—	Outbound mode: direct push or pull request.
`--git-private`, `--no-git-private`	boolean	—	Make the new repository private or public (with `--git-create-repo`).

bash

dxb link pocketbase-docs
dxb link --create --name "Acme Docs" --slug acme-docs --visibility private

push

Push the local docs to the linked Doxbrix project. Pages upload as drafts unless you add --publish.

bash

dxb push [--dry-run] [--publish] [--no-media] [--allow-orphans] [--strict]

Option	Type	Default	Description
`--dry-run`	boolean	—	Report what would change without writing.
`--publish`	boolean	—	Publish every pushed page.
`--media`, `--no-media`	boolean	`true`	Include media files. Use `--no-media` to skip them.
`--allow-orphans`	boolean	—	Push files that are not in `docs.json`. They are not published.
`--strict`	boolean	—	Fail if any local file is missing from `docs.json`.

bash

dxb push --dry-run
dxb push --publish

pull

Pull the project from Doxbrix into local files.

bash

dxb pull [--force]

Option	Type	Description
`--force`	boolean	Overwrite local files without confirming.

status

Show drift between the local files and the linked remote project.

bash

dxb status

diff

Show a line diff of local files against the remote project.

bash

dxb diff [path]

Argument	Description
`path`	Limit the diff to one docs-relative path.

quality

Score documentation quality for every page, grouped by space.

bash

dxb quality [--space <slug>] [--sort worst|best|title] [--min <0-100>]

Option	Type	Default	Description
`--space <slug>`	string	—	Limit the report to one space.
`--sort`	`worst` \| `best` \| `title`	`worst`	Page order within a space.
`--min <0-100>`	number	—	Only show pages below this overall score.

new page

Scaffold a new page and add it to docs.json.

bash

dxb new page <path> [--title <title>] [--space <slug>] [--type <page-type>]

Argument or option	Type	Description
`path`	positional, required	Docs-relative path, for example `guides/auth`.
`--title <title>`	string	Page title.
`--space <slug>`	string	Target space slug. The default is the first space.
`--type <page-type>`	string	Machine-checkable page contract. See page types.

bash

dxb new page guides/auth --title "Authenticate requests" --type how-to

import

Import existing docs from a source repository or a single file.

bash

dxb import repo [dir] [--out <dir>] [--strict]
dxb import file <path> [--into <path>] [--title <title>]

Subcommand	Options	Description
`import repo [dir]`	`--out <dir>`: output docs directory (default: the project base path). `--strict`: stop before writing when source constructs cannot be transformed.	Convert a local documentation repository to Doxbrix. `dir` defaults to the current directory.
`import file <path>`	`--into <path>`: docs-relative page path. `--title <title>`: page title.	Convert a `.docx`, `.pdf`, `.html`, `.md` or `.txt` document to a Doxbrix page.

sync

Add new local folders and files to docs.json, creating spaces and groups as needed.

bash

dxb sync [--dry-run] [--space <slug>]

Option	Type	Description
`--dry-run`	boolean	Show what would change without writing.
`--space <slug>`	string	Put all pages into this space; folders become groups.

📝dxb sync edits the local manifest. To synchronize a project with a Git repository, use dxb git.

docs

Plan, verify, review and maintain documentation against real product sources. These commands run locally, need no sign-in or network, and never publish. They keep a documentation brief in .doxbrix/documentation.json and machine-specific source paths in the ignored file .doxbrix/local.json.

bash

dxb docs <subcommand> [options]

Several subcommands accept --source <[id=]path>, which is repeatable and names a product source root. It overrides the local source bindings.

Subcommand	Description	Options
`docs setup`	Create or update the documentation brief and local source bindings.	`--source`, `--product <name>`, `--documented-version <version>`, `--primary-audience <audience>` (repeatable), `--secondary-audience <audience>` (repeatable), `--first-success <outcome>`, `--reader-job <goal>` (repeatable), `--include <surface>` (repeatable), `--exclude <surface>` (repeatable), `--publication public\|customer\|partner\|internal\|undecided`, `--release-status <policy>`, `--rest-api`, `--code-api`, `--force`
`docs brief init`	Same as `docs setup`.	Same as `docs setup`
`docs brief show`	Show the documentation brief.	—
`docs brief validate`	Validate that the brief has the decisions agents need.	—
`docs coverage show`	Show reader-journey coverage and its computed state.	—
`docs coverage refresh`	Add current pages to coverage without deleting confirmed reader goals.	`--force`: replace existing coverage with page-derived rows
`docs coverage validate`	Fail when required reader goals have no ready destination.	—
`docs inventory`	Build a secret-safe inventory of product sources.	`--source`, `--write`/`--no-write` (default: write `.doxbrix/inventory.json`)
`docs status`	Show the brief, coverage, evidence freshness, page contracts and link health.	`--source`
`docs impact`	Map source changes to documentation pages.	`--source`, `--base <ref>` (omit for working-tree changes), `--head <ref>` (default: `HEAD`)
`docs verify`	Statically validate examples, and optionally run configured verification commands.	`--source`, `--run`, `--id <id>` (repeatable)
`docs review`	Run a focused, read-only documentation review.	`--source`, `--mode factual\|first-use\|failure-recovery\|completeness\|security\|navigation\|maintainability\|comprehensive` (default: `comprehensive`)
`docs check`	Run the complete local documentation CI gate: lint, brief and coverage, page contracts, links, evidence receipts, source freshness, example verification, and optional Git change impact.	`--source`, `--base <ref>`, `--head <ref>`, `--strict` (fail on warnings too), `--run`

dxb docs check exits with code 2 when it finds an error, or a warning in --strict mode.

bash

dxb docs setup --source ../product
dxb docs impact --base origin/main
dxb docs check --source ../product --base origin/main --strict

To run these checks in a pipeline, see Run dxb checks and pushes in CI.

Local structure

space

Manage spaces in the local docs.json. dxb spaces is an alias.

bash

dxb space list
dxb space create <name> [--slug <slug>] [--locale <locale>] [--parent <slug>]

Subcommand	Description
`space list` (alias `ls`)	List spaces in the local `docs.json`.
`space create <name>`	Add a space to `docs.json` and create its folder. `--slug` sets the space slug, `--locale` its locale, and `--parent` the parent space slug.

nav

Edit navigation in the local docs.json. Each subcommand accepts --space <slug> to target a space; the default is the first space.

bash

dxb nav tree [--space <slug>]
dxb nav add-link <title> <href> [--space <slug>] [--group <label>]
dxb nav add-label <text> [--space <slug>]
dxb nav add-divider [--space <slug>]
dxb nav remove <file> [--space <slug>]

Subcommand	Description
`nav tree`	Print the local navigation tree.
`nav add-link <title> <href>`	Add an external link. `--group <label>` places it inside a group.
`nav add-label <text>`	Add a section label.
`nav add-divider`	Add a divider.
`nav remove <file>` (alias `rm`)	Remove a page node by its file reference, for example `guides/auth`.

bash

dxb nav add-link "Status page" https://status.example.com --group Resources

Git and review

git

Manage Git sync between the project and a GitHub or GitLab repository. All git subcommands act on the resolved project. For the browser workflow, see Sync a project with a Git repository.

bash

dxb git status
dxb git preview --repo <owner/name> [target options]
dxb git connect --repo <owner/name> [target options] [--mode push|pr] [--conflict-policy git_wins|editor_wins] [--create-repo] [--private|--no-private]
dxb git sync
dxb git pause
dxb git resume
dxb git disconnect
dxb git conflicts list
dxb git conflicts resolve <pageId> --keep editor|git

Subcommand	Description
`git status`	Show the Git connection and recent sync runs.
`git preview`	Dry-run a connection: test the credentials and report what would import (pages, spaces, images, dialect, redirects) and whether the credentials can write.
`git connect`	Connect an existing repository, or create one with `--create-repo`.
`git sync`	Pull the latest changes from Git now.
`git pause`	Pause syncing.
`git resume`	Resume syncing.
`git disconnect`	Disconnect the repository. Content stays in the project.
`git conflicts list`	List unresolved sync conflicts.
`git conflicts resolve <pageId>`	Resolve a conflict. `--keep editor` or `--keep git` is required.

Target options for git preview and git connect:

Option	Type	Default	Description
`--repo <owner/name>`	string, required	—	Repository full name.
`--provider`	`github` \| `gitlab` \| `github_enterprise` \| `gitlab_self_managed`	`github`	Git provider. Omit when you pass `--account`.
`--branch <branch>`	string	`main`	Tracked branch.
`--base-path <dir>`	string	—	Docs subfolder in the repository.
`--git-token <token>`	string	—	Provider personal access token or OAuth token.
`--account <id>`	string	—	Connected Git account id. Preferred over `--git-token`.
`--installation-id <id>`	string	—	GitHub App installation id.
`--host <url>`	string	—	Host for GitHub Enterprise or GitLab self-managed.

Additional options for git connect:

Option	Type	Description
`--mode`	`push` \| `pr`	Outbound delivery: direct push or pull request.
`--conflict-policy`	`git_wins` \| `editor_wins`	Which side wins when both sides changed.
`--create-repo`	boolean	Create a new repository from the current pages.
`--private`, `--no-private`	boolean	Make the new repository private or public (with `--create-repo`).

bash

dxb git preview --repo acme/docs --account acc_123
dxb git connect --repo acme/docs --account acc_123 --branch main --base-path docs --mode pr
dxb git conflicts resolve pg_123 --keep editor

See Resolve Git sync conflicts for when to keep each side.

review

Work with the review workflow.

bash

dxb review queue

Subcommand	Description
`review queue`	List pages awaiting review.

Hosted features

ai

Ask the project's AI assistant a question.

bash

dxb ai ask <question> [--locale <locale>]

bash

dxb ai ask "How do I rotate an API key?" --project acme-docs

keys

Manage assistant API keys for Ask AI and the embedded assistant. See Embed the assistant on another website.

bash

dxb keys list
dxb keys create <label> [--origin <url>]... [--allow-private]
dxb keys revoke <id>

Subcommand	Description
`keys list`	List assistant API keys.
`keys create <label>`	Create an assistant API key. `--origin <url>` is repeatable and sets an allowed browser origin. `--allow-private` permits access to private content.
`keys revoke <id>`	Revoke an assistant API key.

bash

dxb keys create "Marketing site" --origin https://www.example.com

project

Manage projects.

bash

dxb project list
dxb project view [project]
dxb project use <project>

Subcommand	Description
`project list`	List projects you can access.
`project view [project]`	Show a project. The default is the selected project.
`project use <project>`	Select a project as the default for this folder.

page

Work with pages in the hosted project.

bash

dxb page list [--space <spaceId>] [--status <status>] [--limit <n>]
dxb page get <id> [--content]
dxb page create <title> --space <spaceId> [--parent <navItemId>]

Subcommand	Options	Description
`page list`	`--space <spaceId>`; `--status draft\|in_review\|published\|unpublished\|archived`; `--limit <n>` (1–500, default `100`)	List pages in a project.
`page get <id>`	`--content`: include the content blocks	Show a page.
`page create <title>`	`--space <spaceId>` (required); `--parent <navItemId>`	Create a page in a space.

search

Search a project's docs.

bash

dxb search <query> [--limit <n>] [--locale <locale>]

Option	Type	Default	Description
`--limit <n>`	number	`20`	Maximum hits, from 1 to 100.
`--locale <locale>`	string	—	Locale to search.

Utilities

open

Open the project in the browser.

bash

dxb open [app|editor]

The default target is app.

doctor

Diagnose the CLI setup. The command checks the API URL, authentication, whether you are inside a docs project, the project link, and docs.json and its pages. Each check reports ok, warn or fail.

bash

dxb doctor

completion

Print a shell completion script.

bash

dxb completion bash|zsh|fish

bash

dxb completion zsh > "${fpath[1]}/_dxb"

config

Manage CLI configuration. The supported keys are telemetry (on or off) and api-url.

bash

dxb config list
dxb config get <key>
dxb config set <key> <value>

bash

dxb config set telemetry off

version

Print the CLI version. dxb --version does the same.

bash

dxb version

Next steps

📝

Author docs locally

Follow the end-to-end local workflow with dxb.

⚙️

Run dxb in CI

Gate pull requests with docs checks and push on merge.

📄

docs.json reference

Look up manifest keys, frontmatter and lint rules.

🛠️

Troubleshoot the CLI

Fix sign-in, link and sync errors.