Install the dxb CLI and sign in
Install the dxb command-line tool, authenticate with a browser approval or an access token, and switch between profiles.
Install dxb, the Doxbrix command-line tool, and connect it to your Doxbrix account. After this guide, dxb whoami prints your email address and every command that talks to Doxbrix runs as you.
Use this guide the first time you set up dxb on a computer, when you add a second account or environment as a separate profile, or when you need to replace a revoked token.
Before you begin
- Install Node.js 22 or later. Check the version with
node --version; the output must start withv22or higher. - Have a Doxbrix account and a workspace. See Create an account and choose a plan.
- For the browser sign-in, use a computer with a web browser, or any device where you can open the approval page. For servers and CI without a browser, prepare a personal access token instead. See Create and revoke access tokens.
Install dxb
Install the CLI globally with npm.
npm install --global @doxbrix/cliUse the npx form when you want to run the latest version once without a global install. Prefix each later command with npx --yes @doxbrix/cli@latest instead of dxb.
Run:
dxb --version
dxb --helpdxb --version prints the CLI version, and dxb --help lists the command groups, such as init, dev, lint, link, push, auth and docs.
Sign in with the browser
The default sign-in is a device flow: dxb shows a short code, you approve it in the browser while signed in to Doxbrix, and the CLI receives a personal access token without you copying it.
Run:
dxb loginThe CLI prints Open https://app.doxbrix.com/cli/authorize and enter code ABCD-1234, tries to open that page in your browser, and waits with Waiting for approval… (Ctrl-C to cancel). Your code is different from the example.
On the Authorize the Doxbrix CLI page, check that the Device code field matches the code in your terminal, then select Review request. If you are not signed in, sign in first and reopen the link.
The page shows dxb @ <your computer name> and the account it will sign in as.
Under Choose what it can do:, keep or clear each permission. By default the CLI requests all of these:
| Permission | Scope | Allows |
|---|---|---|
| Read documentation | docs:read | Read pages, spaces and navigation |
| Write documentation | docs:write | Create, edit and publish pages |
| View projects | project:read | Read project settings and metadata |
| Manage projects | project:admin | Create projects and change their settings |
| Use AI features | ai:use | Run AI-assisted authoring and review |
| Manage access tokens | tokens:manage | Create, list and revoke access tokens |
Clearing a scope limits what dxb can do. For example, without Manage projects, dxb link --create fails. At least one permission must stay selected.
Select Authorize the CLI. The page changes to CLI authorized and tells you to return to your terminal.
The terminal prints:
✓ Logged in as you@example.com (profile: default).dxb login that you started yourself. A code expires after 10 minutes; if it expires, the CLI prints Device authorization timed out. and asks you to paste a token instead.Sign in with an access token
Use a token when no browser is available, in CI, or when your organization prefers tokens with a limited scope or expiry. Tokens start with dxb_.
dxb login --with-token dxb_your_token_valueThe CLI verifies the token against the API before saving it.
If you are already signed in, you can create a token for another machine from the CLI. The value is shown once:
dxb auth token create "laptop CLI" --scopes docs:read --scopes docs:write --expires-in-days 90List and revoke your tokens with dxb auth token list and dxb auth token revoke <id>.
Verify
Run:
dxb whoami
dxb auth statusdxb whoami prints your email address and name. dxb auth status prints the active profile, the API URL and whether you are authenticated, followed by a table of saved profiles:
Active profile: default
API URL: https://app.doxbrix.com
Authenticated: yes (profile)
Profiles
NAME EMAIL API URL
* default you@example.com https://app.doxbrix.comThe value in parentheses after Authenticated shows where the token came from: flag, env or profile.
For a broader check of the API URL, sign-in, project link and docs.json, run dxb doctor.
Use more than one profile
A profile is a named saved login. Profiles let you keep separate accounts, or a production and a test environment, on one computer. The first login is saved to the default profile.
dxb login --profile workAdd --api-url https://docs-api.example.com when the profile points at a different Doxbrix API origin. Signing in makes that profile the active one.
dxb auth switch defaultThe CLI prints Switched to profile 'default'. If the profile has never signed in, it prints Profile 'work' has no stored login. Run 'dxb login --profile work' first.
Pass --profile to any command, or set DOXBRIX_PROFILE:
dxb whoami --profile workdxb logoutThis removes the stored token for the active profile and prints Logged out of profile 'default'. It does not revoke the token on the server; revoke it with dxb auth token revoke <id> or in the web app.
How dxb chooses its settings
dxb stores logins in ~/.doxbrix/config.json, written with file mode 0600 so only your user can read it. Set DOXBRIX_CONFIG_HOME to keep that file in another directory. A docs project also has a .doxbrix/config.json at its root, but that file only records the linked project and never holds a token, so it is safe to commit.
For each command, the first value found wins:
| Setting | 1st | 2nd | 3rd | Default |
|---|---|---|---|---|
| Token | --token | DOXBRIX_TOKEN | Active profile | None |
| API URL | --api-url | DOXBRIX_API_URL | Active profile | https://app.doxbrix.com |
| Profile | --profile | DOXBRIX_PROFILE | Last profile you signed in to or switched to | default |
| Project | --project or -p | DOXBRIX_PROJECT | Linked project in .doxbrix/config.json | None |
The API URL must be an HTTPS origin with no path, query or credentials. Plain HTTP is accepted only for localhost and loopback addresses.
Troubleshooting
For more CLI problems, see Troubleshoot the CLI, Git sync and MCP.