Input
Accept a command's arguments and flags as one JSON object.
Usage
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
--inputtakes. --inputis read and bound insetup, before any flag handler orpreRun, so everypreRuncheck sees its values whatever the.extend()order.- It is read even when a flag handler such as
--helptakes over:--input - --helpwaits for stdin to end before printing help, and an invalid--inputfails the command instead of showing help.
Behavior
The value of --input is one of:
- inline JSON;
@path, which reads the file atpath, 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.jsondeploysstagingwhatever the file says. Overridden JSON values are dropped before conversion, so an invalid one does not fail;rawis 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 asUnknown flag "--nope"orExpected 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 asInvalid URL for --origin., which never includes the value.