---
title: CLI overview
"og:title": Microsandbox CLI installation and command reference
sidebarTitle: "Overview"
description: Install the microsandbox CLI and manage local or cloud microVM sandboxes from your terminal.
icon: "book"
---

Run sandboxes locally from your terminal without a cloud account or daemon. When you need hosted compute, set `MSB_BACKEND=remote` and `MSB_API_KEY`, or choose a saved remote profile with `msb context use <name>`. Set `MSB_BACKEND=local` to switch back. See [our managed cloud](/cloud/overview) for setup and pricing.

Interactive sessions are detected automatically; no `-it` flags are needed.

## 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.

<Note>
  Local sandboxes require Linux with glibc 2.28 or newer and KVM, an Apple Silicon Mac, or an x64 or ARM64 machine running Windows 10 or later with Windows Hypervisor Platform enabled. See [Linux troubleshooting](/troubleshooting/linux), [macOS troubleshooting](/troubleshooting/macos), or [Windows troubleshooting](/troubleshooting/windows) for setup help.
</Note>

Check your local setup with:

<CodeGroup>
```bash Shell
msb doctor
```
</CodeGroup>

## Quick start

<CodeGroup>
```bash Shell
msb create python --name worker
msb exec worker -- python -c "print('hello')"
msb stop worker
msb rm worker
```
</CodeGroup>

`msb run` without `--name` creates an ephemeral sandbox, removed when its command finishes. Named sandboxes persist. Names must contain 1–128 UTF-8 bytes.

To reuse sandbox settings, save them in a YAML file named `Sandboxfile` and run `msb run --file Sandboxfile`. See the [Sandboxfile example](/cli/configuration).

## Command forms

Use short commands for everyday work. These forms are equivalent:

<CodeGroup>
```bash Shell
msb run alpine -- echo hello
msb sandbox run alpine -- echo hello
msb sbx run alpine -- echo hello
```
</CodeGroup>

Aliases such as `ls`, `rm`, `cp`, and `mod` also work inside `sandbox` and `sbx`.

Saved-state operations are grouped under `msb snap`. The equivalent long form, `msb snapshot`, is also supported; this documentation uses `msb snap` consistently:

<CodeGroup>
```bash Shell
msb snap create devbox-history --sandbox devbox --name ready --full
msb create --from-snapshot devbox-history --checkpoint ready --name worker
msb snap ls devbox-history
msb snap export devbox-history --checkpoint ready --output ready.msb
msb snap import received --file ready.msb
```
</CodeGroup>

<Accordion title="Snapshot behavior, aliases, and backend support">

Omit `--full` to save disk state for a fresh boot. The first command creates group `devbox-history` and its checkpoint `ready`. Full captures, live forks, groups, and archive operations are local-only. Use `msb fork devbox --names worker-a worker-b` to create children directly from the same live moment. See [Snapshots](/sandboxes/snapshots) for backend limits and resource bindings. Existing top-level `restore` and snapshot `save`/`load` commands remain supported.

</Accordion>

## Quick reference

| Commands | Purpose |
| --- | --- |
| [`run`, `create`, `start`, `stop`, `restart`](/cli/sandbox-commands) | Manage sandbox lifecycles |
| [`exec`, `copy`, `logs`](/cli/sandbox-commands#msb-exec) | Run commands and access files or output |
| [`ls`, `ps`, `inspect`, `metrics`](/cli/sandbox-commands#msb-ls) | Inspect sandboxes |
| [`modify`, `pause`, `resume`, `fork`, `rm`](/cli/sandbox-commands#msb-modify) | Change, fork, or remove sandboxes |
| [`snap`](/cli/snapshot-commands) | Save and restore state |
| [`ssh`](/cli/ssh-commands) | SSH sessions, keys, and listeners |
| [`volume`, `volumes`](/cli/volume-commands) | Manage named storage |
| [`service`](/cli/service-commands) | Give a sandbox port a public URL |
| [`df`, `prune`](/cli/storage-commands) | Inspect local storage and reclaim unused runtime RAM |
| [`pull`, `load`, `save`, `images`, `rmi`, `image`](/cli/image-commands) | Manage cached images |
| [`registry`, `registries`](/cli/registry-commands) | Manage registry credentials |
| [`context`](/cli/management#msb-context) | Inspect the backend, list profiles, or switch your saved preference |
| [`install`, `uninstall`](/cli/sandbox-commands#msb-install) | Turn sandboxes into shell commands |
| [`doctor`, `update`, `downgrade`, `self`](/cli/management#msb-self) | Manage the CLI installation |
| [`completion`](#shell-completion) | Generate shell completions |

## Global options

| Flag | Description |
|------|-------------|
| `--tree` | Display the complete command tree with descriptions |
| `-L, --levels <N>` | Limit tree depth, counting the selected root as level 0 (requires `--tree`) |
| `-C, --commands` | Hide flags and arguments in the command tree (requires `--tree`) |
| `-b, --brief` | Omit descriptions from the command tree (requires `--tree`) |
| `--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 |

## Output formatting

Command results normally go to stdout; progress and diagnostics go to stderr. Use JSON output when a command supports it for scripting.

<Accordion title="Streams, units, and output exceptions">

Progress, styled action confirmations, warnings, and errors go to stderr. Tables, inspection results, and JSON go to stdout. Empty-list messages retain their command-specific behavior: the registry empty-list message goes to stdout, while listing installed aliases produces no output when none exist. The plain `snapshot reindex` completion message also remains on stdout.

Indented output uses two spaces, with nested content at four spaces. Human-readable image, snapshot, and volume sizes use binary units (KiB, MiB, GiB, TiB); JSON retains its documented numeric fields.

</Accordion>

## 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>

Restart your shell. Regenerate saved completions after upgrading.

## Command tree

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

<CodeGroup>
```bash Shell
msb --tree
```
</CodeGroup>

You can scope it to a specific subcommand:

<CodeGroup>
```bash Shell
msb image --tree    # Show only image commands
msb volume --tree   # Show only volume commands
msb run --tree      # Show all flags for run
msb sandbox --tree  # Show the canonical sandbox command group
msb sbx run --tree  # Show run flags through the group alias
```
</CodeGroup>

Limit the depth or hide flags and arguments for a compact command overview:

<CodeGroup>
```bash Shell
msb --tree -L 2
msb --tree --commands
msb image --tree --commands -L 1
msb --tree --brief --commands -L 2
msb --tree -Cb -L 2
```
</CodeGroup>

<Accordion title="Tree depth and display rules">

`-L N` (or `--levels N`) counts the selected root as level 0, so `-L 1` shows its immediate children and `-L 0` shows only the root. Omitting the limit shows all levels. At the depth limit, an inline marker such as `… 4 subcommands, 2 arguments` counts the immediate children that were collapsed; arguments include both flags and positional arguments. Hidden commands and options are excluded, and `--commands` excludes arguments from both the tree and these counts.

`--brief` omits command and argument descriptions and their alignment padding, while retaining names, aliases, value placeholders, and collapse counts. It works with both `-L` and `--commands`.

</Accordion>
