Quick Start

Create a projectCopy Anchor Link

npx create-crust@latest my-cli
cd my-cli

Run itCopy Anchor Link

npm run dev -- Ada --greet Welcome
# Welcome, Ada!

The help() extension generates usage from the same definitions:

npm run dev -- --help

my-cli - A CLI built with Crust

Usage:
  my-cli [name] [options]

Arguments:
  [name]             Your name [default: "world"]

Options:
  -g, --greet                  Greeting to use [default: "Hello"]
  -v, --version                Show version number
  -h, --help                   Show help

Add a subcommandCopy Anchor Link

Chain .command() onto the root:

import { Crust } from "@crustjs/core";
import { help, version } from "@crustjs/extensions";

import pkg from "../package.json" with { type: "json" };

const app = new Crust("my-cli", { description: "A CLI built with Crust", version: pkg.version })
	.extend(version(), help())
	.args({
		name: "name",
		type: "string",
		description: "Your name",
		default: "world",
	})
	.flags({
		name: "greet",
		type: "string",
		description: "Greeting to use",
		default: "Hello",
		short: "g",
	})
	.action(({ args, flags, stdout }) => {
		stdout(`${flags.greet}, ${args.name}!`);
	})
	.command("build", (command) =>
		command
			.flags({ name: "minify", type: "boolean", description: "Minify output" })
			.action(({ flags, stdout }) => stdout(`minify: ${flags.minify ?? false}`)),
	);

await app.execute();

npm run dev -- build --minify
# minify: true

npm run dev -- Ada
# Hello, Ada!

my-cli build routes to the subcommand; anything else still reaches the root action. Inline .command() suits app-local commands. Move to defineCommand and split files when a command needs its own file or reuse.

Build itCopy Anchor Link

npm run build
npm run start Ada

crust build stages your selected artifact and npm packaging metadata in .crust/. npm is optional: standalone binaries embed their runtime and can also ship as release downloads or through Homebrew and other installers, without the Node-based npm launcher. Runtime packages still require their selected runtime. See Build and distribution for targets and output layouts.

Choose your runtimeCopy Anchor Link

The runtime runs your CLI; the package manager installs dependencies. For Bun and Node.js, use whichever package-manager tab you prefer.

npm install @crustjs/core @crustjs/extensions
npm install -D typescript @types/bun

{
  "type": "module"
}

{
  "compilerOptions": {
    "target": "ESNext",
    "lib": ["ESNext"],
    "types": ["bun"],
    "module": "Preserve",
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Create the entrypointCopy Anchor Link

Create src/cli.ts. The same code works on all three runtimes:

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

const app = new Crust("my-cli")
	.extend(help())
	.args({ name: "name", type: "string", default: "world" })
	.action(({ args, stdout }) => {
		stdout(`Hello, ${args.name}!`);
	});

await app.execute();

Run and check itCopy Anchor Link

bun run src/cli.ts Ada
bun run src/cli.ts --help
bunx tsc --noEmit