CLI
The dbx binary is composed from framework-agnostic command descriptors. Commands that run against a project load its toolchain config — the dbx() Vite plugin config when present, otherwise the nearest dbx.config.* — so config-derived defaults apply unless you override them on the command line.
Global flags
| Flag | Description |
|---|---|
--log-level <lvl> | Minimum log level: debug, info, warn, error, silent. |
--color | Force coloured output (the default). |
--no-color | Disable coloured output (including help/error formatting). |
--no-update-check | Do not check for a newer dbx version. |
--config <file> | Use a specific config file instead of discovering one. |
--no-config | Ignore config files and use CLI flags/env defaults only. |
-H, --help | Display help for the program or subcommand. |
-V, --version | Output the version number. |
These override the logger config and may appear before or after the subcommand. --config resolves relative to the current directory (absolute paths are used as-is); --no-config skips discovery entirely (including inherited parent configs).
dbx checks the npm registry in the background (about once a day) and prints a short notice with a link to the release when a newer version is published. The check is skipped in CI and when NO_UPDATE_NOTIFIER or DBX_NO_UPDATE_CHECK is set, and can be turned off with --no-update-check.
Interactive CLI
The CLI is scriptable first: every prompt has a flag equivalent. In a TTY, however, some commands prompt when the flags are omitted:
dbx create # template + name + scope + template inputs/actions
dbx migrate --recursive # choose the projects to migratedbx migrate detects migrations automatically without --from; the prompt is only the project picker for --recursive. --json, a piped stdin, or the explicit flags disable prompts. See Scaffolding and Migrations for the flag forms.
Output
Colour is on by default and follows --no-color / the logger config. --no-color also disables the program's configured help/error colours (the dbx program passes disableColors from the parsed global color flag).
Core
| Command | Description |
|---|---|
projects | Discover projects and write .dbx/toolchain/projects.json. |
sync | Regenerate every managed file (--check, --recursive, --watch, --force, --only, --json). |
watch | Sync once, then watch key inputs and re-sync. |
reset | Remove generated files, the manifest and/or the config (--all, --recursive); reverts tsconfig.overrides first. |
providers | List registered providers + their commands (--json). |
enable | Enable the toolchain (--workspace by default, or --global; --json). |
disable | Disable the toolchain (--workspace by default, or --global; --json). |
enabled | Print the resolved enabled state and scope (--json). A config toolchain.enabled wins over .vscode/settings.json. |
Task-only sync
dbx sync --only <tasks> runs just the named sync tasks (comma-separated) and does not prune files owned by the tasks it skipped. This is useful at the end of a build, when only the tsconfig aliases/references need refreshing:
dbx sync --only tsconfigUnknown task names fail with the list of available tasks.
Scaffolding
| Command | Description |
|---|---|
project:init | A single-package TypeScript project (--package-manager). |
project:init:monorepo | A monorepo root (add --example for one example workspace). |
project:init:workspace | A workspace package into an existing monorepo root. |
project:config | Generate dbx.config.* for projects missing one (TS/JS, --skip-config for graph only; folds vite.config.*). |
create | Scaffold from a template (--template/--kind, --name, --scope, --out). |
Templates that declare inputs/actions are prompted for them (--var key=value, --action <id>), see Templates.
On an interactive terminal, a bare dbx create (no --template/--kind/--name) prompts for the template, name and scope with clack; Ctrl-C cancels. See Templates.
Templates
| Command | Description |
|---|---|
template:list | List templates (--kind, --registry, --online, --json). |
template:init | Write a template.json to a directory (--kind, --name, --add, --no-global). |
template:add | Record a source (auto-inits local; --no-global keeps it project-only). |
template:remove | Remove a source by id or type:locate. |
template:registry | List/add/remove the global template search paths (--vscode-dir, --clear). |
registry | List/add/remove/set template or provider registries (--kind, --scope). |
template:info | Show one template. |
See Templates.
Migrations
dbx migrate --from biome --write # .oxfmtrc.json + .oxlintrc.json
dbx migrate --from biome --from prettier --write # several sources
dbx migrate --from biome --target vite --write
dbx migrate --from oxc --write # .oxfmtrc/.oxlintrc -> dbx.config
dbx migrate --from all # every detected source
dbx migrate --from vite --recursive --write # migrate every detected project
dbx migrate --recursive # interactive project picker
dbx migrate --check # CI: exit 1 when stale
dbx migrate:listSee Migrations.
Tsconfig / cleanup / changelog / workflows
| Command | Description |
|---|---|
tsconfig | Regenerate workspace tsconfig.json files (--restore [kind] reverts overrides). |
cleanup / cleanup:turbo | Remove build artifacts / the turbo cache. |
changelog | Derive the semver bump and update CHANGELOG + versions. |
workflow | Trigger generated workflows with their vendor CLI (gh, glab or az). |
Workflows
dbx workflow [id...] runs every enabled workflow (or the named ids/custom ids/file names) with the CLI for its provider:
dbx workflow # every enabled workflow
dbx workflow ci release # by id
dbx workflow deploy.yml # by file name
dbx workflow --list --json # ids, paths and providers
dbx workflow ci --ref main # pass a branch/ref
dbx workflow ci --gh /path/to/gh --glab glab --az azGitHub uses gh workflow run <file>, GitLab glab ci run (the project's configured CI file), and Azure az pipelines run --name <pipeline> (the file stem by default). When the matching CLI is not installed the command reports it and continues with the other workflows. See CI for the vendor workflow config.
Providers
Every provider subcommand is a passthrough. Vite+ commands are reachable both directly and through the vite namespace:
dbx fmt # the active formatter (vp fmt when Oxc)
dbx run -r build # forwards to `vp run -r build`
dbx vite dev # explicit namespace (always works)
dbx vite:build # named alias for `vp build`A bare dbx <command> is forwarded to Vite+ when the name (or a Vite+ alias) matches — built-in commands win, so dbx migrate stays the toolchain's migration. The vite command forwards its operands verbatim, so every Vite+ CLI command and flag is reachable.
Programmatic
The CLI is assembled from framework-agnostic command descriptors, so a consumer can build its own program (or reuse the routing helpers):
import {
createCli,
runCli,
builtinCommands,
withCliContext,
withDefaultVite,
extractConfigSelection,
extractLogOptions,
} from '@deltabox/toolchain/cli';| Export | Description |
|---|---|
createCli(commands?, options?) | Build the dbx engine program (global flags + built-in commands). |
runCli(argv?, options?) | Parse and run the CLI (extracts logger flags, then defaults Vite+). |
builtinCommands() | The commands built into the root CLI (config commands need an engine). |
withCliContext(commands) | Wrap commands with dbx config loading, logging and framing. |
withDefaultVite(argv, commandNames?) | Insert vite before a bare Vite+ command (built-ins win). |
extractLogOptions(argv) | Pull --log-level / --color / --no-color out of argv. |
extractConfigSelection(argv) | Pull --config <file> / --no-config out of argv. |
createCli(commands) accepts a typed command array (for example from defineCliCommand) and keeps the command/option types on program.commands; createCli() uses builtinCommands().
Invalid argv prints only the error message by default. Pass { helpOnError: true } to createCli({ helpOnError: true }), createCli(commands, { helpOnError: true }) or runCli(argv, { helpOnError: true }) to also print the full help after an unknown option/command or a bad value.
dbx groups options and commands by default: vite:list is listed under a Vite+ commands: heading. The built-in commands mirror the docs sidebar: core workspace commands stay under Commands:, followed by Project & templates, Tooling, Automation & API, Agents and Vite+. Commands are sorted ascending by name within each section by default; pass { sort: 'desc' } to reverse that or { sort: false } to keep registration order (in groups too). Pass { groups: false } for flat lists, or { groups: { auto: false } } to only honor explicit command groups. The same options work through createCli and runCli.
extractLogOptions makes the logger flags work before or after the subcommand and stops at --, so a wrapped binary's own flags are never eaten. withDefaultVite powers the bare-command passthrough described above:
extractLogOptions(['node', 'dbx', 'sync', '--no-color']);
// { argv: ['node', 'dbx', 'sync'], options: { color: false } }
withDefaultVite(['node', 'dbx', 'fmt', '--check']);
// ['node', 'dbx', 'vite', 'fmt', '--check']Config generator
The generic Zod/env config engine is not a dbx command: a consumer builds an engine with createConfigEngine and registers the config:* commands on its own CLI. See Config Generator.