Getting Started

Get up and running with Bunli in just a few minutes. This guide will walk you through creating your first CLI application.

Prerequisites

Bunli requires Bun 1.0 or later. Install it from bun.sh

# Check your Bun version
bun --version

Quick Start

Create a new project

Use create-bunli to scaffold a new CLI project:

bunx create-bunli my-cli
cd my-cli

You'll be prompted for:

Project name: Validated to contain only lowercase letters, numbers, and hyphens
Template: Choose from basic (default), advanced, or monorepo
Package manager: Select your preferred package manager (bun, npm, yarn, pnpm)

The tool will automatically:

✅ Create the project structure
✅ Initialize a git repository
✅ Install dependencies
✅ Set up TypeScript and testing

Explore the project structure

Your new CLI project includes:

my-cli/
├── src/
│   ├── index.ts       # CLI entry point
│   └── commands/      # Command definitions
├── bunli.config.ts    # Configuration
├── package.json
├── tsconfig.json
└── README.md

Run your CLI

In development mode with hot reload:

bunli dev

Or run directly with Bun:

bun run src/index.ts --help

Add your first command

Create a new command in src/commands/greet.ts:

import { defineCommand, option } from '@bunli/core'
import { z } from 'zod'

export default defineCommand({
  name: 'greet',
  description: 'Greet someone',
  options: {
    name: option(
      z.string().min(1),
      { description: 'Name to greet', short: 'n' }
    ),
    excited: option(
      z.coerce.boolean().default(false),
      { description: 'Add excitement', short: 'e' }
    )
  },
  handler: async ({ flags }) => {
    const greeting = `Hello, ${flags.name}${flags.excited ? '!' : '.'}`
    console.log(greeting)
  }
})

Test your command

# Run in development
bunli dev greet --name World --excited
# Output: Hello, World!

# Run tests
bunli test

Build for production

Create optimized binaries for distribution:

# Build for current platform
bunli build

# Build for all platforms
bunli build --all

Project Templates

Create-bunli offers several templates to match your needs:

Simple single-command CLI:

bunx create-bunli my-cli --template basic

Perfect for:

Learning Bunli
Simple scripts
Single-purpose tools

Includes:

TypeScript setup
Example command with tests
Build configuration

Multi-command CLI with all features:

bunx create-bunli my-cli --template advanced

Includes:

Multiple commands (init, validate, serve, config)
Configuration management
File validation system
Development server
Interactive license selection

Perfect for:

Production CLIs
Developer tools
Complex applications

Workspace setup for larger projects:

bunx create-bunli my-cli --template monorepo

Features:

Turborepo configuration
Multiple packages (cli, core, utils)
Changeset support
Parallel builds

Perfect for:

Large teams
Multi-package CLIs
Scalable architectures

External Templates

Use any GitHub repository as a template:

# GitHub repository
bunx create-bunli my-cli --template username/repo

# Specific branch
bunx create-bunli my-cli --template username/repo#branch

# NPM package
bunx create-bunli my-cli --template npm:template-package

Manual Setup

If you prefer to set up manually:

Install Bunli

bun add bunli @bunli/core

Create your CLI entry point

// src/index.ts
import { createCLI } from '@bunli/core'

const cli = createCLI({
  name: 'my-cli',
  version: '1.0.0',
  description: 'My awesome CLI'
})

cli.command({
  name: 'hello',
  description: 'Say hello',
  handler: async () => {
    console.log('Hello from Bunli!')
  }
})

cli.run()

Add to package.json

{
  "name": "my-cli",
  "bin": {
    "my-cli": "./src/index.ts"
  },
  "scripts": {
    "dev": "bunli dev",
    "build": "bunli build",
    "test": "bun test"
  }
}

Create bunli.config.ts

import { defineConfig } from 'bunli'

export default defineConfig({
  name: 'my-cli',
  commands: {
    dir: './src/commands'
  }
})

What's Next?

Now that you have a working CLI:

Learn about Commands - The building blocks of your CLI
Explore Type Inference - Leverage TypeScript's power
Add Validation - Ensure correct input
Write Tests - Keep your CLI reliable
Build & Distribute - Share your CLI with the world

Join our community on GitHub Discussions for help and to share what you're building!

Getting Started

On this page