parseArgs()

Parses an argv array against a command's definitions, performing type coercion, alias expansion, and default value resolution.

This is a pure parse+coerce function — it never throws for missing required values. Use validateParsed() to enforce required constraints separately.

Signature

function parseArgs<
  A extends ArgsDef = ArgsDef,
  F extends FlagsDef = FlagsDef,
>(
  command: CommandNode,
  argv: string[],
): ParseResult<A, F>;

Parameters

Parameter	Type	Description
`command`	`CommandNode`	The command node whose definitions drive parsing. Uses `command.effectiveFlags` for flag parsing and `command.args` for positional argument parsing.
`argv`	`string[]`	The argument array to parse (typically `process.argv.slice(2)`)

Returns

interface ParseResult<A, F> {
  args: InferArgs<A>;     // Resolved positional arguments
  flags: InferFlags<F>;   // Resolved flags
  rawArgs: string[];       // Everything after the `--` separator
}

Throws

CrustError("PARSE") — Unknown flag, number coercion failure
CrustError("DEFINITION") — Invalid flag definition at runtime (alias collision, or flag name/short/alias starting with "no-")

Behavior

Parsing Engine

parseArgs wraps Node's util.parseArgs with Crust-specific semantics:

Strict mode — Unknown flags immediately produce a PARSE error
Positionals allowed — Positional arguments are captured and mapped
Negative flags — --no-<canonical-flag> syntax is supported for boolean flags; --no-<alias> is not supported
Token-based — Uses util.parseArgs tokens for accurate -- separator handling
Effective flags — Parses against command.effectiveFlags (inherited + local merged), not just local flags

Type Coercion

Definition Type	Parser Behavior
`"string"`	Kept as-is
`"number"`	Coerced via `Number()`. Throws `PARSE` if `NaN`
`"boolean"`	Toggle flags. `--flag` -> `true`, `--no-flag` -> `false`. Value assignment forms like `--flag=true` are rejected

Alias Resolution

Aliases are resolved to their canonical flag names:

flags: {
  verbose: { type: "boolean", short: "v" },
}
// --verbose and -v both resolve to flags.verbose

Multiple aliases are supported via short and aliases:

flags: {
  target: { type: "string", short: "t", aliases: ["T"] },
}

Default Values

Flags and arguments without values fall back to their default. If no default is set and the definition isn't required, the value is undefined.

The `--` Separator

Everything after -- is collected into rawArgs and excluded from positional/flag parsing. See Arguments — the -- separator for more.

parseArgs(cmd, ["file.txt", "--", "--verbose"]);
// result.args -> { file: "file.txt" }
// result.rawArgs -> ["--verbose"]

Example

import { Crust, parseArgs } from "@crustjs/core";

const cmd = new Crust("example")
  .args([
    { name: "file", type: "string", required: true },
  ])
  .flags({
    output: { type: "string", default: "dist", short: "o" },
    verbose: { type: "boolean", short: "v" },
  });

const result = parseArgs(cmd._node, ["input.ts", "-o", "build", "--verbose"]);
// result.args.file === "input.ts"
// result.flags.output === "build"
// result.flags.verbose === true
// result.rawArgs === []

On this page