The Command Line Interface (CLI) is the primary entry point for the Bun toolkit. It serves as a high-performance dispatcher that routes user input to the runtime, bundler, test runner, or package manager. Designed as a drop-in replacement for Node.js and npm, Bun's CLI minimizes overhead through static command routing and specialized argument parsing in Zig.
For details on the underlying dispatch logic, see CLI Architecture and Command Dispatch. For script execution and the shell bridge, see Run Command and Script Execution. For bundling and compilation, see Build Command and Compilation. For the test runner, see Test Command. For dependency management, see Install and Package Commands.
Bun's CLI is built for sub-millisecond startup. The entry point initializes the global logger and tracks the process lifecycle. Argument parsing is handled by specialized Zig modules that map CLI inputs to internal command structures.
The CLI uses a Subcommand enumeration to identify and route user requests src/install/PackageManager.zig139-155 This system handles everything from standard package management (install, add, remove) to specialized utility commands like patch, audit, and scan src/install/PackageManager.zig140-155
Sources: src/install/PackageManager.zig139-203 src/install/PackageManager/CommandLineArguments.zig1-12
The execution system manages local files and package.json scripts. A key feature is the replacement of standard package manager calls with Bun's internal equivalents to avoid the overhead of spawning new shells or processes. This is reflected in the CLI completions which support dynamic script discovery from package.json completions/bun.bash32-67
The PackageManager handles a wide array of subcommands including install, update, link, and pm src/install/PackageManager.zig140-146 It supports different linker strategies, such as hoisted (yarn-like) or isolated (pnpm-like) src/install/PackageManager/PackageManagerOptions.zig71-72
installIsolatedPackages, which uses a content-addressable store to create symlink-based node_modules src/install/isolated_install.zig4-10<cache_dir>/links) to make warm installs O(packages) symlinks instead of O(files) copy operations src/install/isolated_install/Installer.zig24-29The test runner is configured via the [test] section of bunfig.toml or CLI flags docs/runtime/bunfig.mdx166-173 It supports advanced discovery features like pathIgnorePatterns to prune directories during scanning docs/runtime/bunfig.mdx193-200
Sources: src/install/PackageManager.zig139-155 src/install/isolated_install.zig4-15 src/install/PackageManager/PackageManagerOptions.zig1-91 src/install/PackageManager/CommandLineArguments.zig1-80
Bun's behavior is configured via bunfig.toml, which can be project-local or global (e.g., $HOME/.bunfig.toml) docs/runtime/bunfig.mdx6-18 If both are present, they are shallow-merged docs/runtime/bunfig.mdx19
preload scripts, jsx behavior, and smol mode for memory efficiency docs/runtime/bunfig.mdx25-61.bagel = "tsx") docs/runtime/bunfig.mdx86-90CLI arguments are defined using the clap library in Zig. Shared parameters across install commands include --production, --frozen-lockfile, --cache-dir, and --backend src/install/PackageManager/CommandLineArguments.zig21-57 The backend flag allows platform-specific optimizations like clonefile on macOS or hardlink on Linux src/install/PackageManager/CommandLineArguments.zig45
Bun provides comprehensive completion scripts for:
These scripts handle dynamic completions for package names, bunfig.toml paths, and package.json scripts completions/bun.zsh42-51 completions/bun.bash32-54
Sources: docs/runtime/bunfig.mdx1-107 src/install/PackageManager/CommandLineArguments.zig21-77 completions/bun.zsh1-160
Subcommand system, argument parsing with clap, and the dispatcher.bun run, shell detection, and package.json script optimization.bun build, configuration, and standalone binary compilation.PackageManager, including isolated vs hoisted linkers and the global package store.