Bunli
API Reference

createCLI

Create a new CLI instance with configuration

createCLI

Creates a new CLI instance with automatic configuration loading from bunli.config.ts.

Syntax

function createCLI(configOverride?: Partial<BunliConfig>): Promise<CLI>

Parameters

configOverride (optional)

Override specific configuration values. If not provided, createCLI automatically loads configuration from bunli.config.ts.

interface BunliConfig {
  name?: string
  version?: string
  description?: string
  commands?: {
    entry?: string
    directory?: string
  }
  plugins?: PluginConfig[]
  build?: BuildConfig
  dev?: DevConfig
  test?: TestConfig
  // ... other config options
}

New in Bunli 0.4.0: Configuration is automatically loaded from bunli.config.ts. You only need to provide overrides for runtime-specific settings like plugins with custom options.

Returns

A CLI instance with the following methods:

interface CLI {
  command(cmd: Command): void
  init(): Promise<void>
  run(argv?: string[]): Promise<void>
}

Examples

With automatic config loading from bunli.config.ts:

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

const cli = await createCLI()

// Add commands
cli.command({
  name: 'hello',
  description: 'Say hello',
  handler: async () => {
    console.log('Hello, World!')
  }
})

await cli.run()
// bunli.config.ts
import { defineConfig } from '@bunli/core'

export default defineConfig({
  name: 'my-cli',
  version: '1.0.0',
  description: 'My awesome CLI tool'
})

With Explicit Registration

// cli.ts
import { createCLI } from '@bunli/core'
import build from './commands/build.js'
import test from './commands/test.js'
import deploy from './commands/deploy.js'

const cli = await createCLI()

cli.command(build)
cli.command(test)
cli.command(deploy)

await cli.run()
// bunli.config.ts
import { defineConfig } from '@bunli/core'

export default defineConfig({
  name: 'my-cli',
  version: '1.0.0',
  description: 'My CLI with explicit command registration',
  commands: {
    entry: './cli.ts',
    directory: './commands'
  }
})

With Runtime Plugin Configuration

For plugins that need runtime-specific options:

// cli.ts
import { createCLI } from '@bunli/core'
import { configMergerPlugin } from '@bunli/plugin-config'
import { aiAgentPlugin } from '@bunli/plugin-ai-detect'

const cli = await createCLI({
  plugins: [
    configMergerPlugin({ sources: ['.myrc.json'] }),
    aiAgentPlugin({ verbose: true })
  ] as const
})

await cli.run()
// bunli.config.ts
import { defineConfig } from '@bunli/core'

export default defineConfig({
  name: 'my-cli',
  version: '1.0.0',
  description: 'My CLI with plugins',
  // Plugins configured in cli.ts for runtime options
  commands: {
    directory: './commands'
  }
})

Legacy: Explicit Configuration

You can still provide full configuration explicitly:

import { createCLI } from '@bunli/core'

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

await cli.run()

Deprecated: Explicit configuration is still supported but not recommended. Use bunli.config.ts for better maintainability and consistency with the Bunli CLI toolchain.

CLI Methods

command(cmd)

Add a command to the CLI.

cli.command({
  name: 'build',
  description: 'Build the project',
  handler: async () => {
    // Command implementation
  }
})

init()

Initialize the CLI.

await cli.init()

run(argv?)

Run the CLI with the given arguments. If no arguments are provided, uses process.argv.slice(2).

// Use process arguments
await cli.run()

// Use custom arguments
await cli.run(['build', '--watch'])

Automatic Features

When you create a CLI with createCLI, you get:

  • Automatic help generation - --help flag shows available commands
  • Version display - --version flag shows CLI version
  • Command routing - Automatically routes to the correct command
  • Error handling - Friendly error messages for unknown commands
  • Nested command support - Commands can have subcommands
  • Alias support - Commands can have shortcuts
  • Plugin system - Extend functionality with type-safe plugins
  • Type-safe context - Plugin stores are fully typed in commands

Help Output

Running with --help shows:

$ my-cli --help
my-cli v1.0.0
My awesome CLI tool

Commands:
  hello                Say hello
  build                Build the project
  test                 Run tests

Error Handling

Unknown commands show helpful messages:

$ my-cli unknown
Unknown command: unknown

The CLI automatically handles help flags at any level. For example, my-cli build --help shows help for the build command specifically.

See Also

API Reference

Complete API documentation for Bunli

defineCommand

Define type-safe commands with automatic inference

On this page

createCLISyntaxParametersconfigOverride (optional)ReturnsExamplesBasic Usage (Recommended)With Explicit RegistrationWith Runtime Plugin ConfigurationLegacy: Explicit ConfigurationCLI Methodscommand(cmd)init()run(argv?)Automatic FeaturesHelp OutputError HandlingSee Also