create-bunli

Quick Start

Features

• 🚀 Fast scaffolding - Get started in seconds
• 📦 Multiple templates - Choose from basic, advanced, or monorepo setups
• 🔧 TypeScript ready - Full TypeScript support out of the box
• 🧪 Testing included - Comes with @bunli/test for CLI testing
• 🎨 Best practices - Follows Bunli conventions and patterns
• 🌐 External templates - Use any GitHub repository as a template
• 💾 Offline support - Works offline with cached templates

Usage

Interactive Mode

Run without arguments for a guided experience:

bunx create-bunli

You'll be prompted for:

• Project name
• Directory location
• Template selection
• Package manager preference

Command Line Mode

Specify options directly:

bunx create-bunli my-cli --template advanced --package-manager pnpm

Options

Built-in Templates

Basic Template

Perfect for simple CLI tools with a single command.

my-cli/
├── src/
│   ├── index.ts         # CLI entry point
│   └── commands/
│       └── hello.ts     # Example command
├── test/
│   └── hello.test.ts    # Example test
├── bunli.config.ts      # CLI configuration
├── package.json
├── tsconfig.json
└── README.md

Features:

• Single command setup
• TypeScript configuration
• Test setup with @bunli/test
• Build script using bunli
• Essential dependencies only

bunx create-bunli my-cli --template basic

Advanced Template

For complex CLIs with multiple commands and features.

my-cli/
├── src/
│   ├── index.ts         # CLI entry point
│   ├── commands/        # Command implementations
│   │   ├── index.ts     # Command manifest
│   │   ├── init.ts      # Initialize configuration
│   │   ├── validate.ts  # File validation
│   │   ├── serve.ts     # Development server
│   │   └── config.ts    # Configuration management
│   └── utils/          # Utility functions
│       ├── config.ts
│       ├── validator.ts
│       └── glob.ts
├── test/
├── bunli.config.ts
├── package.json
├── tsconfig.json
└── README.md

Features:

• Multiple commands with subcommands
• Configuration management system
• File validation with rules
• Built-in development server
• License selection during setup
• Rich utility functions

bunx create-bunli my-cli --template advanced

Monorepo Template

For large projects with multiple packages.

my-cli/
├── packages/
│   ├── cli/            # Main CLI package
│   │   ├── src/
│   │   └── package.json
│   ├── core/           # Core functionality
│   │   ├── src/
│   │   └── package.json
│   └── utils/          # Shared utilities
│       ├── src/
│       └── package.json
├── turbo.json          # Turborepo config
├── package.json        # Root package.json
├── tsconfig.json       # Root TypeScript config
├── .changeset/         # Changeset config
└── README.md

Features:

• Turborepo configuration
• Multiple packages with workspace setup
• Shared dependencies management
• Changeset support for versioning
• Parallel builds and testing
• Optimized for scalability

bunx create-bunli my-cli --template monorepo

External Templates

Use any GitHub repository as a template:

GitHub Templates

# Short format
bunx create-bunli my-cli --template username/repo

# Full GitHub format
bunx create-bunli my-cli --template github:username/repo

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

NPM Templates

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

Local Templates

bunx create-bunli my-cli --template ./path/to/template
bunx create-bunli my-cli --template file:./path/to/template

Creating Custom Templates

Build your own templates with variable substitution and custom logic.

Template Structure

A template is any directory with files that will be copied and processed. Add a template.json for advanced features:

{
  "name": "my-template",
  "description": "My custom Bunli template",
  "variables": [
    {
      "name": "name",
      "message": "Project name",
      "type": "string",
      "default": "my-project"
    },
    {
      "name": "license",
      "message": "License",
      "type": "select",
      "choices": [
        { "label": "MIT", "value": "MIT" },
        { "label": "Apache 2.0", "value": "Apache-2.0" },
        { "label": "GPL 3.0", "value": "GPL-3.0" }
      ]
    }
  ],
  "files": {
    "include": ["**/*.ts", "**/*.json"],
    "exclude": ["node_modules", ".git"]
  },
  "hooks": {
    "postInstall": ["npm run build"]
  }
}

Variable Substitution

Templates support multiple variable formats:

Available Variables:

These are the variables passed to the template engine from create-project.ts:

File Name Variables

Use variables in file names:

templates/
└── my-template/
    ├── __projectName__.config.js  # Becomes my-app.config.js
    └── src/
        └── __projectName__.ts     # Becomes my-app.ts

Variable Types

{
  "name": "apiKey",
  "message": "API Key",
  "type": "string",
  "default": ""
}

{
  "name": "useTypeScript",
  "message": "Use TypeScript?",
  "type": "boolean",
  "default": true
}

{
  "name": "port",
  "message": "Default port",
  "type": "number",
  "default": 3000
}

{
  "name": "framework",
  "message": "Choose framework",
  "type": "select",
  "choices": [
    { "label": "Express", "value": "express" },
    { "label": "Fastify", "value": "fastify" }
  ]
}

Advanced Usage

Programmatic API

Use create-bunli programmatically:

import { createProject } from "create-bunli";

await createProject({
  name: "my-cli",
  template: "advanced",
  dir: "./projects/my-cli",
  packageManager: "bun",
  install: true,
  git: true,
  offline: false,
});

Offline Mode

Work offline with cached templates:

# Use cached template if available
bunx create-bunli my-cli --offline

# Force offline mode (fail if not cached)
GIGET_FORCE_OFFLINE=1 bunx create-bunli my-cli

Custom Directory

Create project in a specific location:

# Create in current directory
bunx create-bunli . --template advanced

# Create in custom path
bunx create-bunli my-cli --dir ~/projects/my-cli

Examples

bunx create-bunli todo-cli
cd todo-cli
bunli dev

bunx create-bunli weather-cli \
  --template advanced \
  --package-manager pnpm \
  --dir ~/tools/weather-cli \
  --git \
  --install

bunx create-bunli my-app \
  --template pvtnbr/bunli-starter \
  --package-manager npm

bunx create-bunli api-cli \
  --template monorepo \
  --no-git \
  --no-install

Troubleshooting

Template not found

If you get a "template not found" error:

• Check the template name spelling
• For GitHub templates, ensure the repository exists and is public
• For local templates, verify the path exists
• Try with --offline if you've used the template before

Installation fails

If dependency installation fails:

• Check your internet connection
• Ensure the package manager is installed
• Try with --no-install and install manually
• Clear package manager cache

Permission errors

If you get permission errors:

• Ensure write access to the target directory
• Try a different directory
• Check available disk space
• Run with appropriate permissions

Variable substitution not working

If template variables aren't replaced:

• Check variable syntax (use {{variable}} format)
• Ensure variables are defined in template.json
• Verify file is not in excluded patterns
• Check file encoding (UTF-8 required)

Next Steps

• Learn about Commands to build your CLI
• Explore Testing to ensure reliability
• Read about Distribution to share your CLI