Crust logoCrust

Confirm

Ask before a destructive change, or take --yes.

Usage

cli.ts
import { Crust, defineCommand } from "@crustjs/core";
import { confirm } from "@crustjs/extensions";

const drop = defineCommand("drop", { description: "Drop the database" }, (cmd) =>
	cmd.use(confirm).action(async ({ ctx, stdout }) => {
		const ask = await ctx.confirm;
		await ask("Drop the database?");
		stdout("Dropped");
	}),
);

const app = new Crust("my-cli").extend(confirm()).add(drop);

await app.execute();
$ my-cli drop --yes
Dropped

$ my-cli drop < /dev/null
Error: Confirmation required: Drop the database? Pass --yes to confirm.

confirm() provides the confirm Context:

  1. Declare it with .use(confirm).
  2. await ctx.confirm to get the ask function.
  3. await ask(message) before changing anything. It resolves once confirmed and throws otherwise, so the code after it runs only when confirmed.

Without .extend(confirm()) on the app, .use(confirm) is a type error, and preparing the app throws a DEFINITION error.

Behavior

The Context owns a boolean --yes flag. Commands that .use(confirm) accept it, as do the root and its inline .command() children; other commands reject it as an unknown flag. When the command calls ask(message):

  • with --yes, it resolves without asking;
  • when stdin and stderr are both terminals and CI is unset (an empty string, 0, or false in any letter case counts as unset), or a withTerminalIO scope supplies TTY streams (such as runInteractive()'s fake terminal, whatever CI is), it shows a yes/no prompt with message on stderr, defaulting to No. Yes resolves; No throws Not confirmed: <message> Nothing was changed. (exit code 1). Ctrl-C cancels the command (exit code 130);
  • otherwise it throws the exported ConfirmationRequiredError, Confirmation required: <message> Pass --yes to confirm. (exit code 1), so a script, an agent, or a CI job with a pseudo-terminal never waits on a prompt and never succeeds unconfirmed.

--yes is a normal flag:

  • input() can supply it where it is accepted: --input '{"yes":true}'.
  • Only commands that accept it list it in --help, schema, and MCP tool inputs.

The prompt from @crustjs/prompts loads only when a command asks.

Limitations

--yes is a Context-owned flag, so a command that accepts it cannot declare its own yes flag while confirm() is registered.

On this page