Skip to main content

​
System Requirements

Before installing Bunli, ensure you have Bun installed on your system:
Bunli requires Bun 1.0.0 or higher. The framework is specifically designed to leverage Bun’s unique features like the Bun Shell, fast startup times, and native TypeScript support.

​
Installing Bun

If you don’t have Bun installed yet: 
curl -fsSL https://bun.sh/install | bash
Verify your Bun installation: 
bun --version
You should see output like: 
1.3.10

​
Installing Bunli CLI

There are two ways to install the Bunli CLI: globally or locally per project. Install Bunli globally to use it across all your projects: 
bun add -g bunli

​
Local Installation

Install Bunli as a dev dependency in your project: 
bun add -d bunli
Global installation allows you to use the bunli command anywhere. Local installation is useful when you want to lock specific versions per project.

​
Verifying Installation

Check that Bunli is installed correctly: 
bunli --version
You should see output like: 
0.8.0
View available commands: 
bunli --help
Expected output: 
The Bunli CLI toolchain for developing, building, and distributing CLIs

Usage:
  bunli [command] [options]

Commands:
  build      Compile CLI to standalone binary
  dev        Start development mode with hot reload
  generate   Generate TypeScript definitions from commands
  init       Initialize a new Bunli project
  test       Run tests with coverage
  release    Build and publish CLI to npm

Options:
  -h, --help     Display help
  -v, --version  Display version

​
Installing Core Framework

If you’re setting up a project manually (not using create-bunli), you’ll need to install the core framework: 
bun add @bunli/core
For TypeScript support, also install Zod: 
bun add zod

​
Troubleshooting

​
Command Not Found

If you get a “command not found” error after global installation:
  1. Check your PATH: Make sure Bun’s global bin directory is in your PATH
  2. Restart your terminal: Close and reopen your terminal window
  3. Verify installation location: 
    which bunli

​
Permission Errors

If you encounter permission errors during global installation: On macOS/Linux: 
sudo bun add -g bunli
Or use a version manager like asdf to avoid permission issues.

​
Version Mismatch

If you experience issues with version compatibility:
  1. Update Bun: 
    bun upgrade
  2. Clear Bun cache: 
    rm -rf ~/.bun/install/cache
  3. Reinstall Bunli: 
    bun remove -g bunli
bun add -g bunli

​
Module Resolution Issues

If you see module resolution errors:
  1. Ensure you’re using ES modules: Add "type": "module" to your package.json
  2. Use .js extensions: Import local files with .js extensions, even in TypeScript files: 
    import command from './commands/hello.js'

​
Installation Hangs or Fails

If installation hangs or fails:
  1. Check internet connection: Ensure you have a stable connection
  2. Try with verbose logging: 
    bun add -g bunli --verbose
  3. Check disk space: Ensure you have sufficient disk space
  4. Try alternative registry: 
    bun add -g bunli --registry https://registry.npmjs.org

​
Next Steps

Now that you have Bunli installed, you’re ready to create your first CLI:

Quick Start

Get up and running with create-bunli in under 2 minutes

Your First CLI

Build a complete CLI from scratch with step-by-step guidance

Build docs developers (and LLMs) love

Get started for freeTalk to us