Command-Line Interface¶

Complete reference for bunenv’s command-line options.

Synopsis¶

bunenv [OPTIONS] DEST_DIR
bunenv --list
bunenv --version

Description¶

bunenv creates isolated Bun environments, similar to Python’s virtualenv.

Basic Usage¶

# Create environment with latest Bun
bunenv myenv

# Create with specific version
bunenv myenv --bun=1.3.3

# List available Bun versions
bunenv --list

# Show bunenv version
bunenv --version

Positional Arguments¶

DEST_DIR¶

Destination directory for the Bun environment.

Type: String (path)

Required: Yes (unless using --list or --python-virtualenv)

Examples:

bunenv myenv              # Relative path
bunenv /opt/bunenv        # Absolute path
bunenv .venv              # Common convention
bunenv ~/projects/env     # Home directory

Version Options¶

--version¶

Show bunenv version and exit.

bunenv --version
# Output: 0.1.0

-b, --bun BUN_VER¶

Specify Bun version to install.

Type: String

Default: latest

Values:

latest - Most recent stable release
X.Y.Z - Specific version (e.g., 1.3.3)
system - Use system-installed Bun

Examples:

bunenv myenv --bun=latest     # Latest stable
bunenv myenv --bun=1.3.3      # Pin to 1.3.3
bunenv myenv -b 1.0.0         # Short form

System Bun:

bunenv myenv --bun=system

Warning

--bun=system is not supported on Windows.

-l, --list¶

List all available Bun versions from GitHub Releases and exit.

bunenv --list

Output (example):

1.3.3    1.3.2    1.3.1    1.3.0    1.2.15   1.2.14   1.2.13   1.2.12
1.2.11   1.2.10   1.2.9    1.2.8    1.2.7    1.2.6    1.2.5    1.2.4
...

--variant VARIANT¶

Specify Bun binary variant.

Type: Choice

Default: "" (auto-detect)

Choices: "", baseline, profile, musl

Auto-detection:

Linux with musl → musl
All others → standard (default)

Examples:

# Auto-detect (recommended)
bunenv myenv --bun=1.3.3

# Force baseline for old CPUs
bunenv myenv --bun=1.3.3 --variant=baseline

# musl for Alpine Linux
bunenv myenv --bun=1.3.3 --variant=musl

# Profile build for debugging
bunenv myenv --bun=1.3.3 --variant=profile

Variant Comparison:

Variant	Use Case	CPU Requirement
Standard (default)	Modern systems	Haswell/Excavator+ (2013+)
Baseline	Older systems	Nehalem/Bulldozer+ (2008+)
Musl	Alpine/Void Linux	Any (musl libc)
Profile	Development/debugging	Any

Network Options¶

--github-token TOKEN¶

GitHub personal access token for API requests.

Type: String

Default: None

Why needed: Avoid GitHub API rate limits (60/hour → 5000/hour)

Examples:

# Direct
bunenv myenv --github-token=ghp_your_token_here

# From environment variable
export GITHUB_TOKEN=ghp_your_token
bunenv myenv --github-token=$GITHUB_TOKEN

# From config file
echo "github_token = ghp_your_token" >> ~/.bunenvrc
bunenv myenv  # Uses token from config

Creating a token:

Go to https://github.com/settings/tokens
Generate new token (classic)
No scopes needed for public repos
Copy token (ghp_...)

--mirror URL¶

Set alternative mirror URL for Bun downloads.

Type: String (URL)

Default: https://github.com/oven-sh/bun/releases/download

Examples:

# Corporate mirror
bunenv myenv --mirror=https://artifacts.corp.com/bun/releases

# Local mirror
bunenv myenv --mirror=http://localhost:8000

Mirror URL format:

{mirror}/bun-v{version}/bun-{platform}-{arch}[-{variant}].zip

--ignore_ssl_certs¶

Disable SSL certificate verification.

Type: Boolean flag

Default: False

Examples:

bunenv myenv --ignore_ssl_certs

Danger

UNSAFE: Only use when absolutely necessary (corporate proxy with self-signed certs). This disables security verification!

Installation Options¶

-r, --requirements FILENAME¶

Install packages from requirements file after creating environment.

Type: String (file path)

Default: None

File format: One package per line

Example file (requirements-bun.txt):

express
typescript
@types/node
zod

Usage:

bunenv myenv --requirements=requirements-bun.txt

Equivalent to:

bunenv myenv
source myenv/bin/activate
bun add express typescript @types/node zod

-c, --clean-src¶

Remove downloaded source files after installation.

Type: Boolean flag

Default: False

Examples:

bunenv myenv --clean-src

Effect: Removes myenv/src/ directory (~50MB saved)

When to use: Save disk space (recommended for production environments)

--force¶

Overwrite existing environment directory.

Type: Boolean flag

Default: False

Examples:

# First creation
bunenv myenv --bun=1.3.3

# Try again - ERROR
bunenv myenv --bun=1.3.4
# Error: Environment already exists

# Force overwrite
bunenv myenv --bun=1.3.4 --force

Warning

This deletes the existing environment! Installed packages will be lost.

--prebuilt¶

Install Bun from prebuilt binaries.

Type: Boolean flag

Default: True

Examples:

bunenv myenv --prebuilt

Note

This is the only option for Bun (no source builds available). Flag exists for nodeenv compatibility.

--update¶

Install packages from requirements file into existing environment without creating new Bun install.

Type: Boolean flag

Default: False

Examples:

# Create environment
bunenv myenv

# Later, update packages
bunenv --update --requirements=new-packages.txt

Environment Options¶

-p, --python-virtualenv¶

Install Bun into the current Python virtualenv instead of creating new directory.

Type: Boolean flag

Default: False

Requires: Active Python virtualenv

Examples:

# Create Python venv
python -m venv .venv
source .venv/bin/activate

# Install bunenv
pip install bunenv

# Add Bun to same environment
bunenv --python-virtualenv --bun=1.3.3

# Now have both
(venv) $ python --version  # Python 3.11.x
(venv) $ bun --version     # 1.3.3

--prompt PROMPT¶

Custom shell prompt prefix when environment is activated.

Type: String

Default: (directory-name)

Examples:

# Default
bunenv myenv
source myenv/bin/activate
(myenv) $

# Custom
bunenv myenv --prompt="[my-app] "
source myenv/bin/activate
[my-app] $

# Empty (no prompt change)
bunenv myenv --prompt=""
source myenv/bin/activate
$

Configuration Options¶

-C, --config-file FILE¶

Load configuration from custom file.

Type: String (file path)

Default: ["./tox.ini", "./setup.cfg", "~/.bunenvrc"] (checked in order)

Examples:

# Use custom config
bunenv myenv --config-file=./bunenv.ini

# Disable all config files (use built-in defaults)
bunenv myenv --config-file=

Config file format:

[bunenv]
bun = 1.3.3
variant = baseline
github_token = ghp_xxx

Logging Options¶

-v, --verbose¶

Enable verbose output showing detailed installation steps.

Type: Boolean flag

Default: False

Examples:

bunenv myenv --verbose

Output comparison:

# Normal
* Install prebuilt Bun (1.3.3) ........ done.

# Verbose
* Install prebuilt Bun (1.3.3)
 * Creating: myenv/bin ... done.
 * Downloading from https://github.com/oven-sh/bun/...
 * Extracting archive
 * Copying binary
done.

-q, --quiet¶

Suppress non-error output.

Type: Boolean flag

Default: False

Examples:

bunenv myenv --quiet

When to use: Scripting, CI/CD where you only want error output

Usage Examples¶

Basic Examples¶

# Minimal - latest Bun
bunenv myenv

# Specific version
bunenv myenv --bun=1.3.3

# Old CPU support
bunenv myenv --bun=1.3.3 --variant=baseline

# With requirements
bunenv myenv --requirements=packages.txt

Advanced Examples¶

# Full-featured setup
bunenv myenv \
  --bun=1.3.3 \
  --variant=baseline \
  --requirements=requirements-bun.txt \
  --github-token=$GITHUB_TOKEN \
  --clean-src \
  --prompt="[my-app] "

# Corporate environment
bunenv myenv \
  --mirror=https://artifacts.corp.com/bun/releases \
  --github-token=$CORP_GITHUB_TOKEN \
  --ignore_ssl_certs  # Only if necessary!

# Python integration
python -m venv .venv
source .venv/bin/activate
pip install bunenv
bunenv --python-virtualenv --bun=1.3.3

CI/CD Examples¶

GitHub Actions:

- name: Setup Bun
  run: |
    pip install bunenv
    bunenv .venv --bun=1.3.3 --clean-src --quiet
    source .venv/bin/activate
    echo "$PWD/.venv/bin" >> $GITHUB_PATH

GitLab CI:

before_script:
  - pip install bunenv
  - bunenv .venv --bun=1.3.3 --quiet
  - source .venv/bin/activate

Exit Codes¶

Code	Meaning
`0`	Success
`1`	General error (network, file system, etc.)
`2`	Invalid arguments or environment already exists (without `--force`)

Environment Variables¶

Variables Set by bunenv¶

When environment is activated:

BUN_VIRTUAL_ENV=/path/to/environment
BUN_INSTALL=/path/to/environment
BUN_INSTALL_BIN=/path/to/environment/bin
PATH=/path/to/environment/bin:$PATH

Variables Used by bunenv¶

bunenv reads these if set:

# Used for GitHub token
GITHUB_TOKEN=ghp_xxx

# Disable prompt changes
BUN_VIRTUAL_ENV_DISABLE_PROMPT=1

Files and Directories¶

Created by bunenv¶

myenv/
├── bin/                   # Unix (macOS/Linux)
│   ├── activate           # Bash/zsh activation
│   ├── activate.fish      # Fish shell activation
│   ├── bun               # Bun executable
│   └── shim              # System bun wrapper
├── Scripts/               # Windows
│   ├── activate.bat       # cmd.exe activation
│   ├── Activate.ps1       # PowerShell activation
│   └── bun.exe           # Bun executable
├── install/
│   └── cache/            # Bun package cache
└── src/                  # Downloaded files (optional)
    └── bun-*/

Configuration Files¶

bunenv reads (in order):

./tox.ini
./setup.cfg
~/.bunenvrc
.bun-version (version only)
Custom file via --config-file

Reporting Bugs¶

Report issues at: https://github.com/JacobCoffee/bunenv/issues

Include:

bunenv version (bunenv --version)
Full command run
Error output (with --verbose)
Platform information

Author¶

Jacob Coffee <jacob@z7x.org>

Adapted from nodeenv by Eugene Kalinin.

License¶

BSD-3-Clause

See: https://github.com/JacobCoffee/bunenv/blob/main/LICENSE

Command-Line Interface¶

Synopsis¶

Description¶

Basic Usage¶

Positional Arguments¶

DEST_DIR¶

Version Options¶

--version¶

-b, --bun BUN_VER¶

-l, --list¶

--variant VARIANT¶

Network Options¶

--github-token TOKEN¶

--mirror URL¶

--ignore_ssl_certs¶

Installation Options¶

-r, --requirements FILENAME¶

-c, --clean-src¶

--force¶

--prebuilt¶

--update¶

Environment Options¶

-p, --python-virtualenv¶

--prompt PROMPT¶

Configuration Options¶

-C, --config-file FILE¶

Logging Options¶

-v, --verbose¶

-q, --quiet¶

Usage Examples¶

Basic Examples¶

Advanced Examples¶

CI/CD Examples¶

Exit Codes¶

Environment Variables¶

Variables Set by bunenv¶

Variables Used by bunenv¶

Files and Directories¶

Created by bunenv¶

Configuration Files¶

See Also¶

Reporting Bugs¶

Author¶

License¶