buns

README

buns

Run TypeScript scripts with inline dependencies. No package.json needed.

Inspired by PEP 723 and uv's inline scripts, buns brings the same workflow to TypeScript/JavaScript with automatic Bun version management.

Features

• Inline dependencies - Declare npm packages in script comments, installed automatically
• Bun version management - Pin specific Bun versions per script, downloaded on demand
• Dependency caching - Same packages across scripts share a single cache
• Zero config - No package.json, no tsconfig, just run

Installation

Homebrew (Recommended)

brew install eddmann/tap/buns

Quick Install

curl -fsSL https://raw.githubusercontent.com/eddmann/buns/main/install.sh | sh

Download Binary

# macOS (Apple Silicon)
curl -L https://github.com/eddmann/buns/releases/latest/download/buns-macos-arm64 -o buns
chmod +x buns && sudo mv buns /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/eddmann/buns/releases/latest/download/buns-macos-x64 -o buns
chmod +x buns && sudo mv buns /usr/local/bin/

# Linux (x64)
curl -L https://github.com/eddmann/buns/releases/latest/download/buns-linux-x64 -o buns
chmod +x buns && sudo mv buns /usr/local/bin/

From Source

git clone https://github.com/eddmann/buns
cd buns
make build
make install  # Installs to ~/.local/bin

Quick Start

1. Run a simple script

buns script.ts

2. Add inline dependencies

#!/usr/bin/env buns
// buns
// packages = ["chalk@^5.0"]

import chalk from "chalk";

console.log(chalk.green("Hello from buns!"));

3. Run it

buns script.ts
# Hello from buns!

4. Pin a Bun version

#!/usr/bin/env buns
// buns
// bun = ">=1.0"
// packages = ["zod@^3.0"]

import { z } from "zod";
console.log("Bun version:", Bun.version);

5. Pipe from stdin

echo 'console.log(Bun.version)' | buns run -

Script Metadata

Declare dependencies in a // buns TOML comment block:

#!/usr/bin/env buns
// buns
// bun = ">=1.0"
// packages = ["zod@^3.0", "chalk@^5.0"]

import { z } from "zod";
import chalk from "chalk";

Field	Type	Description
bun	string	Bun version constraint (semver)
packages	string[]	npm packages as name@constraint

Command Reference

buns run

Run a TypeScript/JavaScript script with inline dependencies.

buns run <script.ts> [-- args...]
buns <script.ts> [-- args...]  # Shorthand

Flag	Short	Description
--bun		Bun version constraint (overrides script)
--packages		Comma-separated packages to add
--verbose	-v	Show detailed output
--quiet	-q	Suppress buns output

buns cache

Manage the buns cache.

buns cache list              # Show cached items
buns cache clean             # Remove dependency cache (default)
buns cache clean --bun       # Remove Bun binaries
buns cache clean --deps      # Remove dependencies
buns cache clean --index     # Remove version index
buns cache clean --all       # Remove everything
buns cache dir               # Print cache path

buns version

Print version information.

Examples

The examples/ directory contains progressive examples:

Example	Description
01-hello-world.ts	Simplest script, no dependencies
02-bun-version.ts	Display Bun environment info
03-cli-arguments.ts	Handle command-line arguments
04-single-package.ts	One dependency (chalk)
05-multiple-packages.ts	Multiple dependencies
06-bun-constraint.ts	Require specific Bun version
07-http-client.ts	HTTP requests with native fetch
08-json-processing.ts	JSON processing from stdin
09-cli-app.ts	Full CLI app with @clack/prompts

# Run examples
buns examples/04-single-package.ts
buns examples/09-cli-app.ts
echo '{"test": 123}' | buns examples/08-json-processing.ts -- -

How It Works

Script → Parse metadata → Resolve Bun version → Download Bun (if needed)
                                              → Install dependencies (if needed)
                                              → Execute script

Bun binaries are downloaded from oven-sh/bun releases - official pre-built binaries for all platforms.

Dependencies are installed via Bun into content-addressed cache directories at ~/.buns/deps/{hash}/.

Cache Structure

~/.buns/
├── bun/{version}/bun     # Bun binaries
├── deps/{hash}/          # Script dependencies (node_modules)
└── index/                # Version index (24h TTL)

Development

git clone https://github.com/eddmann/buns
cd buns
make test       # Run tests
make lint       # Run linters
make build      # Build binary
make install    # Install to ~/.local/bin

Credits

• Bun - Fast JavaScript runtime
• oven-sh/bun releases - Bun binary distribution

License

MIT License - see LICENSE for details.