bunx

Use bunx to auto-install and run packages from npm. The bunx CLI will be auto-installed when you install bun.

bunx cowsay "Hello world!"

Packages can declare executables in the "bin" field of their package.json. These are known as package executables or package binaries.

{
  // ... other fields
  "name": "my-cli",
  "bin": {
    "my-cli": "dist/index.js"
  }
}

These executables are commonly plain JavaScript files marked with a shebang line to indicate which program should be used to execute them. The following file indicates that it should be executed with node.

#!/usr/bin/env node

console.log("Hello world!");

These executables can be run with bunx,

bunx my-cli

As with npx, bunx will check for a locally installed package first, then fall back to auto-installing the package from npm. Installed packages will be stored in Bun's global cache for future use.

Arguments and flags

To pass additional command-line flags and arguments through to the executable, place them after the executable name.

bunx my-cli --foo bar

Shebangs

By default, Bun respects shebangs. If an executable is marked with #!/usr/bin/env node, Bun will spin up a node process to execute the file. However, in some cases it may be desirable to run executables using Bun's runtime, even if the executable indicates otherwise. To do so, include the --bun flag.

bunx --bun my-cli

bunx --bun my-cli # good

bunx my-cli --bun # bad

Environment variables

Bun automatically loads environment variables from .env files before running a file, script, or executable. The following files are checked, in order:

1. .env.local (first)
2. NODE_ENV === "production" ? .env.production : .env.development
3. .env

To debug environment variables, run bun run env to view a list of resolved environment variables.