bunvm/README.md

Bun Version Manager - Switch between different versions of Bun easily

# BVM - Bun Version Manager

**BVM** is a simple and fast CLI tool to manage multiple versions of [Bun](https://bun.sh), the all-in-one JavaScript runtime. Inspired by tools like `nvm` and `rvm`, BVM lets you easily install, switch, and manage different Bun versions.

---

## 🚀 Features

- 📥 Install any version of Bun
- 🔁 Switch between installed versions seamlessly
- 📦 Uninstall versions you no longer need
- 📃 List installed and remote Bun versions
- 🎯 Interactive prompts for `install`, `use`, and `uninstall` (powered by [Clack](https://github.com/natemoo-re/clack))
- 🔒 SHA-256 checksum verification before extracting downloads
- 🐧 Smart platform detection (Apple Silicon, Alpine/musl, AVX2 baseline, Rosetta)
- 🐚 Auto-configure shell environment (bash, zsh, fish)
- 🔔 Update notifications when a newer bvm release is available
- 🧠 Lightweight and fast – built with Node.js and TypeScript
- 🔗 Automatic symlink management for `bun` and `bunx`
- ✨ Command completions support

---

## 🖥️ Platform Support

| Platform | Status           | Tested                          |
| -------- | ---------------- | ------------------------------- |
| Linux    | ✅ Supported     | ✅ Tested on Ubuntu/Debian      |
| macOS    | ✅ Supported     | ✅ Tested on M2 (Apple Silicon) |
| Windows  | ❌ Not supported | ❌ Not supported yet            |

**Note**: BVM supports macOS and Linux only. Windows support is not implemented.

---

## 📦 Installation

### Install from npm

```bash
# With npm
npm install -g bunvm

# With pnpm (recommended)
pnpm add -g bunvm

# With yarn
yarn global add bunvm

# With Bun
bun add -g bunvm
```

After installation, you can use the `bvm` command from anywhere in your terminal.

### Install from source

```bash
git clone https://github.com/MrHacker26/bvm.git
cd bvm
pnpm install
pnpm build
pnpm link
```

---

## 🛠️ Usage

Once installed, you can use `bvm` from anywhere in your terminal:

```bash
bvm install [version]     # Install a Bun version (alias: i)
bvm install latest        # Install the latest Bun version
bvm use [version]         # Switch to a Bun version (interactive if omitted)
bvm uninstall [version]   # Remove an installed version (alias: u)
bvm current               # Display currently activated version of Bun
bvm list                  # List installed Bun versions (alias: ls)
bvm remote                # List available remote Bun versions (alias: r)
bvm upgrade               # Show how to update bvm itself
bvm --help                # Show help information
```

### Interactive mode

When run without a version argument in a terminal, `install`, `use`, and `uninstall` show interactive menus:

- **`bvm use`** — pick from installed versions (cursor starts on your current version)
- **`bvm install`** — pick from remote releases (latest is pre-selected; shows `installed` / `current` hints)
- **`bvm uninstall`** — pick a version to remove, then confirm (warns if it's your active version)

In non-interactive environments (CI, pipes), a version argument is required:

```bash
bvm use 1.2.5        # works in scripts
bvm use              # errors in CI — version required
```

### Updating bvm

BVM checks for newer releases in the background (at most once a day) and shows a notification when an update is available. To see how to update:

```bash
bvm upgrade
```

This prints the update command for each package manager (npm, pnpm, yarn, bun) — it does not modify anything itself. To disable the update check, set `NO_UPDATE_NOTIFIER=1`.

---

## 📌 Examples

```bash
# Install the latest Bun version
bvm install latest

# Install a specific Bun version
bvm install 1.0.12
bvm i 1.0.12              # alias

# Interactive install — pick from remote versions
bvm install

# Switch to a specific version
bvm use 1.0.12

# Interactive switch — pick from installed versions
bvm use

# List all installed versions
bvm list
bvm ls                    # alias

# See what versions are available remotely
bvm remote
bvm r                     # alias

# Remove an old version (with confirmation prompt)
bvm uninstall 1.0.11
bvm u 1.0.11              # alias

# Interactive uninstall — pick then confirm
bvm uninstall

# See how to update bvm itself
bvm upgrade
```

---

## 🛠️ Development

### Prerequisites

- Node.js 20+
- pnpm (recommended) or npm
- [Bun](https://bun.sh) (for running tests)

### Setup

```bash
# Clone the repository
git clone https://github.com/MrHacker26/bvm.git
cd bvm

# Install dependencies
pnpm install

# Build the project
pnpm build

# Link for local testing
pnpm link

# Run in development mode
pnpm dev
```

### Scripts

- `pnpm build` - Build the project with tsup
- `pnpm dev` - Run in development mode with tsx
- `pnpm test` - Run unit tests with Bun
- `pnpm clean` - Clean build directory
- `pnpm start` - Run the built CLI
- `pnpm format` - Format code with Prettier
- `pnpm lint` - Lint code with ESLint
- `pnpm lint:fix` - Fix linting issues

---

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Areas where help is needed:

- Testing on Linux (x64, ARM) and macOS (Intel)
- Bug fixes and improvements
- Documentation updates

---

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- Inspired by [nvm](https://github.com/nvm-sh/nvm) and [rvm](https://rvm.io/)
- Built for the amazing [Bun](https://bun.sh) runtime
- Thanks to the TypeScript and Node.js communities

---

## 📞 Support

If you encounter any issues or have questions:

1. Check the [Issues](https://github.com/MrHacker26/bvm/issues) page
2. Create a new issue with details about your environment
3. Include your platform, shell, and any error messages

**Happy Bunning! 🥖✨**