Termost

You can install Termost using npm, pnpm, or yarn depending on your preferred package manager.

# Npm
npm install termost
# Pnpm
pnpm add termost
# Yarn
yarn add termost

When upgrading from version 1.x.x to 2.0.0, several breaking changes require manual updates to your implementation. The underlying prompt and task runner libraries have changed from enquirer and listr2 to @clack/prompts. While high-level APIs like input, option, and task should remain functional without changes, the helpers namespace has been removed, and logging mechanisms have been unified.

npm install termost@2.0.0

By default, the return value of an instruction is not automatically added to the command's Context. To make an instruction's output available in the Context object for subsequent instructions, you must use the InstructionKey pattern by providing a key in the return object.

export type InstructionKey<Key> = {
	/**
	 * Makes the method output available in the context object. By default, if no provided key, the
	 * output is not included in the context.
	 */
	key: Key;
};

In version 2.0.0, helpers.format is removed. For text styling (such as bold or italic), use the styleText function from the built-in node:util module.

- import { format } from "termost";
- console.log(format.bold("My styled message"));
+ import { styleText } from "node:util";
+ console.log(styleText(["bold", "italic"], "My styled message"));

In version 2.0.0, the helpers namespace is removed. You must now import createLogger and exec directly from the termost package.

- import { helpers, termost } from "termost";
+ import { createLogger, exec, termost } from "termost";

- const log = helpers.createLogger("my-cli");
+ const log = createLogger({ name: "my-cli" });

- helpers.exec("echo 'Hello from shell'");
+ exec("echo 'Hello from shell'");

Termost provides a createLogger helper to manage stdout/stderr with consistent formatting and namespacing.

import { createLogger } from "termost";

const logger = createLogger({ name: "my-cli" });

logger.info("Info message");
logger.warn("Warning message");
logger.error("Error message");
logger.success("Success message");

The command({ name, description }) API creates a new subcommand context. The root command context is shared across all subcommands, but subcommand contexts are scoped and cannot be accessed by other subcommands.

program
	.command({
		name: "build",
		description: "Transpile and bundle in production mode",
	})
	.task({
		handler(context, argv) {
			logger.info(`👋 Hello, I'm the ${argv.command} command`);
		},
	});

The helpers.message and helpers.format methods are no longer available in version 2.0.0. They have been replaced by a unified logger built on @clack/prompts. To log messages, instantiate a logger using createLogger and call the appropriate level method (e.g., .info()).

- helpers.message("info", "Hello world");
+ const log = createLogger({ name: "my-cli", level: "info" });
+ log.info("Hello world");

The option({ key, name, description, defaultValue, skip, validate }) API defines a contextual CLI option. The value provided by the user is persisted in the program context using the provided key.

program
	.option({
		key: "optionWithAlias",
		name: { long: "shortOption", short: "s" },
		description: "Useful CLI flag",
		defaultValue: 0,
	})
	.option({
		key: "optionWithoutAlias",
		name: "longOption",
		description: "Useful CLI flag",
		defaultValue: "defaultValue",
		validate(context) {
			if (context.optionWithoutAlias === "invalid") return new Error("Invalid input");
			return undefined;
		},
	});

The input({ key, label, type, skip, validate, ...typeParameters }) API creates an interactive prompt. Supported types include select, multiselect, confirm, and text.

Values are persisted to the context via the key property.

program
	.input({
		type: "select",
		key: "input1",
		label: "What is your single choice?",
		options: ["singleOption1", "singleOption2"],
		defaultValue: "singleOption2",
	})
	.input({
		type: "text",
		key: "input4",
		label: (context) => `Dynamic label: ${context.input1}`,
		defaultValue: "Empty input",
		skip(context) {
			return Boolean(context.input3);
		},
		validate(context) {
			if (context.input4 === "invalid") return new Error("Invalid input");
			return undefined;
		},
	});