@kjanat/dreamcli

The main export. Import schema builders, CLI runner, output, parsing, and errors.

Key types: ActivityEvent, BeforeParseParams, CLIPluginHooks, CommandMeta, CommandSchema, DeprecationWarning, DeriveHandler, DeriveParams, Out, PluginCommandContext, ResolvedCommandParams, RunResult

import {
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
} from '@kjanat/dreamcli';

Schema Builders

command(name)

Create a command builder.

import { , ,  } from '@kjanat/dreamcli';

const  = ('deploy')
  .('Deploy the app')
  .('target', .())
  .('force', .())
  .(({ , ,  }) => {});

group(name)

Create a command group (container for subcommands).

import { ,  } from '@kjanat/dreamcli';

const  = ('migrate');
const  = ('seed');

const  = ('db')
  .('Database operations')
  .()
  .();

cli(name)

Create a multi-command CLI builder.

import { ,  } from '@kjanat/dreamcli';

const  = ('deploy');
const  = ('main');

('mycli')
  .('1.0.0')
  .('My tool')
  .()
  .()
  .('mycli')
  .({ : true })
  .();

.packageJson(settings?)

Enable automatic package.json discovery during .run(). When enabled, dreamcli walks up from the current working directory, reads the nearest package.json, and uses its version and description fields as fallback CLI metadata. Pass { inferName: true } to also infer the CLI name from the package bin entry or package name. This has no effect in .execute().

import { ,  } from '@kjanat/dreamcli';

const  = ('deploy');

('mycli')
  .({ : true })
  .()
  .();

.plugin(definition)

Register a CLI plugin created with plugin(...). Plugins run in registration order and can observe execution before parse, after resolve, before action, and after action.

import { , ,  } from '@kjanat/dreamcli';

const  = ('deploy');
const  = ({}, 'trace');

('mycli').().();

flag

Flag factory with typed builders:

Factory	Type	Default
flag.string()	string | undefined	—
flag.number()	number | undefined	—
flag.boolean()	boolean	false
flag.enum(values)	Union of values | undefined	—
flag.array(inner)	T[]	[]
flag.custom(parseFn)	Return type | undefined	—

arg

Argument factory:

Factory	Type
arg.string()	string
arg.number()	number
arg.enum(values)	Union of provided string values
arg.custom(parseFn)	Return type

middleware<Context>(handler)

Create typed middleware that can wrap downstream execution and add context to the chain.

.derive(handler)

Register a command-scoped typed pre-action handler. Derive runs after resolution, receives typed { args, flags, ctx, out, meta }, and may either return void for validation-only behavior or return an object to merge additional properties into ctx.

import { , ,  } from '@kjanat/dreamcli';

('deploy')
  .('token', .().('AUTH_TOKEN'))
  .(({  }) => {
    if (!.)
      throw new ('Not authenticated', {
        : 'AUTH_REQUIRED',
      });
    return { : . };
  })
  .(({  }) => {
    .;
  });

plugin(hooks, name?)

Create a reusable CLI plugin definition from lifecycle hooks. The returned value can be attached with cli(...).plugin(...) and receives stable hook payloads typed by BeforeParseParams, ResolvedCommandParams, and PluginCommandContext.

import { , ,  } from '@kjanat/dreamcli';

const  = ('deploy');

const  = (
  {
    : ({ ,  }) =>
      .(.(' ')),
    : ({ ,  }) =>
      .({ ,  }),
  },
  'trace',
);

('mycli').().();

Plugin Types

CLIPluginHooks

Lifecycle hook bag for plugin(...). Each hook may be sync or async:

import type {  } from '@kjanat/dreamcli';

Use beforeParse to inspect raw argv, afterResolve to observe resolved args/flags, beforeAction to run immediately before middleware and the action handler, and afterAction to observe successful completion.

PluginCommandContext

Base payload shared by all plugin hooks. It contains the current command schema, meta (CommandMeta), and out channel, so hooks can inspect execution context without reaching into internal CLI state.

import type {  } from '@kjanat/dreamcli';

BeforeParseParams

Payload for beforeParse. Adds the leaf-command argv array to PluginCommandContext so plugins can log, validate, or instrument the exact argument list before parsing starts.

import type {  } from '@kjanat/dreamcli';

ResolvedCommandParams

Payload for afterResolve, beforeAction, and afterAction. Adds fully resolved flags, args, and collected deprecations so hooks can inspect the final command inputs.

import type {  } from '@kjanat/dreamcli';

Execution Types

CommandMeta

Metadata about the running CLI, passed to action handlers and middleware as meta. It carries the CLI name, display bin, version, and current leaf command, making it useful for logging, telemetry, and custom output headers.

import type {  } from '@kjanat/dreamcli';

RunResult

Structured result returned by runCommand(...) and cli.execute(...). It includes the process exitCode, captured stdout/stderr, activity lifecycle events, and an error field that is undefined on success and a CLIError on failure.

import type {  } from '@kjanat/dreamcli';

Output

createOutput(options?)

Create an output channel. Typically not called directly — commands receive out in the action handler.

Parsing

tokenize(argv)

Tokenize raw argv into a Token[] array.

parse(schema, argv)

Parse argv against a command schema, returning ParseResult.

resolve(schema, parseResult, options)

Resolve flag values through the resolution chain.

Schema Export

generateSchema(schema, options?)

Generate a definition metadata document describing the CLI's structure.

• schema: CLISchema from cli.schema
• options.includeHidden?: include hidden commands (default: true)
• options.includePrompts?: include prompt config on flags (default: true)

import {
  ,
  ,
  ,
} from '@kjanat/dreamcli';

const  = ('mycli').(('deploy'));

const  = (.);

generateInputSchema(schema, options?)

Generate a JSON Schema (draft 2020-12) for validating CLI input as JSON.

• schema: CLISchema or CommandSchema
• options.includeHidden?: include hidden commands (default: true)

Accepts a full CLISchema (discriminated union across commands) or a single CommandSchema (flat object schema).

import {
  ,
  ,
  ,
} from '@kjanat/dreamcli';

const  = ('mycli').(('deploy'));

const  = (.);

Completions

generateCompletion(schema, shell, options?)

Generate a shell completion script from a command schema.

• shell: 'bash' | 'zsh' | 'fish' | 'powershell'
• options.functionPrefix?: override the generated helper function prefix
• options.rootMode?: 'subcommands' | 'surface'

Config

buildConfigSearchPaths(appName, cwd, configDir, loaders?)

Build the default search-path list dreamcli uses for config discovery. This is mainly useful for debugging, custom bootstrapping, or help text that wants to show the exact probed paths.

import {  } from '@kjanat/dreamcli';

const  = (
  'mycli',
  process.cwd(),
Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.
  '/home/me/.config',
);

configFormat(extensions, parseFn)

Create a config format loader from a list of file extensions and a parse function. Pass the result to .configLoader(...) or discoverConfig(...) to add YAML, TOML, or other formats on top of the built-in JSON loader.

(['yaml', 'yml'], );
(['toml'], );

discoverConfig(appName, adapter, options?)

Low-level config discovery helper behind cli(...).config(...). It searches standard paths, reads the first matching file via the provided adapter, and returns either { found: true, ... } with parsed config data or { found: false } when no config file exists.

const  = await ('mycli', , {
  : [
    (['yaml', 'yml'], ),
    (['toml'], ),
  ],
});

discoverPackageJson(adapter)

Walk up from adapter.cwd and return the nearest parsed package.json metadata, or null when no package file is found. This is the helper used by .packageJson() during .run().

import {  } from '@kjanat/dreamcli';
import {  } from '@kjanat/dreamcli/testkit';

const  = ();

const  = await ();
if ( !== null) {
  .(.);
}

inferCliName(pkg)

Infer a CLI display name from package metadata. It prefers the first key from a bin object and otherwise falls back to the package name with any npm scope removed.

import {  } from '@kjanat/dreamcli';

({ : { : './dist/cli.js' } }); // 'mycli'
({ : '@scope/mycli' }); // 'mycli'

Errors

CLIError

Base error class with code, exitCode, suggest, details.

ParseError

Extends CLIError. Thrown for argv parsing failures.

ValidationError

Extends CLIError. Thrown for value validation failures.

Type Guards

• isCLIError(err) — narrows to CLIError
• isParseError(err) — narrows to ParseError
• isValidationError(err) — narrows to ValidationError