Skip to content

About this page

On this page

Registering commands ​

Packages export framework-agnostic CliCommand[] descriptors; build them into a program with engine.cli.program.create() (preferred), or with the lower-level createConfigProgram when the command list is not tied to an engine (this is how the bundled dbx binary and a consumer's own CLI are assembled):

ts
import { configCommands } from '@deltabox/toolchain/config';

const program = engine.cli.program.create(() => configCommands({ engine }), {
    name: 'myapp',
    version: '1.0.0',
    globalOptions: [{ flags: '--json', description: 'Print JSON.' }],
    disableColors: ({ color }) => color === false,
});
await program.invokeAsync();

For config-driven commands, engine.cli.program.create(...) builds the program runtime with schema-derived options and typed run values. It accepts the full program options, including globalOptions, disableColors, helpOnError, groups, sort, format, argv and the output hooks. See Running a built program and the program members.

Custom descriptors do not need to be added to builtinCommands() to appear in the generated reference. Pass the same command list to generateCliDocs:

ts
import { builtinCommands } from '@deltabox/toolchain/cli';
import { generateCliDocs } from '@deltabox/toolchain/config';

const markdown = generateCliDocs([...builtinCommands(), ...myCommands], {
    prefix: 'my-cli',
});

generateCliDocs omits hidden commands, keeps the first of any duplicate name, and renders args/options (with defaults) the same way as the dbx reference.

Typed command args ​

CliCommand infers its run(args, context) object from the literal options list. Use defineCliCommand so the literal tuple is preserved:

ts
import { defineCliCommand } from '@deltabox/toolchain/shared';

const command = defineCliCommand({
    name: 'serve',
    description: 'Serve.',
    options: [
        { flags: '--json', description: 'JSON output.' },
        { flags: '--cwd <dir>', description: 'Project root.' },
        { flags: '--tag <value...>', description: 'Tags.' },
        { flags: '--no-color', description: 'Disable colour.' },
    ],
    // args.json?: boolean, args.cwd?: string,
    // args.tag?: string[], args.color?: boolean
    run: args => serve(args),
});

The same inference is available as a type through CliOptionValues<typeof options>. Unknown positional args and dynamic flags remain addressable through the index signature.

Descriptors also carry optional argv and bin fields. argv feeds the standalone config program runtime (program.invoke()/invokeAsync(), defaulting to process.argv.slice(2)); bin makes that runtime execute a relative or absolute binary instead of the in-process run. See the config program runtime for create(), hooks and help/error formatting.