### Install @crustjs/create

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/create.mdx

Install the @crustjs/create package using Bun.

```sh
bun add @crustjs/create
```

--------------------------------

### Usage Examples

Source: https://github.com/chenxin-yan/crust/blob/main/packages/create-crust/templates/modular/README.md

Examples demonstrating how to run subcommands and display help for the CLI.

```sh
{{name}} greet world
```

```sh
{{name}} greet --greet Hey world
```

```sh
{{name}} --help
```

--------------------------------

### Install @crustjs/prompts

Source: https://github.com/chenxin-yan/crust/blob/main/packages/prompts/README.md

Install the package using bun.

```sh
bun add @crustjs/prompts
```

--------------------------------

### Pack and Install CLI (Bun Runtime Package)

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/development.mdx

Pack your CLI into a tarball and install it into a throwaway project to simulate a real npm installation. This tests the publish artifact.

```sh
bun run build
TARBALL="$(pwd)/$(bun pm pack 2>/dev/null | tail -1)"

mkdir -p ../my-cli-install
cd ../my-cli-install
bun init -y
bun add "$TARBALL"

./node_modules/.bin/my-cli --help
```

--------------------------------

### Modular CLI Application Setup

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/installation.mdx

Defines the base Crust application with metadata and flags that can be inherited by subcommands. This is the starting point for a modular CLI.

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

export const app = new Crust("my-cli").meta({ description: "My CLI tool" }).flags({
  greet: {
    type: "string",
    description: "Greeting to use",
    default: "Hello",
    short: "g",
    inherit: true,
  },
});
```

--------------------------------

### Install @crustjs/progress

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/progress.mdx

Install the @crustjs/progress package using bun.

```sh
bun add @crustjs/progress
```

--------------------------------

### Quick Example: Create a Greeting CLI

Source: https://github.com/chenxin-yan/crust/blob/main/packages/core/README.md

A basic example demonstrating how to create a command-line application named 'greet' that accepts a 'name' argument and a 'loud' flag. The application prints a greeting, optionally in uppercase if the 'loud' flag is set.

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

const app = new Crust("greet")
	.meta({ description: "Say hello" })
	.args([{ name: "name", type: "string", default: "world" }] as const)
	.flags({
		loud: { type: "boolean", description: "Shout it", alias: "l" },
	})
	.run(({ args, flags }) => {
		const msg = `Hello, ${args.name} દૂર!`;
		console.log(flags.loud ? msg.toUpperCase() : msg);
	});

app.execute();
```

--------------------------------

### Registering Multiple Plugins

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/plugins.mdx

Register multiple official plugins like version, did-you-mean, and help using the .use() method. This example shows a typical setup for a CLI application.

```typescript
import { Crust } from "@crustjs/core";
import { helpPlugin, versionPlugin, didYouMeanPlugin } from "@crustjs/plugins";

const main = new Crust("my-cli")
  .meta({ description: "My CLI" })
  .use(versionPlugin("1.0.0"))
  .use(didYouMeanPlugin({ mode: "help" }))
  .use(helpPlugin())
  .run(() => {
    console.log("Running!");
  });

await main.execute();
```

--------------------------------

### Install Crust Plugins

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/plugins/index.mdx

Install the official Crust plugins package using bun.

```sh
bun add @crustjs/plugins
```

--------------------------------

### Install @crustjs/skills

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/skills.mdx

Install the @crustjs/skills package using Bun.

```sh
bun add @crustjs/skills
```

--------------------------------

### Install @crustjs/utils

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/utils.mdx

Install the @crustjs/utils package using Bun.

```sh
bun add @crustjs/utils
```

--------------------------------

### Install Crust Style Package

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/style.mdx

Install the @crustjs/style package using Bun.

```sh
bun add @crustjs/style
```

--------------------------------

### Install Dependencies

Source: https://github.com/chenxin-yan/crust/blob/main/AGENTS.md

Installs project dependencies using Bun.

```sh
bun install              # install deps
```

--------------------------------

### Subcommand Help Output Example

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/plugins/help.mdx

Shows the help output for a specific subcommand, including its path and options.

```text
my-cli build - Build the project

USAGE:
  my-cli build [options]

OPTIONS:
  --minify, --no-minify         Disable minification
  -h, --help, --no-help         Show help
```

--------------------------------

### SetupContext

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/api/types.mdx

Provides context information available during the plugin setup phase, including command-line arguments, the root command, and plugin state.

```APIDOC
## `SetupContext`

Context available during plugin setup:

```ts
interface SetupContext {
  readonly argv: readonly string[];
  readonly rootCommand: CommandNode;
  readonly state: PluginState;
}
```
```

--------------------------------

### Install Crust CLI

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/crust.mdx

Install the @crustjs/crust package as a development dependency using Bun.

```sh
bun add -d @crustjs/crust
```

--------------------------------

### Subcommand Help Example

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/plugins/help.mdx

Demonstrates how to access help for specific subcommands, including nested ones.

```text
my-cli --help              # Help for root command
my-cli build --help        # Help for build subcommand
my-cli create plugin --help # Help for nested subcommand
```

--------------------------------

### Install Core Package

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/core.mdx

Install the core package using Bun package manager.

```sh
bun add @crustjs/core
```

--------------------------------

### Example Help Output

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/plugins/help.mdx

Displays the auto-generated help text for a CLI tool, including commands and options.

```text
my-cli - My CLI tool

USAGE:
  my-cli <command> [options]

COMMANDS:
  build               Build the project
  issue (issues, i)   Manage issues
  dev                 Start dev server

OPTIONS:
  -h, --help, --no-help          Show help
  -v, --version, --no-version    Show version number
```

--------------------------------

### Install @crustjs/store

Source: https://github.com/chenxin-yan/crust/blob/main/packages/store/README.md

Install the @crustjs/store package using your preferred package manager.

```sh
# bun
bun add @crustjs/store

# npm
npm install @crustjs/store

# pnpm
pnpm add @crustjs/store
```

--------------------------------

### Install Hand-Authored Skill Bundle

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/skills.mdx

Demonstrates how to install a hand-authored skill bundle using installSkillBundle. This is used when you have a directory with a SKILL.md file and supporting assets.

```typescript
import { installSkillBundle } from "@crustjs/skills";
import pkg from "./package.json" with { type: "json" };

await installSkillBundle({
  // Resolved relative to the nearest package.json walking up from
  // process.argv[1]. You may also pass an absolute path or a file: URL.
  // Resolution is performed by `resolveSourceDir` from
  // [`@crustjs/utils`](/docs/modules/utils#resolvesourcedir).
  sourceDir: "skills/funnel-builder",
  agents: ["claude-code", "opencode"],
  version: pkg.version,
});
```

--------------------------------

### Install @crustjs/man

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/man.mdx

Install the @crustjs/man package as a development dependency.

```sh
bun add -d @crustjs/man
```

--------------------------------

### Running a Modular CLI Command

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/installation.mdx

Example of how to execute a specific subcommand ('greet') of a modular CLI application, passing arguments and flags.

```sh
bun run src/cli.ts greet world
```

--------------------------------

### Install Fish Completion

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/plugins/completion.mdx

This command installs the fish completion script. Fish automatically loads completions from ~/.config/fish/completions/.

```fish
my-cli completion fish > ~/.config/fish/completions/my-cli.fish
```

--------------------------------

### Development Server for Docs

Source: https://github.com/chenxin-yan/crust/blob/main/CONTRIBUTING.md

Starts a local development server for the documentation site.

```shell
bun run dev:docs
```

--------------------------------

### Run Development Server

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/README.md

Use this command to start the development server for the Crust CLI framework.

```bash
bun run dev
```

--------------------------------

### Quick Example of All Prompts

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/prompts.mdx

Demonstrates the usage of input, confirm, select, multiselect, filter, and multifilter prompts in a single script.

```ts
import { input, confirm, select, multiselect, filter, multifilter } from "@crustjs/prompts";

const name = await input({ message: "Project name?" });
const useTS = await confirm({ message: "Use TypeScript?" });

const framework = await select({
  message: "Framework",
  choices: ["react", "vue", "svelte"],
});

const features = await multiselect({
  message: "Features",
  choices: ["linting", "testing", "ci"],
  required: true,
});

const language = await filter({
  message: "Language",
  choices: ["typescript", "javascript", "rust"],
});

const addons = await multifilter({
  message: "Add-ons",
  choices: ["tailwind", "testing", "storybook", "eslint"],
});
```

--------------------------------

### SetupActions

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/api/types.mdx

Defines the actions that can be performed during plugin setup, such as adding flags or subcommands to a command node.

```APIDOC
## `SetupActions`

Actions available during plugin setup:

```ts
interface SetupActions {
  addFlag(command: CommandNode, name: string, def: FlagDef): void;
  addSubCommand(parent: CommandNode, name: string, command: CommandNode): void;
}
```

- `addFlag` — inject a flag into a command's `effectiveFlags` object (`localFlags` is unchanged). If the command already has a flag with the same name, the plugin's flag overrides it. [`crust build`](/docs/guide/build#pre-compile-validation) emits a warning when this happens.
- `addSubCommand` — inject a subcommand into a command's `subCommands` record. If the parent already has a subcommand with the same name (user-defined), the call is skipped — user definitions always take priority. [`crust build`](/docs/guide/build#pre-compile-validation) emits a warning when this happens.
```

--------------------------------

### Install @crustjs/store

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/store.mdx

Install the @crustjs/store package using Bun. This command adds the necessary dependency to your project for local persistence.

```sh
bun add @crustjs/store
```

--------------------------------

### Plugin Usage Example

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/plugins.mdx

Demonstrates how to register custom plugins, such as the timing plugin and the help plugin, with a Crust CLI instance.

```typescript
new Crust("my-cli").use(timingPlugin()).use(helpPlugin());
```

--------------------------------

### Consumer Installing Skill Bundle from npm Package

Source: https://github.com/chenxin-yan/crust/blob/main/packages/skills/README.md

Demonstrates how a consumer installs a skill bundle from an npm package. It uses `import.meta.resolve` to create a `file:` URL for the bundle's source directory and passes the package version for update detection.

```typescript
import skillsPkg from "acme-skills/package.json" with { type: "json" };

await installSkillBundle({
	sourceDir: new URL(import.meta.resolve("acme-skills/skills/funnel-builder")),
	agents: ["claude-code"],
	version: skillsPkg.version,
});
```

--------------------------------

### Initialize Crust App with Completion Plugin

Source: https://github.com/chenxin-yan/crust/blob/main/packages/plugins/README.md

This snippet shows how to initialize a Crust application and integrate the completion plugin. Ensure you have the necessary packages installed.

```typescript
import { Crust } from "@crustjs/core";
import { completionPlugin } from "@crustjs/plugins";
import pkg from "../package.json";

const app = new Crust("my-cli")
	.use(completionPlugin({ version: pkg.version }))
	.command("build", (cmd) =>
		cmd
			.meta({ description: "Build artifact" })
			.flags({ target: { type: "string", choices: ["browser", "bun", "node"] } })
			.run(() => {}),
	)
	.run(() => {});

await app.execute();
```

--------------------------------

### SKILL.md Frontmatter Example

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/skills.mdx

An example of the frontmatter required in a SKILL.md file for hand-authored bundles. Both 'name' and 'description' are mandatory fields.

```yaml
---
name: funnel-builder
description: Build a sales funnel
---
```

--------------------------------

### Mimic Global Install with `bun link -g`

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/development.mdx

Use `bun link -g` to make your CLI available as a global command, mimicking a global installation. This is useful for testing global command availability.

```sh
bun link -g my-cli
my-cli --help
```

--------------------------------

### Execute Inline Subcommands

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/subcommands.mdx

Examples of how to execute the defined inline subcommands and the help command. These demonstrate basic usage and flag passing.

```bash
my-cli build              # Runs the build command
my-cli dev --port 8080    # Runs the dev command
my-cli --help             # Shows help with available subcommands
```

--------------------------------

### Installing a Skill Bundle with a Specific Version

Source: https://github.com/chenxin-yan/crust/blob/main/packages/skills/README.md

Installs a skill bundle from a specified directory, targeting specific agents, and assigning a version. The `version` is recorded in `crust.json` for update detection.

```typescript
await installSkillBundle({
	sourceDir: "skills/funnel-builder",
	agents: ["claude-code"],
	version: "2.0.0",
});
```

--------------------------------

### Help Mode Output Example

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/plugins/did-you-mean.mdx

In help mode, the plugin displays the suggestion along with the CLI's help information to standard output.

```text
Unknown command "buld". Did you mean "build"?

my-cli - My CLI tool

USAGE:
  my-cli <command> [options]

COMMANDS:
  build      Build the project
  dev        Start dev server
  deploy     Deploy to production

OPTIONS:
  -h, --help, --no-help          Show help
  -v, --version, --no-version    Show version number
```

--------------------------------

### Install Core Framework and CLI Tooling (Standalone Binaries)

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/installation.mdx

Use this command to add the core framework and plugins as development dependencies when building standalone binaries. It also installs CLI tooling and TypeScript types.

```sh
# Core framework and plugins are build-time inputs
bun add -d @crustjs/core @crustjs/plugins

# CLI tooling (crust build)
bun add -d @crustjs/crust @types/bun typescript
```

--------------------------------

### package.json prepublishOnly Script for Completion Files

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/plugins/completion.mdx

Example package.json script to pre-generate completion files for bash, zsh, and fish before publishing.

```jsonc
// package.json
{
  "scripts": {
    "prepublishOnly": "bun run dist/my-cli.js completion bash --output-dir completions/",
  },
  "files": ["dist", "completions"]
}
```

--------------------------------

### Quick Start with Default Style Instance

Source: https://github.com/chenxin-yan/crust/blob/main/packages/style/README.md

Use the default style instance for basic text styling. It auto-detects color support.

```ts
import { style } from "@crustjs/style";

// The default `style` instance auto-detects color support
console.log(style.bold("Build succeeded"));
console.log(style.red("Error: missing argument"));
console.log(style.dim("hint: use --help for usage"));
console.log(style.bold.red("Critical failure"));
console.log(style.link("Docs", "https://crustjs.com"));
```

--------------------------------

### Basic CLI with Version and Help Plugins

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/index.mdx

This example demonstrates setting up a basic CLI application using Crust. It includes metadata, version and help plugins, defines a string argument with a default value, and a boolean flag. The `run` function defines the CLI's core logic.

```typescript
import { Crust } from "@crustjs/core";
import { helpPlugin, versionPlugin } from "@crustjs/plugins";

const main = new Crust("greet")
  .meta({ description: "A friendly greeter CLI" })
  .use(versionPlugin("1.0.0"))
  .use(helpPlugin())
  .args([
    {
      name: "name",
      type: "string",
      description: "Who to greet",
      default: "world",
    },
  ])
  .flags({
    shout: { type: "boolean", description: "SHOUT the greeting", short: "s" },
  })
  .run(({ args, flags }) => {
    const message = `Hello, ${args.name} জিহ`;
    console.log(flags.shout ? message.toUpperCase() : message);
  });

await main.execute();
```

--------------------------------

### Timing Plugin Example

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/plugins.mdx

A plugin that measures and logs the execution time of a command. It uses `performance.now()` to record the start and end times.

```typescript
import type { CrustPlugin } from "@crustjs/core";

function timingPlugin(): CrustPlugin {
  return {
    name: "timing",
    async middleware(context, next) {
      const start = performance.now();
      await next();
      const duration = (performance.now() - start).toFixed(2);
      console.log(`Completed in ${duration}ms`);
    },
  };
}
```

--------------------------------

### Install Fish Completion (Inline Eval)

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/plugins/completion.mdx

This method evaluates the fish completion script inline in your ~/.config/fish/config.fish file.

```fish
# in ~/.config/fish/config.fish
my-cli completion fish | source
```

--------------------------------

### Nixpkgs postInstall for Shell Completion

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/plugins/completion.mdx

Nixpkgs postInstall script to install pre-generated completion files for bash, zsh, and fish.

```nix
postInstall = ''
  installShellCompletion \
    --bash completions/my-cli \
    --zsh  completions/_my-cli \
    --fish completions/my-cli.fish
'';
```

--------------------------------

### Install Bash Completion (Inline Eval)

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/plugins/completion.mdx

This method evaluates the completion script inline in your ~/.bashrc file. This may incur a shell-startup cost.

```bash
# in ~/.bashrc
eval "$(my-cli completion bash)"
```

--------------------------------

### Quick Start: Using Effect Schemas with Crust

Source: https://github.com/chenxin-yan/crust/blob/main/packages/validate/README.md

Wrap Effect schemas with Schema.standardSchemaV1 before passing them to arg() or flag(). Crust uses the wrapper's validate function at runtime. This example demonstrates setting up a Crust instance with port and verbose arguments.

```typescript
import { Crust } from "@crustjs/core";
import { arg, commandValidator, flag } from "@crustjs/validate";
import * as Schema from "effect/Schema";

new Crust("serve")
	.args([
		arg("port", Schema.standardSchemaV1(Schema.NumberFromString), {
			description: "Port to listen on",
		}),
	])
	.flags({
		verbose: flag(Schema.standardSchemaV1(Schema.UndefinedOr(Schema.Boolean)), {
			type: "boolean",
			short: "v",
			description: "Enable verbose logging",
		}),
	})
	.run(
		commandValidator(({ args, flags }) => {
			/* … */
		}),
	);

```

--------------------------------

### Quick Example: Creating and Using a Typed Store

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/store.mdx

Demonstrates how to create a typed store for configuration with default values. Shows reading, writing, updating, patching, and resetting the store's state. Types are inferred automatically from the field definitions.

```ts
import { createStore, configDir } from "@crustjs/store";

const store = createStore({
  dirPath: configDir("my-cli"),
  fields: {
    theme: { type: "string", default: "light" },
    fontSize: { type: "number", default: 14 },
    verbose: { type: "boolean", default: false },
  },
});

// Read state (returns defaults when no persisted file exists)
const state = await store.read();
// → { theme: "light", fontSize: 14, verbose: false }

// Write a full state object
await store.write({ theme: "dark", fontSize: 16, verbose: true });

// Update with a function
await store.update((current) => ({ ...current, verbose: false }));

// Patch only specific keys
await store.patch({ theme: "solarized" });

// Reset to defaults (removes persisted file)
await store.reset();
```

--------------------------------

### Mimic Global Install with Packed Tarball

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/development.mdx

Install a packed tarball globally to simulate a global command installation. This verifies that the CLI can be installed and run globally from a published package.

```sh
bun add -g "$TARBALL"
my-cli --help
```

--------------------------------

### Quick Scaffold and Run Steps Example

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/create.mdx

Scaffold a project from a template directory, interpolate context variables, and then run a series of post-scaffold automation steps.

```ts
import { scaffold, runSteps } from "@crustjs/create";

// 1. Copy and interpolate the template
const result = await scaffold({
  template: "./templates/base",
  dest: "./my-project",
  context: { name: "my-app", description: "A cool CLI" },
});

console.log("Created files:", result.files);

// 2. Run post-scaffold automation
await runSteps(
  [{ type: "install" }, { type: "git-init", commit: "Initial commit" }, { type: "open-editor" }],
  "./my-project",
);
```

--------------------------------

### Install @crustjs/validate

Source: https://github.com/chenxin-yan/crust/blob/main/packages/validate/README.md

Install the validation package. Optionally install a schema library like Zod or Effect if you plan to use them.

```sh
bun add @crustjs/validate
# Optional, depending on your schema library:
bun add zod      # any Zod v4 schema is a Standard Schema natively
bun add effect   # wrap with `Schema.standardSchemaV1(...)`
```

--------------------------------

### Quick Start: Creating and Using a Store

Source: https://github.com/chenxin-yan/crust/blob/main/packages/store/README.md

Demonstrates creating a typed store, reading its state, writing a full state object, updating with a function, patching specific keys, and resetting to defaults. Types are inferred from the fields definition.

```typescript
import { createStore, configDir } from "@crustjs/store";

const store = createStore({
	dirPath: configDir("my-cli"),
	fields: {
		theme: { type: "string", default: "light" },
		fontSize: { type: "number", default: 14 },
		verbose: { type: "boolean", default: false },
	},
});

// Read state (returns defaults when no persisted file exists)
const state = await store.read();
// → { theme: "light", fontSize: 14, verbose: false }

// Write a full state object
await store.write({ theme: "dark", fontSize: 16, verbose: true });

// Update with a function
await store.update((current) => ({ ...current, verbose: false }));

// Patch only specific keys
await store.patch({ theme: "solarized" });

// Reset to defaults (removes persisted file)
await store.reset();
```

--------------------------------

### Example CLI Usage with '--' Separator

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/arguments.mdx

Shows how flags and arguments passed after '--' are treated as raw arguments and not processed by Crust.

```sh
my-cli build -- --some-flag --passed-through
# rawArgs: ["--some-flag", "--passed-through"]
```

--------------------------------

### Install Packaged Artifacts into Throwaway Project

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/development.mdx

Install both the root and platform-specific tarballs into a throwaway project to mimic a complete installation of your CLI, including platform-specific binaries.

```sh
mkdir -p ../my-cli-smoke
cd ../my-cli-smoke
```

--------------------------------

### SetupContext Interface

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/api/types.mdx

Provides context to the plugin's setup function, including the command-line arguments, the root command node, and the plugin's state.

```typescript
interface SetupContext {
  readonly argv: readonly string[];
  readonly rootCommand: CommandNode;
  readonly state: PluginState;
}
```

--------------------------------

### Bun Runtime Package Configuration

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/build.mdx

Configure your package.json to build a CLI binary specifically for the Bun runtime. This requires the end-user to have Bun installed.

```json
{
  "name": "my-cli",
  "files": ["dist"],
  "bin": {
    "my-cli": "dist/cli.js"
  },
  "scripts": {
    "build": "bun build src/cli.ts --target bun --outfile dist/cli.js",
    "prepack": "bun run build"
  }
}
```

--------------------------------

### Example CLI Usage with Variadic Arguments

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/arguments.mdx

Shows how to pass multiple file names as variadic arguments to the 'copy' command, after the required destination.

```sh
my-cli /output file1.txt file2.txt file3.txt
```

--------------------------------

### Usage Examples for Crust CLI

Source: https://github.com/chenxin-yan/crust/blob/main/packages/create-crust/templates/minimal/README.md

Demonstrates how to run the generated Crust CLI application with different arguments. Replace `{{name}}` with your project's actual name.

```sh
# Run the CLI
{{name}} world
{{name}} --greet Hey world
```

--------------------------------

### Initialize Crust with Help Plugin

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/plugins/help.mdx

Import and use the helpPlugin to add automatic --help flags to your CLI commands.

```typescript
import { Crust } from "@crustjs/core";
import { helpPlugin } from "@crustjs/plugins";

const main = new Crust("my-cli").use(helpPlugin()).run(() => {
  /* ... */
});

await main.execute();
```

--------------------------------

### Test Crust CLI with Arguments and Flags

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/quick-start.mdx

Demonstrates how to invoke the CLI with positional arguments, flags, and view the help message. Ensure you are in the project directory.

```sh
# Pass an argument
bun run src/cli.ts Alice

# Use a flag
bun run src/cli.ts Alice --greet Hey

# View the help
bun run src/cli.ts --help
```

--------------------------------

### String Flags with Choices Example

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/api/types.mdx

Example demonstrating string flags with 'choices' for single and multi-value types.

```typescript
flags: {
  target: { type: "string", choices: ["browser", "bun", "node"] },
  suites: { type: "string", multiple: true, choices: ["unit", "integration"] },
}
```

--------------------------------

### Run Crust CLI in Development Mode

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/quick-start.mdx

After scaffolding, navigate to the project directory and run the CLI in development mode using 'bun run dev'. This will display a 'Hello, world!' message.

```sh
cd my-cli
bun run dev
```

--------------------------------

### Configure for Global Bun CLI

Source: https://github.com/chenxin-yan/crust/blob/main/packages/plugins/README.md

Set the package manager to 'bun' and install scope to 'global' for a globally installed Bun CLI.

```typescript
updateNotifierPlugin({
	packageName: "my-cli",
	currentVersion: "1.0.0",
	packageManager: "bun",
	installScope: "global",
});
```

--------------------------------

### Install @crustjs/validate

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/validate.mdx

Install the @crustjs/validate package using bun. This command adds the necessary library to your project for CLI argument and flag validation.

```sh
bun add @crustjs/validate
```

--------------------------------

### Install Bash Completion (Per-user)

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/plugins/completion.mdx

This command installs the bash completion script for per-user lazy loading. Ensure you have bash-completion version 2.0 or higher.

```bash
# Per-user (lazy-loaded by bash-completion ≥ 2.0)
mkdir -p ~/.local/share/bash-completion/completions
my-cli completion bash > ~/.local/share/bash-completion/completions/my-cli
```

--------------------------------

### CrustPlugin Interface

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/api/types.mdx

Defines the structure for a Crust plugin, including optional name, setup function, and middleware. The setup function is called during plugin initialization.

```typescript
interface CrustPlugin {
  name?: string;
  setup?: (context: SetupContext, actions: SetupActions) => void | Promise<void>;
  middleware?: PluginMiddleware;
}
```

--------------------------------

### Nested Subcommands Example

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/subcommands.mdx

Subcommands can be nested arbitrarily deep to create complex command structures. This example shows creating resources like components and plugins.

```typescript
const main = new Crust("my-cli").command("create", (create) =>
  create
    .meta({ description: "Create resources" })
    .command("component", (cmd) =>
      cmd
        .meta({ description: "Create a component" })
        .args([{ name: "name", type: "string", required: true }])
        .run(({ args }) => {
          console.log(`Creating component: ${args.name}`);
        }),
    )
    .command("plugin", (cmd) =>
      cmd
        .meta({ description: "Create a plugin" })
        .args([{ name: "name", type: "string", required: true }])
        .run(({ args }) => {
          console.log(`Creating plugin: ${args.name}`);
        }),
    ),
);
```

--------------------------------

### Install Zsh Completion (Per-user)

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/plugins/completion.mdx

This command installs the zsh completion script into a custom directory. You need to configure your ~/.zshrc to include this directory in your fpath and run compinit.

```bash
# Per-user — drop into a directory on $fpath
mkdir -p ~/.zsh/completions
my-cli completion zsh > ~/.zsh/completions/_my-cli
```

--------------------------------

### Custom Type Parsing Example

Source: https://github.com/chenxin-yan/crust/blob/main/packages/core/README.md

Example of defining a custom parser for a flag. This snippet shows how to parse a string input into a number for the 'port' flag, with a default value.

```ts
flags: {
  port: { type: "string", parse: (s) => Number(s), default: "3000" },
}
// flags.port: number
```

--------------------------------

### Create and Run a New Crust CLI Project

Source: https://github.com/chenxin-yan/crust/blob/main/README.md

Use this command to scaffold a new CLI project with Crust. Navigate into the project directory and run the development server.

```shell
bun create crust my-cli
cd my-cli
bun run dev
```

--------------------------------

### String Argument Definition Example

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/api/types.mdx

An example of defining a string argument, including its name, type, description, default value, and optional properties like 'required', 'variadic', and 'choices'.

```typescript
interface StringArgDef {
  name: string; // Argument name
  type: "string"; // Type discriminant
  description?: string; // Help text
  default?: string; // Default value (type-safe)
  required?: true; // Error if missing
  variadic?: true; // Collect remaining into array
  choices?: readonly string[]; // Static enum of valid values (string only)
}
```

--------------------------------

### Plugin Setup Phase: Injecting a Subcommand

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/plugins.mdx

Defines a custom plugin that injects a 'status' subcommand into the root command during the setup phase. User-defined subcommands with the same name will take precedence.

```typescript
import { createCommandNode } from "@crustjs/core";

const myPlugin: CrustPlugin = {
  name: "my-plugin",
  setup(context, actions) {
    const statusNode = createCommandNode("status");
    statusNode.meta.description = "Show status";
    statusNode.run = () => {
      console.log("Status: OK");
    };

    // Inject "status" as a subcommand of the root command
    actions.addSubCommand(context.rootCommand, "status", statusNode);
  },
};

```

--------------------------------

### Plugin Setup Phase: Adding a Flag

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/plugins.mdx

Defines a custom plugin that adds a 'debug' boolean flag to the root command during the setup phase. This is useful for injecting configuration options.

```typescript
const myPlugin: CrustPlugin = {
  name: "my-plugin",
  setup(context, actions) {
    // context.rootCommand — the root command node
    // context.argv — raw argv
    // context.state — plugin state store

    // Inject a flag into the root command
    actions.addFlag(context.rootCommand, "debug", {
      type: "boolean",
      description: "Enable debug mode",
    });
  },
};

```

--------------------------------

### Programmatic Skill Generation and Installation

Source: https://github.com/chenxin-yan/crust/blob/main/packages/skills/README.md

Control skill installation directly by calling `generateSkill` from your handler. This function is idempotent and safe to run on every invocation, returning `up-to-date` for targets that already match the current version.

```typescript
import { Crust } from "@crustjs/core";
import { generateSkill } from "@crustjs/skills";

export const app = new Crust("my-cli").meta({ description: "My CLI" }).run(async (ctx) => {
	// Defaults to universal + agents detected on PATH. Idempotent: targets
	// that already match the current version are returned as `up-to-date`.
	const result = await generateSkill({
		command: ctx.command,
		meta: {
			name: ctx.command.meta.name,
			description: ctx.command.meta.description ?? "",
			version: "1.0.0",
		},
		scope: "global",
	});

	const changed = result.agents.filter((a) => a.status !== "up-to-date");
	if (changed.length > 0) {
		console.log(`Installed or updated skills for ${changed.length} target(s).`);
	}
});

if (import.meta.main) {
	await app.execute();
}
```

--------------------------------

### Install Core Framework and CLI Tooling (Bun Runtime Package)

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/installation.mdx

Use this command to add the core framework and plugins as runtime dependencies when distributing as a Bun runtime package. CLI tooling and types are added as dev dependencies.

```sh
# Core framework and plugins are runtime dependencies
bun add @crustjs/core @crustjs/plugins

# CLI tooling + types are dev dependencies
bun add -d @crustjs/crust @types/bun typescript
```

--------------------------------

### Interactive Skill Management Command

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/skills.mdx

Execute the 'skill' subcommand to interactively manage agent skill installations. This command presents a multiselect prompt for toggling agent installations, including a universal option and individually detected agents.

```sh
my-cli skill

```

--------------------------------

### Build for All Platforms (Default Output Structure)

Source: https://github.com/chenxin-yan/crust/blob/main/packages/crust/README.md

Illustrates the default output structure when building for all platforms without specifying a target. Includes a shell resolver script and platform-specific binaries.

```sh
dist/
  cli                               # Shell resolver (entry point for npm bin)
  cli.cmd                           # Windows batch resolver
  my-cli-bun-linux-x64-baseline     # Linux x64 binary
  my-cli-bun-linux-arm64            # Linux ARM64 binary
  my-cli-bun-darwin-x64             # macOS Intel binary
  my-cli-bun-darwin-arm64           # macOS Apple Silicon binary
  my-cli-bun-windows-x64-baseline.exe  # Windows x64 binary
  my-cli-bun-windows-arm64.exe      # Windows ARM64 binary
```

--------------------------------

### Build Project

Source: https://github.com/chenxin-yan/crust/blob/main/AGENTS.md

Builds all packages in the project using Bun.

```sh
bun run build            # build all packages
```

--------------------------------

### Create a Configured Style Instance

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/style.mdx

Demonstrates creating a custom style instance with specific options.

```typescript
import { createStyle } from "@crustjs/style";

const customStyle = createStyle({
  colorMode: "always", // or "auto", "never"
  // other options...
});
```

--------------------------------

### isGitInstalled

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/create.mdx

Checks if Git is installed and available on the system's PATH.

```APIDOC
## `isGitInstalled()`

### Description
Check whether `git` is available on the system PATH.

### Returns
- **boolean** - `true` if Git is installed, `false` otherwise.
```

--------------------------------

### Initialize Crust CLI with Completion Plugin

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/plugins/completion.mdx

This snippet shows how to integrate the completion plugin into your Crust CLI application. Ensure you have the necessary package.json version information.

```typescript
import { Crust } from "@crustjs/core";
import { completionPlugin } from "@crustjs/plugins";
import pkg from "../package.json";

const main = new Crust("my-cli")
  .meta({ description: "My CLI" })
  .use(completionPlugin({ version: pkg.version }))
  .command("build", (cmd) =>
    cmd
      .meta({ description: "Build artifact" })
      .flags({
        target: { type: "string", choices: ["browser", "bun", "node"] },
      })
      .run(() => {}),
  )
  .run(() => {});

await main.execute();
```

--------------------------------

### Nested Subcommands CLI Usage

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/subcommands.mdx

Example of how to invoke nested subcommands from the command line.

```shell
my-cli create component Button
my-cli create plugin auth
```

--------------------------------

### String Type Example

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/types.mdx

Defines a required string flag. The inferred TypeScript type is `string`.

```typescript
.flags({
  name: { type: "string", required: true },
})
// flags.name: string
```

--------------------------------

### .prepareCommandTree(options?)

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/api/crust.mdx

Builds a frozen and validated copy of the command tree after plugin setup hooks, without executing middleware or command handlers. This is useful for documentation generation tools.

```APIDOC
## .prepareCommandTree(options?)

### Description

Builds a **frozen, validated copy** of the command tree after plugin `setup()` hooks, without running middleware or command handlers. The original builder is **not** mutated. Use this for documentation generators such as [`@crustjs/man`](/docs/modules/man).

### Method Signature

```ts
prepareCommandTree(options?: {
  argv?: readonly string[];
}): Promise<{ root: CommandNode; warnings: readonly string[] }>
```

### Options

| Option | Type                | Default |
| ------ | ------------------- | ------- |
| `argv` | `readonly string[]` | `[]`    |

**Description:** Synthetic argv passed to plugin `setup()` (same as `.execute()`).

### Throws

On the same validation failures as build-time tree validation (e.g. invalid flag definitions). Unlike `.execute()`, errors are thrown instead of printing to stderr.
```

--------------------------------

### Build with Production Environment File

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/environment.mdx

Execute the 'crust build' command using a specific production environment file. This command loads environment variables from '.env.production' for the build process.

```bash
crust build --env-file .env.production
```

--------------------------------

### Get Global Color Mode Override

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/modules/style.mdx

Read the current runtime color override setting.

```typescript
import { getGlobalColorMode } from "@crustjs/style";

const currentMode = getGlobalColorMode(); // "always", "auto", or "never"
```

--------------------------------

### Define a Basic Command

Source: https://github.com/chenxin-yan/crust/blob/main/apps/docs/content/docs/guide/commands.mdx

Use the `Crust` class to create a new command and set its description using `.meta()`.

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

const serve = new Crust("serve").meta({ description: "Start the development server" }).run(() => {
  console.log("Server started!");
});
```