Quick Start

Scaffold a New Project

The fastest way to start is with create-crust:

bun create crust my-cli

This runs an interactive setup that prompts for your project directory, template style, and distribution mode, then scaffolds a ready-to-run project.

Create the project

bun create crust my-cli

Answer the prompts (or press Enter to accept defaults) for template style and distribution mode.

Run in development mode

cd my-cli
bun run dev

You should see:

Hello, world!

Try it out

# 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

Distribution

How you ship depends on the distribution mode you selected during scaffolding:

Recommended for most CLIs: distribute your tool as prebuilt binaries.

Raw binaries (default):

bun run build

This runs crust build, which compiles your CLI to standalone executables for all platforms using bun build --compile.

If you need public build-time constants, crust build can use Bun's cwd env by default or take explicit --env-file inputs. See Environment Variables for the full env model.

Per-OS npm packages (optional):

To publish via npm with automatic platform detection:

# Stage npm packages (creates dist/npm/ with per-platform packages)
bun run package

# Publish all packages in manifest order
bun run publish

This creates a root package with optional dependencies on platform-specific packages. Users install normally with bun add -g my-cli and npm automatically installs only the binary for their platform.

See Per-OS Distribution for details.

If you selected Bun runtime package mode, build and run the JS distribution entry:

bun run build
bun run dist/cli.js --help

In this mode, @crustjs/core and @crustjs/plugins stay in dependencies and your published entrypoint is dist/cli.js.

See Building & Distribution and Installation for full packaging details.

Next Steps

Installation — manual setup and composable modules
Commands — learn how the Crust builder works
Arguments — positional arguments in depth
Flags — named flags and options
Plugins — add help, version, and more