---
title: CLI overview
sidebarTitle: "Overview"
description: Manage sandboxes from the terminal
icon: "book"
---

The `msb` CLI lets you create, manage, and interact with sandboxes from the terminal. It auto-detects TTY and interactivity, so no `-it` flags are needed. If your terminal is interactive, `msb` acts accordingly.

The same CLI drives [microsandbox cloud](/cloud/overview) when an API key is set. A few commands are local-only or limited on cloud, including image-cache commands, `msb metrics`, bounded `msb logs`, `msb ssh serve`, and disk-sized volume creation. Individual pages flag these commands, and the [compatibility matrix](/cloud/compatibility) lists them.

## Install

<CodeGroup>
```bash CLI (Linux & macOS)
curl -fsSL https://install.microsandbox.dev | sh
```

```bash Homebrew (macOS)
brew install superradcompany/tap/microsandbox
```

```powershell CLI (Windows)
irm https://install.microsandbox.dev/windows | iex
```
</CodeGroup>

On Linux and macOS, the install script writes the runtime to `~/.microsandbox/` and creates command links in `~/.local/bin/`. It does not edit shell startup files. If `~/.local/bin` is not on your `PATH`, the installer prints the command to add it. On macOS, Homebrew provides the same CLI through the official tap. On Windows, use PowerShell; Windows support is currently in preview, and Windows 11 is the tested path.

<Note>
  microsandbox requires glibc-based Linux with KVM enabled, macOS with Apple Silicon (M-series chip), or Windows 11 with Windows Hypervisor Platform enabled. Local sandboxes use hardware virtualization. See [Linux troubleshooting](/troubleshooting/linux), [macOS troubleshooting](/troubleshooting/macos), or [Windows troubleshooting](/troubleshooting/windows) for platform-specific notes.
</Note>

Check your local setup with:

```bash
msb doctor
```

## Quick reference

```bash
# Run a one-off command (ephemeral, auto-removed)
msb run python -- python -c "print('Hello!')"

# Interactive shell (auto-detects TTY)
msb run alpine -- sh

# Create a persistent sandbox
msb run --name devbox ubuntu -- bash

# Resume later
msb start devbox

# Execute in a running sandbox
msb exec devbox -- sh -c "apt update && apt install -y cowsay && /usr/games/cowsay \"Hello from devbox\""

# Manage
msb ls                   # List all sandboxes
msb ps                   # Running sandboxes only
msb metrics              # Live CPU/memory/network stats
msb inspect devbox       # Detailed info
msb logs devbox          # Captured stdout/stderr (works on stopped sandboxes too)
msb logs devbox -f       # Follow live
msb stop devbox          # Graceful shutdown
msb rm devbox            # Remove stopped sandbox

# SSH
msb ssh authorize --file ~/.ssh/id_ed25519.pub
msb ssh devbox
msb ssh devbox -- uname -a
msb ssh serve devbox --host 127.0.0.1 --port 2222

# Images
msb pull python       # Pre-pull to cache
msb images            # List cached images
msb rmi python        # Remove a cached image

# Volumes
msb volume create data --size 10G
msb volume ls
msb volume rm data

# Install as a system command
msb install ubuntu       # Install as 'ubuntu' command
msb uninstall ubuntu     # Remove installed command

# Self-management
msb doctor               # Alias for 'msb self doctor'
msb doctor --fix         # Try supported host setup fixes
msb self doctor          # Check runtime files and supported host prerequisites
msb self update          # Update msb to latest
msb self downgrade 0.6.0 # Downgrade to a supported older release
msb self uninstall       # Remove msb

# Shell completion
msb completion zsh       # Print the zsh completion script
```

<Tip>
  Unnamed sandboxes (no `--name` flag) are ephemeral. They're automatically removed when the command finishes. Named sandboxes persist and can be stopped, restarted, and inspected later. Names must be non-empty and no longer than 128 UTF-8 bytes.
</Tip>

## Global options

| Flag | Description |
|------|-------------|
| `--tree` | Display the complete command tree with descriptions |
| `--error` | Show only errors |
| `--warn` | Show warnings and errors |
| `--info` | Show info, warnings, and errors |
| `--debug` | Show debug output |
| `--trace` | Show all output including trace |

## Shell completion

`msb completion <shell>` prints a completion script for `bash`, `zsh`, `fish`, `elvish`, or `powershell`. Write it to the location your shell loads completions from:

<CodeGroup>
```bash bash
# Requires the bash-completion package. Without it, add this line to
# ~/.bashrc instead:  source <(msb completion bash)
mkdir -p ~/.local/share/bash-completion/completions
msb completion bash > ~/.local/share/bash-completion/completions/msb
```

```zsh zsh
mkdir -p ~/.zsh/completions
msb completion zsh > ~/.zsh/completions/_msb
# Add this line to ~/.zshrc before compinit runs:
#   fpath=(~/.zsh/completions $fpath)
```

```fish fish
mkdir -p ~/.config/fish/completions
msb completion fish > ~/.config/fish/completions/msb.fish
```

```elvish elvish
mkdir -p ~/.config/elvish/completions
msb completion elvish > ~/.config/elvish/completions/msb.elv
# Add this line to ~/.config/elvish/rc.elv:
#   eval (slurp < ~/.config/elvish/completions/msb.elv)
```

```powershell PowerShell
$completions = Join-Path (Split-Path $PROFILE) "completions"
New-Item -Path $completions -ItemType Directory -Force | Out-Null
msb completion powershell > (Join-Path $completions "msb.ps1")
# Add this line to your profile ($PROFILE):
#   . "$PSScriptRoot/completions/msb.ps1"
```
</CodeGroup>

Then restart your shell.

## Command tree

Use `--tree` as an alternative to `--help` to see every command, subcommand, and flag at once:

```bash
msb --tree
```

You can scope it to a specific subcommand:

```bash
msb image --tree    # Show only image commands
msb volume --tree   # Show only volume commands
msb run --tree      # Show all flags for run
```

For detailed command reference, see [Sandbox commands](/cli/sandbox-commands), [SSH commands](/cli/ssh-commands), [Volume commands](/cli/volume-commands), and [Image commands](/cli/image-commands). For the SSH model and usage patterns, see [SSH](/sandboxes/ssh).