Core

@crustjs/core defines commands, routes and validates argv, constructs Contexts, applies Extensions, and runs Command Actions.

Install

npm install @crustjs/core

The package supports Bun 1.4+, Node 22+, and Deno 2.8+.

Quick example

src/cli.ts

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

const app = new Crust("hello")
	.flags({ name: "verbose", type: "boolean", short: "v" })
	.action(({ flags, stdout }) => stdout(flags.verbose ? "hello!" : "hello"))
	.command("wave", (command) => command.action(({ stdout }) => stdout("o/")));

const outcome = await app.run([], { flags: { verbose: true } });
console.log(outcome.stdout); // => hello!

The root action prints hello! when verbose is true. The wave command is an app-local leaf command; use defineCommand() for a reusable definition.

Context-owned flags

src/cli.ts

import { Crust as ContextApp, defineContext, defineFlag } from "@crustjs/core";

const apiKey = defineFlag("api-key", { type: "string", required: true });
const api = defineContext("api", { flags: [apiKey] }, ({ flags }) => ({
	apiKey: flags["api-key"],
}));

const contextApp = new ContextApp("my-cli")
	.provide(api())
	.action(async ({ ctx, stdout }) => stdout((await ctx.api).apiKey));

const contextOutcome = await contextApp.run([], { flags: { "api-key": "secret" } });
console.log(contextOutcome.stdout); // => secret

A Context can own the flags needed by its setup. .provide() installs that Context on the current command and commands added later; see Contexts.

Runtime exports

import {
  Crust,
  CrustError,
  defineArg,
  defineCommand,
  defineContext,
  defineExtension,
  defineExtensionId,
  defineFlag,
} from "@crustjs/core";

Export	Role
`Crust`	Root command builder with `run()`, `execute()`, and `snapshot()`
`defineCommand()`	Creates an inert reusable command definition
`defineContext()`	Creates a named Context factory
`defineExtension()`	Creates an Extension or Extension factory
`defineExtensionId()`	Creates a branded Extension identity
`defineArg()` / `defineFlag()`	Creates named argument and flag definitions
`CrustError`	Framework error for definition, routing, parsing, and validation failures

Definition and boundary types

import type {
  ArgDef,
  CommandSnapshot,
  CrustCommandContext,
  Extension,
  FlagDef,
  InvocationIO,
} from "@crustjs/core";

The root barrel exports the command, Context, Extension, input, snapshot, and error types used by applications. See Types for their fields and constraints.

Type	Reference
`ArgDef` / `FlagDef`	`ArgDef` and `FlagDef`
`ContextBag` / `ContextFactory` / `ContextSetup`	Context types
`Extension` / `ExtensionFactory` / `ExtensionBuildContext`	Extension types
`CommandSnapshot` / `ArgSnapshot` / `FlagSnapshot`	Command Snapshot
`BuildFile` / `BuildArtifacts`	`BuildFile` and `BuildArtifacts`
`BuildReport`	`BuildReport`
`DefineExtensionWith` / `RootMetaKey`	`RootMetaKey` and `DefineExtensionWith`
`MergeFlags`	`MergeFlags`
`MergeContext`	`MergeContext`

The root barrel is the full supported export list.

Typed invocation

const outcome = await app.run(["wave"]);
if (outcome.status === "completed") console.log(outcome.stdout); // => o/

run() returns a captured outcome after cleanup. See run() input and I/O for typed paths, structured input, validation, output capture, and failure behavior.

Tooling subpath

import { defineExtensionId } from "@crustjs/core";
import { buildCommandDocumentation, visibleSectionsFor } from "@crustjs/core/tooling";

const snapshot = await app.snapshot();
const documentation = buildCommandDocumentation(snapshot);
const visible = visibleSectionsFor(snapshot, defineExtensionId("acme:web-docs"));

Export	Role
`BUILD_OUT_DIR_ENV` / `SNAPSHOT_PATH_ENV`	Environment variable names for the first-party subprocess protocol
`buildCommandDocumentation()`	Builds a renderer-ready documentation tree from a Command Snapshot
`formatDefault()` / `formatDescription()`	Formats input defaults and descriptions
`isListed()` / `sectionsFor()` / `visibleSectionsFor()`	Filters commands and sections for an Extension identity
`CommandDocumentation` / `DocumentationArg` / `DocumentationFlag` / `UsageSegment`	Documentation model types
`CommandSnapshot`	Command Snapshot type used by tooling consumers

@crustjs/core/tooling contains build-time helpers for Command Snapshots, documentation trees, section filtering, formatting, and the first-party subprocess protocol. Application authoring and invocation APIs stay at the package root. The subprocess protocol applies to source entries run by crust build; finished Bun and Node bundles compile it out through the CRUST_INTERNAL_BUILD marker, and Deno binaries are unchanged.