Bun CLI reference for package management, script running, testing, bundling, and compilation. Use when working with bun install, bun add, bun run, bun test, bun build, bunx, bunfig.toml, bun.lock, or replacing npm/npx/node commands.
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.
Verified against Bun v1.4.2 (2026-09-05). Features are tagged with the version that
introduced them (v1.4+, v1.4.1+, v1.4.2+). Where a release changed existing behavior, both
behaviors are stated so this skill stays correct on older projects -- run bun --version
before relying on a version-tagged item.
bun <command> --help is authoritative for flags and always matches the installed binary --
prefer it over any table here when the two disagree.
For everything beyond flags, Bun ships its full docs inside bun-types, version-matched to
the runtime, in any project that has bun-types or @types/bun installed:
node_modules/bun-types/docs/pm/**/*.mdx # install, lockfile, workspaces, catalogs, linkers
node_modules/bun-types/docs/test/**/*.mdx # test runner
node_modules/bun-types/docs/bundler/**/*.mdx # bun build, executables, loaders, plugins
node_modules/bun-types/docs/runtime/bunfig.mdx
node_modules/bun-types/CLAUDE.md # Bun's own agent rules
bun --version to
node_modules/bun-types/package.json. bun init installs @types/bun@latest, which lags
behind releases -- correct it with bun add -d bun-types@<runtime-version>.node_modules/bun-types
is a symlink, so find node_modules -name '*.mdx' and rg <pattern> node_modules return
nothing. find node_modules/bun-types/docs -name '*.mdx' works.node_modules/. Under the global store every project on the machine
shares the same inode. Use bun patch.docs/pm/lockfile.mdx is
https://bun.com/docs/pm/lockfile.| Task | Doc path (under node_modules/bun-types/docs/) |
|---|---|
| Install behavior, lockfile, linkers | pm/cli/install.mdx, pm/lockfile.mdx, pm/isolated-installs.mdx, pm/global-store.mdx |
| Workspaces, catalogs, filters, overrides | pm/workspaces.mdx, pm/catalogs.mdx, pm/filter.mdx, pm/overrides.mdx |
| Registries, auth, lifecycle scripts | pm/scopes-registries.mdx, pm/npmrc.mdx, pm/lifecycle.mdx |
| Test runner | test/index.mdx, test/discovery.mdx, test/configuration.mdx, test/code-coverage.mdx, test/reporters.mdx, test/mocks.mdx |
| Bundler, executables, loaders | bundler/index.mdx, bundler/executables.mdx, bundler/loaders.mdx, bundler/plugins.mdx |
| Config | runtime/bunfig.mdx |
| Migrating from npm/yarn/pnpm | guides/install/from-npm-install-to-bun-install.mdx |
A project uses Bun if any of these are present:
bun.lock or bun.lockb in the project rootbunfig.toml in the project rootbun field in package.json (e.g., "bun": { "install": { ... } })"packageManager": "bun@..."[run] bun = true in bunfig.toml (forces Bun runtime for all scripts)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.).
bun file.ts (not node file.ts)bun run dev (not npm run dev)bunx tool (not npx tool)bun add pkg (not npm install pkg)bun test (not npx jest or node --test)| 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 (alias: bun list) |
| bun pm ls --all | List all (including transitive) |
| bun pm ls --trusted | List only packages allowed to run lifecycle scripts (v1.4+) |
| bun pm hash | Print lockfile hash |
| bun pm cache | Show cache directory |
| bun pm bin | Print the bin directory (-g for global) |
| bun pm licenses | List dependencies grouped by license (v1.4+; --json, --prod) |
| bun pm diff <pkg> | Diff two versions of a package (v1.4+) |
| bun pm untrusted | List packages whose lifecycle scripts were blocked |
| bun why <pkg> | Explain why a package is installed |
| bun outdated | Check for outdated dependencies |
| bun audit | Security vulnerability audit |
| bun dedupe --check | Exit 1 if the lockfile has removable duplicates (v1.4+) |
| bun prune --dry-run | Show what would be removed from node_modules (v1.4+) |
| bun test | Run test suite |
| bun run lint | Run linter (project-specific) |
| bun run check-types | Type checking (project-specific) |
Reference: See
references/allowlist.mdfor copy-pasteBash(command:*)patterns for Claude Code / OpenCode settings.
| 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 |
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 defaultbun.lock (text-based, v1.2+) or bun.lockb (binary, legacy). Text lockfile is default for new projects--filter flag: bun --filter 'pkg-name' add deptrustedDependencies in package.json to allowlist packages that need postinstall etc.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
bun install --offline # No network at all; every package must already be cached (v1.4.1+)
bun install --prefer-offline # Cached metadata regardless of age; download only what is missing (v1.4.1+)
--offline suits CI jobs that restore ~/.bun/install/cache and air-gapped machines -- a
missing package fails by name (no cached manifest for 'left-pad'). --prefer-offline skips
the staleness check but still fetches uncached packages. Both have bunfig.toml forms:
[install] offline = true and [install] prefer = "offline".
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 --peer pkg # Add to peerDependencies
bun add -g pkg # Install globally
bun add --exact pkg # Pin exact version (no ^)
bun add pkg --filter api # Add to one workspace from the repo root (v1.4+)
bun add pkg --catalog # Add to the root catalog, depend on it as "catalog:" (v1.4+)
bun remove pkg # Remove package
Changed in 1.4: bun add, bun remove, and bun update accept --filter, and
bun install <pkg> --filter x now edits workspace x rather than the root. In a workspace
whose default catalog already lists the package, a plain bun add <pkg> writes catalog:.
--filter 'web...' selects web and everything it depends on; '...web' selects everything
that depends on web.
bun update # Update all packages within package.json ranges
bun update pkg # Update every copy of pkg, transitive ones included (v1.4+)
bun update '@types/*' --latest # Patterns; --latest ignores the declared range
bun update --recursive # Update every workspace and write each package.json (v1.4+)
bun update --filter 'pkg-*' --filter '!pkg-c' # Repeatable; ! excludes (v1.4+)
bun outdated # Show outdated packages
bun info pkg # Show package metadata
bun info pkg versions # List all available versions
bun why pkg # Explain why a package is in the tree
bun pm ls # List installed packages (alias: bun list)
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 (including the global virtual store)
Changed in 1.4: bun update re-resolves transitive dependencies, not just the ones named
in package.json, and bun update <name> errors with exit 1 when nothing depends on that
name (it used to add the package).
bun audit fix # Upgrade vulnerable packages to the lowest safe version
bun audit fix --dry-run # Preview
bun audit fix --latest # Also apply fixes your declared ranges exclude
bun dedupe # Collapse duplicate versions in bun.lock, then install
bun dedupe --check # CI gate: exit 1 if duplicates remain
bun prune # Drop node_modules entries no longer in bun.lock
bun prune --production # Also drop devDependencies -- build with them, ship without
bun pm licenses --prod --json # License inventory
bun pm diff react@18.2.0 19.0.0 # What changed between two versions of a package
bun pm diff leads with a summary -- files changed, new install scripts, and new imports of
child_process, fs, net, or vm -- then the diff, with minified files expanded and
formatting-only changes skipped. Useful for reviewing a dependency bump.
bun prune --production fits the Docker build stage:
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile
COPY . .
RUN bun run build
RUN bun prune --production
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
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.mdfor complete flag details.
Two settings decide how node_modules is laid out. Both matter more than they look.
| | hoisted | isolated |
|---|---|---|
| Layout | npm-style flat node_modules | symlinks into node_modules/.bun/ (pnpm-style) |
| Phantom dependencies | resolve silently | fail, as they should |
| Default when | configVersion = 0 (any project), or configVersion = 1 without workspaces | configVersion = 1 and the project uses workspaces |
The default depends on the lockfile's configVersion, not on the Bun version: isolated only
when configVersion = 1 and the project uses workspaces. Lockfiles created before v1.3.2
are treated as configVersion = 0 and keep hoisted, so upgrading Bun does not change an
existing project's layout. Override with --linker or [install] linker.
Package files live once in ~/.bun/install/cache/links/ and each project symlinks into them:
warm installs are roughly 7x faster, and node_modules drops from hundreds of MB to a few MB
of links. It is off by default and needs both settings -- with linker = "hoisted" the
globalStore flag is silently ignored.
[install]
linker = "isolated" # prerequisite
globalStore = true
BUN_INSTALL_GLOBAL_STORE=1 bun install --linker isolated # per invocation
bun pm cache rm # clears the store too
Consequences worth knowing before enabling it:
node_modules is mostly symlinks. find node_modules -name '*.mdx' and
rg <pattern> node_modules return nothing, and du -sh node_modules reports ~0B
because it measures the symlinks rather than their targets (the real tree is a few MB of
links; du -sh -L shows the target sizes, counted once per link). Address
files by explicit path, or pass find -L (which double-counts through the link layers).
Tools that scan node_modules without following symlinks behave differently -- the same
caveat as any pnpm-style layout.node_modules/ changes it
for every project on the machine. Use bun patch.node_modules/.bun/node_modules/ layer is no longer on the resolution path from
inside a package. Fix by declaring the dependency, or set globalStore = false.trustedDependencies, and anything
depending on a workspace:, file:, or link: dependency. Ineligibility propagates up
the graph, so a monorepo keeps a good share of the tree local regardless.Reference:
node_modules/bun-types/docs/pm/global-store.mdxandpm/isolated-installs.mdx.
Electron packagers and serverless bundlers repackage one workspace's node_modules and expect
every dependency physically under it. List such workspaces in the root package.json, or set
Yarn's "installConfig": { "hoistingLimits": "workspaces" } in the workspace's own file:
{ "workspaces": { "packages": ["apps/*", "packages/*"], "selfContained": ["apps/desktop"] } }
Nothing that workspace depends on, directly or transitively, is hoisted above
apps/desktop/node_modules, and those packages are real copies rather than cache hardlinks.
The lockfile does not record it, and it has no effect under the isolated linker.
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
bun --no-env-file file.ts # Skip automatic .env loading (CI/prod; `env = false` in bunfig)
bun --env-file=<(op inject -i .env.tpl) file.ts # 1Password CLI renders dotenv lines; any pipe/FIFO//dev/stdin works (v1.4.1+)
bun --no-ffi-cc file.ts # cc() from bun:ffi throws ERR_FFI_CC_DISABLED (v1.4.1+)
bun --no-orphans run dev # Die with the parent, SIGKILL every descendant on exit
bun repl # Native REPL: highlighting, history, completion (v1.3.10+)
bun repl -p '{ a: 1 }' # Evaluate and print with REPL semantics
bun exec 'ls | wc -l' # Run a shell script through Bun's shell
bun ./README.md # Render Markdown in the terminal, no VM started
bunx command # Run package binary (auto-installs if needed)
bunx --bun command # Force Bun runtime for the command
bunx command@version # Run specific version
Replaces npm-run-all and concurrently. Output is prefixed per script (or package:script
under --filter), and pre*/post* hooks stay grouped with their main script.
bun run --parallel build lint typecheck # Run all concurrently
bun run --parallel 'build:*' # Glob-match script names
bun run --parallel --filter '*' build # Fan out across every workspace
bun run --parallel --no-exit-on-error --filter '*' test # Keep going past failures
bun run --sequential clean build deploy # One at a time, same prefixed output
The flag may also precede run (bun --parallel run build lint); both forms work.
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
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)
Run HTML files directly as a dev server -- no Vite, Webpack, or any config needed:
bun ./index.html # Start dev server, auto-bundles JS/TS/CSS
bun --hot ./index.html # With hot module replacement
Bun automatically transpiles TypeScript, JSX, TSX, and CSS linked from the HTML. Resolves node_modules imports in <script> tags. Enables HMR and React Fast Refresh.
Reference: See
references/running-and-execution.mdfor complete details.
Bun includes a built-in test runner compatible with Jest-like syntax.
bun test # Run all test files
bun test file.test.ts # Run specific file
bun test foo bar # Positional args filter by FILE path, not test name
bun test -t "pattern" # Filter by TEST NAME (regex); --grep is an alias
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 --retry 3 # Default retry count for flaky tests
bun test --only # Run only tests marked with .only
bun test --todo # Include .todo tests
bun test --only-failures # Print failures and the summary only
bun test --pass-with-no-tests # Exit 0 when nothing matches (monorepos)
--filter is not a test-name filter. In bun test, --filter is another file path
filter, identical to a positional argument; -F is rejected. (Workspace selection is a
package-manager feature: bun run --filter '*' test.) Passing a test name usually matches
no files, and bun test then exits 1 ("did not match any test files") -- so the mistake
fails the run rather than passing it silently, but it still tests nothing. Use -t /
--test-name-pattern / --grep for test names. --pass-with-no-tests turns that exit 1
into 0, which is what would hide it.
bun test --coverage # Enable code coverage
bun test --coverage-reporter text # Coverage format: 'text' and/or 'lcov' -- there is no 'json'
bun test --coverage-dir ./cov # Output directory
bun test --parallel # Files across N worker processes (default: CPU count)
bun test --parallel=4 --isolate # Explicit worker count
bun test --isolate # Fresh globalThis per file, same process (Jest/Vitest default)
bun test --shard=1/3 # One CI runner's slice of the files
bun test --changed=main # Only files your diff reaches (walks the import graph)
bun test --timings=t.json --update-timings # Record per-file durations
bun test --parallel --shard=1/3 --timings=t.json # Balance by wall time, not file count
--parallel implies --isolate; --no-isolate opts out so each worker reuses one
global and module registry.--isolate fixes "passes alone, fails in the suite" by resetting globalThis and the module
registries between files, and closing servers, sockets, watchers, and subprocesses the file
left open. Transpiled source and bytecode stay cached across globals, so the cost is low.JEST_WORKER_ID / BUN_TEST_WORKER_ID, so Jest
setups that key a database or port off JEST_WORKER_ID work unchanged.--bail stops every worker.--timings (v1.4+) makes shards equal in time rather than file count, and the file is
written slowest-first so it doubles as a slow-test report.mock(), spyOn(), mock.module(), or Bun.plugin() from keeping
the previous module graph alive under --isolate, so memory stays flat across a large suite.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. Exclude paths with --path-ignore-patterns <glob> or test.pathIgnorePatterns in bunfig.toml.
bun test --update-snapshots # Update snapshot files
bun test --watch # Re-run on file changes
Reference: See
references/testing.mdfor test API, mocking, lifecycle hooks, and coverage config.
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/
<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer