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?: {
    manifest?: 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
  load(manifest: CommandManifest): Promise<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 Command Manifest

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

const cli = await createCLI()

await cli.load({
  build: () => import('./commands/build'),
  test: () => import('./commands/test'),
  deploy: () => import('./commands/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 lazy-loaded commands',
  commands: {
    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
  }
})

load(manifest)

Load commands from a manifest for lazy loading.

const manifest = {
  build: () => import('./commands/build.js'),
  test: () => import('./commands/test.js'),
  deploy: () => import('./commands/deploy.js')
}

await cli.load(manifest)

init()

Initialize the CLI. This loads commands from the manifest if configured.

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 Command ManifestWith Runtime Plugin ConfigurationLegacy: Explicit ConfigurationCLI Methodscommand(cmd)load(manifest)init()run(argv?)Automatic FeaturesHelp OutputError HandlingSee Also