---
url: https://toolchain.dbx.studio/guide/config-generator/cli-commands.md
---
# CLI commands docs
`configCommands({ engine, defaults })` returns typed `CliCommand[]`; register
them on the engine program with `engine.cli.program.create()` (preferred), or on
a program built with the lower-level `createConfigProgram()` if the command list
is not tied to an engine. They generate config artifacts:
| Command | Writes |
| ----------------- | -------------------------------------------- |
| `config:env` | `.env.example` |
| `config:types` | config types (`--env` also writes env types) |
| `config:json` | `config.json` (metadata) |
| `config:schema` | `config.schema.json` |
| `config:markdown` | the markdown reference |
| `config:cli` | `cli-options.json` |
| `config:all` | everything, under one output directory |
```ts
import { configCommands } from '@deltabox/toolchain/config';
const commands = configCommands({
engine,
defaults: { typesDir: 'packages/shared/src/types', docsDir: 'docs/reference' },
});
const program = engine.cli.program.create(() => commands, { name: 'myapp' });
await program.invokeAsync();
```
> These commands are library-only: `dbx` itself does not register a `config:*`
> group, because each command needs a `ConfigEngine` bound to your schema. Add
> the returned commands to your own program.
The `config:*` commands generate config artifacts; they do not write the CLI
reference. For that, pass the command descriptors your CLI registers to
[`generateCliDocs()` or `engine.markdown.cli.write()`](/guide/config-generator/generate#cli-docs).
## Deriving flags from config fields
When a command flag maps to a config field, generate the option from the schema
instead of hand-writing its flag, description and default. The recommended
entry point is `engine.cli.program.create()`:
```ts
const { commands } = engine.cli.program.create(cmd => [
cmd('tsconfig')
.description('Generate workspace tsconfig files.')
// Genuine runtime flags stay explicit (the escape hatch).
.options([
{ flags: '--cwd
', description: 'Repo root.' },
{ flags: '--json', description: 'Print the resolved config.' },
])
.run(({ config }) => {
// `config` is the validated `tsconfig` section.
}),
]);
```
Config-backed flags are derived recursively: objects and union object branches
expand to dotted paths (`sync.format` → `--format-*`), scalar arrays become list
flags, and arrays of objects/records/maps are skipped unless the field defines
`cli` metadata. Use `engine.cli.program.createCommand(scope, spec)` when you want the
runtime `values` object inferred from the command's `options` list;
`createCommand('name', spec)` / `cmd('name', spec)` build a runtime-only command
with no config scope. Metadata lives in the schema:
```ts
port: z.number().default(3000).meta({ cli: { short: 'p' } }),
aliases: z.boolean().default(true).meta({
cli: { flag: '--no-aliases', type: 'boolean', description: 'Skip path aliases.' },
}),
internal: z.string().meta({ cli: false }),
format: z.union([z.boolean(), z.object({ fix: z.boolean() })]).meta({
cliCommand: { name: 'format', description: 'Format the managed files.' },
}),
```
`cli: false` removes a field (and its subtree) from generated flags without
hiding it from env/types/docs. `cliCommand: false` opts a scope out of automatic
command generation. Env exposure still comes from `envName`/`envPath`; set
`envExpose: false` for CLI-only values. Runtime-only flags (`--cwd`, `--json`,
`--force`, `--dry-run`, output selectors) always stay in the command spec; an
option with a `path` intentionally maps a runtime flag back to a config field.
The lower-level helpers remain available for existing descriptors:
```ts
import { configCliOptions } from '@deltabox/toolchain/config';
const options = [
{ flags: '--json', description: 'Print the resolved config.' },
...configCliOptions(tsconfigConfigSchema),
];
```
Config defaults are applied by the command context, so only explicitly typed
flags are forwarded. `configCliCommand` wraps the same generation with parsing
and validation when the whole command is config-shaped. Use `includePaths` /
`excludePaths` only as a narrow escape hatch; a flag that is not a config field
(output mode, `--cwd`, `--restore`, provider options) stays hand-written and
documented as runtime-only.