Crust logoCrust

Input

Accept a command's arguments and flags as one JSON object.

Usage

cli.ts
import { Crust } from "@crustjs/core";
import { input } from "@crustjs/extensions";

const app = new Crust("my-cli").extend(input()).command("deploy", (cmd) =>
	cmd
		.args({ name: "target", type: "string", required: true })
		.flags({ region: { type: "string", default: "us" } })
		.action(({ args, flags, stdout }) => {
			stdout(`Deploying ${args.target} to ${flags.region}`);
		}),
);

await app.execute();
$ my-cli deploy --input '{"target":"prod","region":"eu"}'
Deploying prod to eu

$ my-cli deploy --input @deploy.json
$ echo '{"target":"prod"}' | my-cli deploy --input -

input() adds a recursive string --input flag. Without the flag, nothing changes.

  • It adds a "JSON input" section to the root command's help, man page, and generated skills, so an agent reading the CLI's documentation knows what --input takes.
  • --input is read and bound in setup, before any flag handler or preRun, so every preRun check sees its values whatever the .extend() order.
  • It is read even when a flag handler such as --help takes over: --input - --help waits for stdin to end before printing help, and an invalid --input fails the command instead of showing help.

Behavior

The value of --input is one of:

  • inline JSON;
  • @path, which reads the file at path, relative to the working directory;
  • -, which reads all of stdin. Stdin that something else already read to the end reads as empty, which fails as invalid JSON. Stdin that another reader is consuming, such as the MCP transport, fails with --input: cannot read stdin (stdin is in use by another reader).

It must be a JSON object keyed by the routed command's argument and flag names, plus raw for passthrough values received as rawArgs, like tokens after --. Flags an Extension declares, such as --json or --help, are not part of it; pass them on argv. This is the flat shape commandInputSchema() describes and the MCP server accepts. Variadic arguments and multiple flags take arrays, and url values take strings.

The object is bound with ctx.bindInput(), so values are converted and validated exactly as typed run() input:

  • Arguments and flags given on argv win over the same keys, even when equal to the default: my-cli deploy staging --input @deploy.json deploys staging whatever the file says. Overridden JSON values are dropped before conversion, so an invalid one does not fail; raw is overridden when argv has passthrough tokens after --.
  • Every other key replaces the environment value or default. Keys are replaced whole; objects are not merged.

Under run(), pass the JSON text as the input flag, for example { args: { target: "dev" }, flags: { input: '{"target":"prod"}' } }. Nothing came from argv, so its keys replace the typed input.

Errors

Each fails the command with a PARSE CrustError before validation and the action run:

  • invalid JSON, a value that is not a JSON object, a file that cannot be read, or a command whose input cannot be one flat object because an argument and a flag share a name or one is named raw: a message starting with --input:. Invalid JSON names its source (--input: invalid inline JSON., --input: invalid JSON in "input.json"., or --input: invalid JSON from stdin.) but not the parser's reason, which can quote the input;
  • an unknown key or a value of the wrong type: the same error typed run() input reports, such as Unknown flag "--nope" or Expected a boolean for --force.;
  • an Extension flag such as json: Flag "--json" is not command input: set it on the command line;
  • an invalid value, such as a bad url: the same error argv reports, such as Invalid URL for --origin., which never includes the value.

On this page