---
url: https://toolchain.deltabox.studio/guide/cli.md
---
# CLI

The `dbx` binary is composed from framework-agnostic command
descriptors. Commands that run against a project load its
`dbx.config.ts` first, 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.                                       |
| `--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.       |

These override the [`logger` config](/guide/config/logging) 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:

```sh
dbx create                     # template + name + scope + template inputs/actions
dbx migrate --recursive        # choose the projects to migrate
```

`dbx 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](#scaffolding) and
[Migrations](#migrations) for the flag forms.

## Output

Colour is on by default and follows `--no-color` / the [`logger` config](/guide/config/logging).

## 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`).                                                               |

### 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:

```sh
dbx sync --only tsconfig
```

Unknown 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](/guide/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](/guide/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](/guide/templates).

## Migrations

```sh
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:list
```

See [Migrations](/guide/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:

```sh
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 az
```

GitHub 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](/guide/ci/) for the vendor
workflow config.

## Providers

Every provider subcommand is a passthrough. Vite+ commands are reachable both
directly and through the `vite` namespace:

```sh
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):

```ts
import {
    createCli,
    runCli,
    builtinCommands,
    registerToolchainCommands,
    withDefaultVite,
    extractConfigSelection,
    extractLogOptions,
} from '@deltabox/toolchain/cli';
```

| Export                                         | Description                                                            |
| ---------------------------------------------- | ---------------------------------------------------------------------- |
| `createCli()`                                  | Build the `dbx` commander program (global flags + built-in commands).  |
| `runCli(argv?)`                                | Parse and run the CLI (extracts logger flags, then defaults Vite+).    |
| `builtinCommands()`                            | The commands built into the root CLI (config commands need an engine). |
| `registerToolchainCommands(program, commands)` | Wire `ToolchainCommand[]` descriptors onto a commander program.        |
| `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.                    |

`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:

```ts
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](/guide/config-generator/).