Crust logoCrust

Next Steps

Suggest follow-up commands after a command succeeds or fails.

Usage

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

class NotLoggedInError extends Error {}

const logs = defineCommand("logs", { description: "Stream logs" }, (cmd) =>
	cmd.flags({ env: { type: "string" } }).action(({ stdout }) => stdout("…")),
);

const login = defineCommand("login", { description: "Log in" }, (cmd) =>
	cmd.flags({ sso: { type: "boolean" } }).action(({ stdout }) => stdout("Logged in")),
);

const deploy = defineCommand("deploy", { description: "Deploy the app" }, (cmd) =>
	cmd
		.use(nextSteps)
		.args({ name: "env", type: "string", required: true })
		.action(async ({ args, ctx, stdout }) => {
			if (!process.env.MY_CLI_TOKEN) throw new NotLoggedInError("Not logged in.");
			stdout(`Deployed to ${args.env}`);
			const steps = await ctx.nextSteps;
			steps.add(logs, { flags: { env: args.env } }, "Follow the logs");
		}),
);

const app = new Crust("my-cli")
	.extend(
		nextSteps({
			onError(error) {
				if (error instanceof NotLoggedInError) {
					return [{ command: login, input: { flags: { sso: true } }, description: "Log in" }];
				}
			},
		}),
	)
	.add(deploy, logs, login);

await app.execute();
$ my-cli deploy prod
Deployed to prod
Next steps:
  Follow the logs:
    my-cli logs --env prod

$ MY_CLI_TOKEN= my-cli deploy prod
Error: Not logged in.
Next steps:
  Log in:
    my-cli login --sso

nextSteps(options?) provides a Context named nextSteps. A command declares it with .use(nextSteps), then, from its action, awaits ctx.nextSteps and calls .add(definition, input?, description?) on it:

  • definition: the command definition to suggest, such as logs. The step prints the path the application added it at, nested commands included.
  • input: arguments, flags, and raw tokens in the shape run() takes them, typed from the definition's arguments and flags, such as { args: { env: "prod" }, flags: { force: true } }.
  • description: what the step is for, printed above its command line.

options.onError(error) returns recovery steps for a failed invocation, or undefined for none:

  • Each step is a { command, input?, description? } object whose command is a definition.
  • Its input is not typed from the definition, but it is checked when the block is printed like any other step's.
  • onError receives the thrown value as-is: match it yourself, for example with instanceof.

The app must .extend(nextSteps()) for a command that uses it: TypeScript rejects the .add() otherwise, and preparing the app throws a DEFINITION error (missing-extension).

Behavior

After the invocation completes or fails, nextSteps() prints a Next steps: block to stderr as plain text, even under json().

  • On a failure, onError steps come first, then the steps the action added before it failed. In execute(), the block follows the error message.
  • Nothing is printed when there are no steps, or when a flag handler such as --help took over.
  • Under run(), the block is captured in outcome.stderr.

Command lines

Each step prints as a shell-quoted command line built from the target command's Command Snapshot: flags first, then positional arguments in declaration order, then any raw tokens after --.

InputPrinted as
flag value--name value, or --name=value when the value starts with -
boolean true / false--name / --no-name
multiple flag or variadic argument arrayrepeated values
numbertext; Infinity and -0 print as written
json valueJSON, strings included: "hello" prints as '"hello"'
positionals, when the command has subcommands or one starts with -after --, so no value is routed as a subcommand
afterDoubleDash argumentafter --, before any raw tokens; the other positionals stay before --

Skipped steps

Steps are checked when the block is printed. Each definition is looked up in the application with commandPathOf(), by identity: a .as() copy is a different definition, and one added more than once prints its shallowest path.

A step is skipped, with a nextSteps(): note on stderr, when:

  • the application does not add its definition;
  • it names an unknown argument or flag;
  • it gives a positional argument after an omitted earlier one, or its raw tokens would fill a positional argument;
  • the command has an afterDoubleDash argument and a value before -- starts with - or names a subcommand (only that argument reads after --);
  • a repeatable flag value is empty or contains the flag's delimiter (argv would split or drop it);
  • a number value is NaN (argv rejects it);
  • a json value would change through JSON: a non-finite number, -0, undefined, or anything else that is not plain JSON data;
  • a boolean flag value is not a boolean.

A throwing onError is reported the same way. Printing never changes the invocation's exit code or result.

Limitations

  • Steps print after failures in the action, in validation, and in Context setup. Routing failures (an unknown command), argv syntax errors (a missing flag value), and invalid typed run() input fail earlier, so no steps print for them; didYouMean() covers unknown commands.
  • A false value for a noNegate boolean flag has no command-line spelling and is left out.
  • The root command has no definition, so it cannot be a step.
  • Looking a definition up builds the commands it searches; if one's recipe throws, the step is skipped with that error as the note.

On this page