Next Steps
Suggest follow-up commands after a command succeeds or fails.
Usage
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 --ssonextSteps(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 aslogs. The step prints the path the application added it at, nested commands included.input: arguments, flags, andrawtokens in the shaperun()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 whosecommandis a definition. - Its
inputis not typed from the definition, but it is checked when the block is printed like any other step's. onErrorreceives the thrown value as-is: match it yourself, for example withinstanceof.
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,
onErrorsteps come first, then the steps the action added before it failed. Inexecute(), the block follows the error message. - Nothing is printed when there are no steps, or when a flag handler such as
--helptook over. - Under
run(), the block is captured inoutcome.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 --.
| Input | Printed as |
|---|---|
| flag value | --name value, or --name=value when the value starts with - |
boolean true / false | --name / --no-name |
multiple flag or variadic argument array | repeated values |
| number | text; Infinity and -0 print as written |
json value | JSON, 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 argument | after --, 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
rawtokens would fill a positional argument; - the command has an
afterDoubleDashargument 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
jsonvalue 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
falsevalue for anoNegateboolean 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.