Program

See the Program guide for usage.

jinju

function jinju<const T extends CommandTree>(config: ProgramConfig<T>): Program;

Creates a program from a tree of commands. Throws a ConfigError if the tree or its commands are invalid.

ProgramConfig

interface ProgramConfig<T extends CommandTree = CommandTree> {
	name?: string;
	version?: string;
	description?: string;
	commands: T & CheckTree<T>;
	strict?: boolean;
	env?: Readonly<Record<string, string | undefined>>;
	help?: HelpTemplate;
	error?: ErrorTemplate;
	stdout?: (text: string) => void;
	stderr?: (text: string) => void;
	exit?: (code: number) => void;
}

Option	Default	Description
name	The script's file name	Shown in usage.
version		Enables --version.
description		Shown on the root help page.
commands		The command tree.
strict	true	Reject unknown flags.
env	process.env	Where flags' env variables are read from.
help	new HelpTemplate()	Renders help pages.
error	new ErrorTemplate()	Renders error output.
stdout	Writes to process.stdout	Receives help and version output.
stderr	Writes to process.stderr	Receives error output.
exit	Sets process.exitCode	Receives the exit code.

Program

class Program {
	readonly name: string;
	constructor(config: ProgramConfig);
	run(argv?: readonly string[]): Promise<number>;
	help(path?: readonly string[]): string;
}

What jinju returns. Define it once, then call its methods:

const app = jinju({ name: 'app', commands });

await app.run();

Use jinju rather than new Program, because jinju checks the command tree's types.

Properties

Property	Description
name	The program's name: name from the config, or the script's file name.

run(argv?)

run(argv?: readonly string[]): Promise<number>;

Parses argv, routes it to a command and runs it. argv defaults to process.argv.slice(2); pass it yourself to run with other input, e.g. app.run(['build', '--watch']).

Resolves to the exit code, which it also passes to exit (by default, setting process.exitCode). Help, --version and errors are written to stdout or stderr. It rejects only when a run handler throws an error that isn't a JinjuError.

help(path?)

help(path?: readonly string[]): string;

Returns the help text for a command path, e.g. app.help(['sync', 'repeat']), without printing it. With no path, it returns the root page. Throws UnknownCommandError for an unknown name.

CommandTree

interface CommandTree {
	readonly [key: string]: AnyCommand | CommandTree;
}

Commands keyed by name. Nest objects for subcommands; $ is the command for that level. A :name key is a dynamic segment, which captures one word into the commands' arg named name.

packageVersion

function packageVersion(from: string | URL): string;

Reads version from the nearest package.json at or above from, usually the CLI's own import.meta.url. Pass the result as jinju({ version }). Throws a ConfigError when there's no package.json, or it has no version.