Repository files navigation

Creating shell scripts has never been this easy!

Bun Magic simplifies shell scripting by providing a toolkit to create, use and manage scripts.

Bun Magic in 15 secondsThis is how you create ademo command and importcowsay from npm, and deliver an important message via the cow.

• Create new scripts withbunmagic create <script-name>.
• List all known scripts withbunmagic list
• Edit scripts withbunmagic <script-name>
• Use thebuilt-in utilities for common CLI tasks (e.g.,cd,ack,select,isDirectory,ensureDirectory,glob).
• LeverageBun to quickly build powerful scripts using all the features that bun provides - run shell commands, import npm packages, and more.

1. Make sure you haveBun installed:

curl -fsSL https://bun.sh/install | bash

2. Installbunmagic

bunx bunmagic install

3. Reload terminal and runbunmagic for the first time. Done!

Let's create a simple script calledlse.

bunmagic lse# orbunmagic create lse

This will create alse.ts file in bunmagic source directory and link it up as a bin so that you can run it from anywhere aslse command.

Now add in a bit script:

constext=args[0];constls=awaitglob(`*.${ext}`);console.log(ls.join("\n"));

Now you can runlse json to list all the json files in your current directory.

Bunmagic is going to handle creating a binary and making sure it's executable for you.

Available commands:

Bun supports dynamicpackage imports out of the box. So you can use any npm package in your scripts:

importcowsayfrom'cowsay';console.log(cowsay.say({text:'Hello, Bunmagic!'}));

However, there are a few global variables that are useful for writing CLI scripts that come bundled with Bun Magic.

BunShell is already imported as$ globally. Use this to run all your shell commands as you would in Bun.

Arguments passed to the script are available in 3 global variables:

• args - an array of arguments without flags.
• flags - an object with all the flags passed to the script.
• argv - a minimist-like object with all the arguments and flags.

Arguments are parsed bynotMinimist - a tiny utility that's inspired byMinimist, but with a smaller footprint.

Example:

$ example one two --not=false --yes -n 10 --equals is-optional

Produces an object like this:

constargs=["one","two"];constflags={not:"false",yes:true,n:10,equals:"is-optional",}// Minimist-like `argv` object:constargv={_:args  ...flags};

If you need more control over the arguments, you can use theBun.argv array directly and parse the arguments using anynpm package you like.

Using the same shell command above, the output ofBun.argv would be:

console.log(Bun.argv);["/Users/user/.bun/bin/bun","/Users/user/.bun/bin/bunmagic-exec","/Users/user/.bunmagic/default/example.ts","example","one","two","--not=false","--yes","-n","10","--equals","is-optional"]

ansis - is a small library for styling the terminal output. The interface is almost exactly the same as the one inchalk, but it's much smaller and faster:

ansis.red("This is red text");ansis.bold.red.bgGreen("This is bold red text on a green background");

Variable:$HOME

The$HOME global variable is a shortcut foros.homedir(). It holds the absolute path to the current user's home directory.

Interface:resolveTilde(path: string): string

If you need to quickly resolve a path that starts with a tilde (~ ), you can use theresolveTilde function. It replaces the tilde with the absolute path to the current user's home directory.

constresolvedPath=resolveTilde("~/my-file.txt");console.log(resolvedPath);// > /Users/user/my-file.txt

Interface:cd(path: string): void

cd is a wrapper around$.cwd, but it also resolves the tilde (~ ) to the home directory.

// All these are equivalent$.cwd(`${$HOME}/my-folder`)$.cwd(resolveTilde(`~/my-folder`))cd(`~/my-folder`)

A prompt to ask a Yes or No question.

Interface:ack(message: string, default: 'y' | 'n'): Promise<boolean>

Out of the box, Bun providesprompt() andconfirm functions Web APIs.

ack works exactly likeconfirm, but allows you to change the default value toy orn.

Show a selection prompt that allows selecting an option from a list. It's an interactive CLI menu that can be navigated using arrow keys or numbers and has simple fuzzy search built-in.

Interface:select(message: string, options: string[]): Promise<string>

constoptions=["one","two","three"];constselected=awaitselect("Select an option:",options);

If you need to interact with the filesystem a lot,fs-extra is great, but I've only found that often I need only a few key functions.

That's why I've included only a handful of functions that I've found to be the most useful.

Interface:isDirectory(path: string): Promise<boolean>

Due to Bun's ( v1.0.26 ) current limitations in directly checking if a path is a directory, this function utilizes Node.js'sfs.stat method to perform the check. If an error occurs during this process (e.g., if the path does not exist), the promise will resolve tofalse. Otherwise, it resolves based on whether the path points to a directory.

Create a directory (recursively) if it doesn't exist.

Interface:ensureDirectory(path: string): Promise<void>

This function is particularly useful when you need to make sure a directory is present before performing file operations that require the directory's existence.

Interface:glob(pattern: string = '*', options: GlobScanOptions = {}): Promise<string[]> (GlobScanOptions )

This is a shortcut fornew Bun.Glob() that allows you to quickly scan a directory and get a list of files that match a pattern.

Mind The Path:Bun.Glob() usesprocess.cwd() by default. If you change paths during the script,Bun.Glob() will always return the files relative to the original path.glob() will always use the current working directory.

Mind the Performance:glob() is a great quick utility for smaller scripts, but it will scan the entire directory before resolving the promise. If large directories are involved, it's better to usenew Bun.Glob() directly.

If there are any utilities that you'd like to reuse across your Bunmagic scripts, you can add configure them as custom globals.

This is especially useful if you're migrating over fromzx and have a lot of scripts that used some utilities that aren't bundled with Bunmagic, likefs-extra,chalk, etc.

To define custom globals, create a file:~/.bunmagic/custom-globals.ts

In this file, you can export any JavaScript object, function, or variable that you wish to be available globally and it will be assigned toglobalThis in all your scripts.

For example, to makefs-extra available in all your scripts by default, add this to yourcustom-globals.ts:

export*asfsfrom'fs-extra';

bunmagic is going to try to use yourEDITOR environment variable and fall back tocode as the editor when opening script files.

If you're using VSCode must haveVSCode CLI Tools installed for files to be opened automatically in VSCode.

In your shell configuration file, set anEDITOR environment variable:

# In .zshrc or .bashrcexport EDITOR="/usr/bin/vim"

Note:VSCode supports both of these commands and Bunmagic will use them to open either a single script or a script directory:

> code /path/to/scripts/my-script.ts> code /path/to/scripts

If you want your editor to work properly, make sure it can accept both a path to a single script file and a path to a directory.

This project is heavily inspired byzx. It paved the way for a new generation of shell scripting, and Bun Shell made it possible to take it to the next level.

Bun Magic started out aszxb - a project I built to managezx scripts. But. Bun Magic is a love child of zx, zxb and Bun.