Bun CLI

Bun is an all-in-one JavaScript/TypeScript runtime, package manager, bundler, and test runner. Bun runs TypeScript natively — bun file.ts directly, no compile step, no tsc, no ts-node. Always use bun instead of node, npm, npx, yarn, or pnpm in Bun projects.

Detecting Bun Projects

A project uses Bun if any of these are present:

• bun.lock or bun.lockb in the project root
• bunfig.toml in the project root
• bun field in package.json (e.g., "bun": { "install": { ... } })
• Package manager field: "packageManager": "bun@..."
• [run] bun = true in bunfig.toml (forces Bun runtime for all scripts)

Critical Rule

In a Bun project, ALWAYS use bun for everything. Never fall back to node, npm, npx, yarn, or pnpm. This avoids compatibility issues, unnecessary retries, and cryptic errors from Node.js/npm not understanding Bun-specific features (workspace protocol, lockfile format, trustedDependencies, etc.).

• Run files: bun file.ts (not node file.ts)
• Run scripts: bun run dev (not npm run dev)
• Execute binaries: bunx tool (not npx tool)
• Install packages: bun add pkg (not npm install pkg)
• Run tests: bun test (not npx jest or node --test)

Read-Only Commands (safe, no side effects)

Command	Purpose
bun --version	Runtime version
bun info <pkg>	Package metadata, available versions
bun info <pkg> versions	List all published versions
bun pm ls	List installed packages
bun pm ls --all	List all (including transitive)
bun pm hash	Print lockfile hash
bun pm cache	Show cache directory
bun outdated	Check for outdated dependencies
bun audit	Security vulnerability audit
bun test	Run test suite
bun run lint	Run linter (project-specific)
bun run check-types	Type checking (project-specific)

Reference: See references/allowlist.md for copy-paste Bash(command:*) patterns for Claude Code / OpenCode settings.

npm/npx/node to Bun Translation

npm/npx/node	Bun equivalent
npm install	bun install
npm install pkg	bun add pkg
npm install -D pkg	bun add -d pkg
npm install -g pkg	bun add -g pkg
npm uninstall pkg	bun remove pkg
npm update	bun update
npm run script	bun run script
npx command	bunx command
node file.js	bun file.js
node --watch file.js	bun --watch file.js
npm test	bun test
npm pack	bun pm pack
npm publish	bun publish
npm info pkg	bun info pkg
npm outdated	bun outdated
npm audit	bun audit
npm link	bun link

Key Behavioral Differences

• No npm run prefix needed: bun run dev works, but so does bun dev (direct script execution)
• --bun flag: Forces Bun runtime instead of Node.js for scripts that use node in their shebang. In bunfig.toml, set [run] bun = true to make this the default
• Lockfile: Bun uses bun.lock (text-based, v1.2+) or bun.lockb (binary, legacy). Text lockfile is default for new projects
• Workspace commands: Use --filter flag: bun --filter 'pkg-name' add dep
• Lifecycle scripts: Bun ignores lifecycle scripts by default for security. Use trustedDependencies in package.json to allowlist packages that need postinstall etc.

Package Management

Installing Dependencies

bun install                    # Install all from package.json
bun install --frozen-lockfile  # CI mode: fail if lockfile needs update
bun install --no-save          # Install without updating package.json
bun install --production       # Skip devDependencies
bun install --dry-run          # Show what would be installed

Adding/Removing Packages

bun add pkg                    # Add to dependencies
bun add pkg@version            # Add specific version
bun add -d pkg                 # Add to devDependencies (--dev)
bun add -D pkg                 # Same as -d
bun add --optional pkg         # Add to optionalDependencies
bun add -g pkg                 # Install globally
bun add --exact pkg            # Pin exact version (no ^)
bun remove pkg                 # Remove package

Updating and Inspecting

bun update                     # Update all packages
bun update pkg                 # Update specific package
bun outdated                   # Show outdated packages
bun info pkg                   # Show package metadata
bun info pkg versions          # List all available versions
bun pm ls                      # List installed packages
bun pm ls --all                # List all (including transitive)
bun pm hash                    # Print lockfile hash
bun pm cache                   # Show cache directory
bun pm cache rm                # Clear cache

Linking and Patching

bun link                       # Register current package as linkable
bun link pkg-name              # Link a registered package
bun pm pack                    # Create tarball of package
bun patch pkg                  # Start patching a package
bun patch --commit pkg-dir     # Apply patch

Publishing

bun publish                    # Publish to npm
bun publish --dry-run          # Preview what would be published
bun publish --tag beta         # Publish with tag
bun publish --access public    # Set access level

Reference: See references/package-management.md for complete flag details.

Running Scripts and Files

Direct Execution

bun file.ts                    # Run TypeScript/JavaScript directly
bun run script-name            # Run package.json script
bun script-name                # Short form (if no conflict with bun commands)
bun --watch file.ts            # Re-run on file changes
bun --hot file.ts              # Hot reload (preserves state)
bun --env-file .env file.ts    # Load env file
bun --env-file .env.local --env-file .env file.ts  # Multiple env files

bunx (npx Replacement)

bunx command                   # Run package binary (auto-installs if needed)
bunx --bun command             # Force Bun runtime for the command
bunx command@version           # Run specific version

Workspace-Aware Execution

bun --filter 'pkg-name' run script    # Run in specific workspace
bun --filter '*' run script           # Run in all workspaces
bun --filter './apps/*' run build     # Run with glob pattern

Script Flags

bun run --smol file.ts         # Reduce memory usage (sacrifice throughput)
bun run --silent script        # Suppress script name echo
bun run --shell=bun script     # Use Bun's built-in shell (cross-platform, default on Windows)
bun run --shell=system script  # Use system shell (default on macOS/Linux)

Reference: See references/running-and-execution.md for complete details.

Testing

Bun includes a built-in test runner compatible with Jest-like syntax.

Running Tests

bun test                          # Run all test files
bun test file.test.ts             # Run specific file
bun test --filter "pattern"       # Filter by test name
bun test --timeout 10000         # Set timeout (ms)
bun test --bail                   # Stop on first failure
bun test --bail 5                 # Stop after 5 failures
bun test --rerun-each 3           # Run each test 3 times
bun test --only                   # Run only tests marked with .only
bun test --todo                   # Include .todo tests

Coverage

bun test --coverage               # Enable code coverage
bun test --coverage-reporter text # Coverage format: text, lcov, json
bun test --coverage-dir ./cov     # Output directory

Test File Patterns

By default, Bun finds files matching: *.test.{ts,tsx,js,jsx}, *_test.{ts,tsx,js,jsx}, *.spec.{ts,tsx,js,jsx}, *_spec.{ts,tsx,js,jsx}, and files in __tests__/ directories.

Snapshot Testing

bun test --update-snapshots       # Update snapshot files

Watch Mode

bun test --watch                  # Re-run on file changes

Reference: See references/testing.md for test API, mocking, lifecycle hooks, and coverage config.

Bundling and Compilation

Bundling

bun build ./src/index.ts --outdir ./dist           # Bundle to directory
bun build ./src/index.ts --outfile ./dist/out.js    # Bundle to single file
bun build ./src/index.ts --target browser           # Target: browser (default), bun, node
bun build ./src/index.ts --format esm               # Format: esm (default), cjs, iife
bun build ./src/index.ts --minify                   # Minify output
bun build ./src/index.ts --sourcemap external        # Sourcemaps: external, inline, linked, none
bun build ./src/index.ts --splitting                # Code splitting (ESM only)

Standalone Executables

bun build ./src/cli.ts --compile                    # Create self-contained executable
bun build ./src/cli.ts --compile --target bun-linux-x64    # Cross-compile
bun build ./src/cli.ts --compile --minify           # Minified executable

Available compilation targets: bun-linux-x64, bun-linux-arm64, bun-darwin-x64, bun-darwin-arm64, bun-windows-x64.

Build Options

bun build ... --external pkg        # Exclude from bundle
bun build ... --define 'KEY=VALUE'  # Define compile-time constants
bun build ... --loader .ext=type    # Custom loaders (js, jsx, ts, tsx, json, css, text, file, base64, dataurl, binary)
bun build ... --entry-naming [dir]/[name].[ext]   # Output naming pattern
bun build ... --public-path /cdn/   # Public path prefix for assets

Reference: See references/bundling-and-compilation.md for complete options.

Project Initialization

bun init                       # Initialize new project (creates package.json, tsconfig.json, index.ts)
bun create template-name       # Create from template
bun create next-app my-app     # Example: create Next.js app

Configuration (bunfig.toml)

Key sections:

[run]
bun = true                     # Always use Bun runtime (not Node)

[install]
exact = true                   # Pin exact versions by default
peer = false                   # Don't auto-install peer deps
production = false             # Include devDeps
frozenLockfile = false         # Don't fail on lockfile mismatch
globalDir = "~/.bun/install/global"  # Global install location

[install.scopes]
"@myorg" = { token = "$NPM_TOKEN", url = "https://npm.pkg.github.com/" }

[test]
coverage = false               # Enable coverage by default
coverageReporter = ["text", "lcov"]
timeout = 5000                 # Default test timeout

[bundle]
entryPoints = ["./src/index.ts"]
outdir = "./dist"

Reference: See references/configuration.md for complete bunfig.toml reference.

Debugging and Profiling

bun --inspect file.ts              # Start debugger (WebSocket, connect via Chrome DevTools)
bun --inspect-wait file.ts         # Wait for debugger to attach before executing
bun --inspect-brk file.ts         # Break on first line
bun --cpu-prof file.ts             # Generate CPU profile
bun --heap-prof file.ts            # Generate heap profile
BUN_JSC_logJITCodeForPerf=1 bun file.ts  # Linux perf integration

Environment Variables

bun --env-file .env file.ts        # Load .env file
bun --env-file .env.local --env-file .env file.ts  # Load multiple (left takes precedence)

Bun auto-loads .env, .env.production, .env.local, .env.production.local by default based on NODE_ENV.

Built-in Features That Replace External Tools

Bun has many capabilities built in that eliminate the need for external packages or tooling:

Native TypeScript

Bun runs .ts, .tsx files directly — no tsc, ts-node, or tsx needed. The transpiler is built into the runtime. Use bun file.ts to run any TypeScript file immediately.

Workspace Catalogs

Bun supports catalog: protocol in package.json for centralized dependency version management across monorepo workspaces — no need for tools like syncpack or manypkg:

// Root package.json
{
  "workspaces": ["packages/*"],
  "catalog": {
    "react": "^19.0.0",
    "typescript": "^5.7.0"
  }
}

// packages/app/package.json
{
  "dependencies": {
    "react": "catalog:"
  }
}

Built-in Test Runner

bun test is a full Jest-compatible test runner with snapshot testing, mocking, coverage — no need for jest, vitest, or mocha.

Built-in Bundler

bun build replaces esbuild, webpack, rollup for many use cases. Supports code splitting, tree shaking, minification, and standalone executable compilation.

Built-in SQLite

import { Database } from 'bun:sqlite' — zero-dependency SQLite3 with prepared statements and transactions. No need for better-sqlite3 or sql.js.

Built-in Shell

Bun.$ tagged template — cross-platform shell execution with automatic escaping. Replaces execa, shelljs, zx.

Built-in File I/O

Bun.file() and Bun.write() — fast file operations without importing fs. Auto-detects MIME types.

Built-in Glob

new Bun.Glob(pattern) — fast glob matching and file scanning. Replaces glob, fast-glob, minimatch.

Built-in Password Hashing

Bun.password.hash() and .verify() with bcrypt and argon2id. Replaces bcrypt, argon2 packages.

Built-in Compression

Bun.gzipSync(), Bun.deflateSync(), Bun.zstdCompressSync() — no need for zlib wrapper packages.

Built-in Semver

Bun.semver.satisfies(), .order() — replaces semver package.

Key Gotchas

1. Always use bun not npm/node/npx in Bun projects
2. Lockfile format: bun.lock (text, v1.2+) is the default for new projects. Legacy bun.lockb is binary. Don't mix with package-lock.json
3. trustedDependencies: Lifecycle scripts (postinstall, etc.) only run for packages listed in trustedDependencies in package.json
4. --bun flag: Some tools (e.g., Next.js) use Node.js by default even when run with bun run. Use --bun or [run] bun = true in bunfig.toml to force Bun runtime
5. Workspace protocol: Use "workspace:*" in package.json to reference workspace packages
6. Global binaries: Installed with bun add -g, located in ~/.bun/bin/
7. Node.js compatibility: Bun implements most Node.js APIs but some edge cases differ. Check https://bun.sh/docs/runtime/nodejs-apis for compatibility
8. TypeScript: Bun runs TypeScript natively with no compilation step. Uses its own transpiler (not tsc)
9. Auto-install: Bun can auto-install missing packages on import (disabled by default, enable with [install] auto = true in bunfig.toml)
10. bun run vs bun: bun run script runs a package.json script; bun file.ts runs a file directly. bun script tries script first, then falls back to file