Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 39 ยท Getting Started

A Tour of the Bun CLI

A guided tour of every important Bun command - run, install, add, build, test, bunx, create, repl, upgrade - plus global flags and the bunfig.toml configuration file.

The bun command is the front door to everything in the toolbox. Once you know the handful of subcommands and what each is for, you can find your way around any Bun project. This lesson is a map: it names every command you will use in this course, shows its most useful options, and introduces bunfig.toml, the optional configuration file.

Everything here is shell usage, so the blocks are read-only. You can paste any of them into a terminal where Bun is installed.

The command map

Run code

bun run files and scripts
--watch restart on change
--hot reload, keep state
bun repl interactive prompt

bun file.ts is shorthand for bun run file.ts.

1 / 3

Running code: bun run

Terminal
bun run index.ts          # run a file
bun index.ts              # shorthand
bun run dev               # run the "dev" script from package.json
bun dev                   # shorthand when the name is not a Bun command
bun -e "console.log(1+1)" # evaluate a string of code

When the name matches a Bun subcommand (install, test, build, add...), the subcommand wins. If your package.json has a script called test and you want to run that script rather than the built-in test runner, write bun run test. Running bun run with no argument lists the scripts and runnable files it found.

Useful flags that go before the file name:

Flag Meaning
--watch Restart the process whenever an imported file changes.
--hot Hot reload: re-evaluate modules without restarting the process.
--env-file=.env.staging Load a specific environment file.
--preload ./setup.ts Run a file before the entry point (for plugins, polyfills).
--inspect Start the debugger so you can attach DevTools or an editor.
--bun Force Bun's runtime for tools whose shebang says node.
--silent Do not echo the command being run.
--cwd <dir> Run as if started in another directory.

Watch and hot reload get a lesson of their own in Watch Mode and Hot Reloading.

Managing packages

Terminal
bun install               # install everything in package.json
bun add zod               # add a dependency
bun add -d typescript     # add a dev dependency
bun remove zod            # remove one
bun update                # update within semver ranges
bun outdated              # show newer versions

bun install reads package.json, fills node_modules, and writes the bun.lock lockfile. The package manager chapter has a full lesson on each option. Related commands live under bun pm:

Terminal
bun pm ls                 # list installed packages
bun pm cache              # print the cache directory
bun pm cache rm           # clear the global cache
bun pm bin                # print the local node_modules/.bin path

bunx: run a package without installing it

bunx is Bun's equivalent of npx. It downloads a package to the cache (if needed) and runs its executable:

Terminal
bunx cowsay "Hello"       # run a CLI package once
bunx prettier --check .   # use a project's local binary if present
bunx --bun vite           # run the tool with Bun instead of Node

bunx is literally bun x. It is a quick way to try tools and to run scaffolders such as bunx create-vite.

Starting new projects

Terminal
bun init                  # blank project in the current folder
bun create vite my-app    # from a template (here: npm package create-vite)
bun create ./my-template  # from a local template folder

bun create <name> looks for an create-<name> npm package, a GitHub repo or a local template, copies it, and runs bun install.

Building and testing

Terminal
bun build ./src/index.ts --outdir ./dist
bun build ./src/cli.ts --compile --outfile mycli
bun test
bun test --watch

bun build is the bundler (chapter 4 in this course). bun test finds files named *.test.ts, *_test.ts, *.spec.ts and similar, runs them with a Jest-compatible API, and prints a summary. Testing has its own chapter.

Helpful extras

  • bun repl opens an interactive prompt where you can type JavaScript and TypeScript, with top-level await.
  • bun upgrade updates Bun; bun --version prints it.
  • bun --help and bun <command> --help print full usage text for every flag.
  • bun pm ls, bun why <package> (shows why a package is installed) and bun info <package> (prints registry metadata) help you explore dependencies.
  • bun completions installs tab completion.

If you mistype, bun suggests the closest command name.

Configuration with bunfig.toml

Most projects need no configuration at all. When you do, Bun reads a TOML file called bunfig.toml in the project root (and an optional global one in ~/.bunfig.toml). Here is a small example:

TOML
# bunfig.toml

# Run before every `bun run`, `bun test`, etc.
preload = ["./setup.ts"]

[install]
# Use a private registry for one scope
registry = "https://registry.npmjs.org"
# Do not write bun.lock
# save = false

[test]
# Extra setup for tests, and coverage on by default
preload = ["./test-setup.ts"]
coverage = true

[run]
# Pretend to be Bun for scripts that start with "node"
bun = true

A few things to remember:

  • Command-line flags override bunfig.toml, and project config overrides global config.
  • [install], [test] and [run] are section names; each controls one command family.
  • TOML strings need quotes; arrays use square brackets.
  • Changes need no restart: the file is read each time you run a command.

Later lessons add the specific keys they need, for example [install.scopes] for private registries in overrides, patches and registries.

Environment files and variables

Bun loads .env files automatically for bun run, bun test and others, so you rarely install dotenv. NODE_ENV and BUN_* variables change behaviour. The environment lesson goes deeper.

A stand-in: a tiny command dispatcher

Bun's CLI is a router that maps a first word to an action and falls back to "run this file". You can model that decision in plain JavaScript:

Node.js Stand-in: how the CLI routes a command (runs on Node 24)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice test hits the built-in first. That mirrors the real rule and explains why bun run test exists.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is bunx the Bun equivalent of?

    bunx downloads (if needed) and runs a package's executable, like npx.
  2. 2. You have a package.json script named test but want to run it instead of Bun's test runner. What do you type?

    Built-in subcommands win over script names. bun run test runs the script.
  3. 3. Which file configures Bun for a project?

    bunfig.toml (TOML format) in the project root, with an optional global ~/.bunfig.toml.
  4. 4. What is the difference between --watch and --hot?

    Watch mode restarts the whole process on change; hot mode re-evaluates modules and keeps the process alive.

Summary

  • bun run runs files and package.json scripts; bun file.ts is a shorthand.
  • bun install, add, remove, update and bun pm manage packages; bunx runs package binaries.
  • bun build bundles, bun test tests, bun init and bun create scaffold.
  • bunfig.toml is optional configuration with [install], [test] and [run] sections; flags override it.
  • Built-in subcommand names take priority over scripts; use bun run <script> to be explicit.

Next: TypeScript and JSX in Bun