command & scope

See the Commands and Scopes guides for usage.

command

function command<const A extends ArgList = [], F extends FlagRecord = {}>(
	config: CommandConfig<F, A, RunContext<F, A>>,
): Command<F, A>;

Creates a standalone command. The same as scope({}).command(config).

scope

function scope<const A extends ArgList = [], F extends FlagRecord = {}>(
	config: ScopeConfig<F, A>,
): Scope<F, A>;

Creates a Scope: flags and args shared by every command created from it.

CommandConfig

interface CommandConfig<F extends FlagRecord, A extends ArgList, Ctx, Prefix extends ArgList = []> {
	name?: string;
	description: string;
	aliases?: readonly string[];
	hidden?: boolean;
	flags?: F;
	args?: A & CheckArgs<[...Prefix, ...A]>;
	run: (context: Ctx) => RunResult;
}

Ctx is the context run receives, a RunContext. Prefix is the args inherited from a scope, which are checked together with the command's own.

RunContext

interface RunContext<F extends FlagRecord, A extends ArgList> {
	flags: InferFlags<F>;
	args: InferArgs<A>;
	argv: readonly string[];
}

What run receives: typed flags and args, and the argv the command parsed (without the command path).

RunResult

type RunResult = void | number | Promise<void | number>;

What run returns. A number sets the exit code.

Command

class Command<F extends FlagRecord = FlagRecord, A extends ArgList = ArgList> {
	readonly config: CommandConfig<FlagRecord, ArgList, never>;
	readonly flags: F;
	readonly args: A;
	readonly inherited: ReadonlySet<string>;
	get description(): string;
	get params(): readonly Param[];
	parse(argv: readonly string[], options?: ParseOptions): Promise<Result<Parsed>>;
	execute(parsed: Parsed): RunResult;
}

Member	Description
flags	Own and inherited flags.
args	Inherited args followed by own args.
inherited	Keys of flags inherited from the scope and not redefined.
params	The args as Params.
parse	Parses argv (without the command path) into flags and args.
execute	Calls run with parsed input.

Create commands with command or scope.command rather than new Command.

ParseOptions

interface ParseOptions {
	globals?: FlagRecord;
	strict?: boolean;
	leading?: readonly string[];
	env?: Readonly<Record<string, string | undefined>>;
}

Option	Description
globals	Extra flags parsed and validated alongside the command's own, such as the program's built-ins. Their values aren't included in the result.
strict	Reject unknown flags. Defaults to true.
leading	Positional values captured before the command name (dynamic segments), placed first.
env	Where flags' env variables are read from. Defaults to process.env.

Parsed

interface Parsed {
	flags: Record<string, unknown>;
	args: unknown[];
	argv: readonly string[];
}

The untyped result of Command.parse, passed to Command.execute.

Scope

interface Scope<P extends FlagRecord = {}, PA extends ArgList = []> {
	readonly flags: P;
	readonly args: PA;
	command<const A extends ArgList = [], F extends FlagRecord = {}>(
		config: CommandConfig<F, A, RunContext<MergeFlags<P, F>, [...PA, ...A]>, PA>,
	): Command<MergeFlags<P, F>, [...PA, ...A]>;
	scope<const A extends ArgList = [], F extends FlagRecord = {}>(
		config: ScopeConfig<F, A, PA>,
	): Scope<MergeFlags<P, F>, [...PA, ...A]>;
}

command creates a command that inherits the scope's flags and args. scope creates a nested scope that adds more.

ScopeConfig

interface ScopeConfig<F extends FlagRecord, A extends ArgList, Prefix extends ArgList = []> {
	flags?: F;
	args?: A & CheckArgs<[...Prefix, ...A]>;
}

flags are declared by every command in the scope, and accepted before the command name. Every command in the scope starts with args.

ScopeDefinition

interface ScopeDefinition {
	flags: FlagRecord;
	args: ArgList;
}

The flags and args a command inherits from its scope.

AnyCommand

type AnyCommand = Command<any, any>;

Any command, for constraints in generic code.