> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI overview

> Install the microsandbox CLI and manage local or cloud microVM sandboxes from your terminal.

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

Set an API key to use [microsandbox cloud](/cloud/overview). Each reference page marks local-only commands and cloud limitations.

## Install

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

  ```bash Homebrew (macOS) theme={null}
  brew install superradcompany/tap/microsandbox
  ```

  ```powershell CLI (Windows) theme={null}
  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:

```bash theme={null}
msb doctor
```

## Command forms

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

```bash theme={null}
msb run alpine -- echo hello
msb sandbox run alpine -- echo hello
msb sbx run alpine -- echo hello
```

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:

```bash theme={null}
msb snap create ready --sandbox devbox --full
msb snap restore devbox:ready --name worker
msb snap ls --group devbox
msb snap export devbox:ready --output ready.msb
msb snap import ready.msb --group received
```

Omit `--full` to save disk state for a fresh boot. The group defaults to the source sandbox's name, so the first command creates `devbox: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.

## 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 |
| [`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) | Show the active backend |
| [`install`, `uninstall`](/cli/management#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 |

## Quick start

```bash theme={null}
msb create python --name worker
msb exec worker -- python -c "print('hello')"
msb stop worker
msb rm worker
```

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

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

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.

## 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 theme={null}
  # 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 theme={null}
  mkdir -p ~/.zsh/completions
  msb completion zsh > ~/.zsh/completions/_msb
  # Add this line to ~/.zshrc before compinit runs:
  #   fpath=(~/.zsh/completions $fpath)
  ```

  ```fish fish theme={null}
  mkdir -p ~/.config/fish/completions
  msb completion fish > ~/.config/fish/completions/msb.fish
  ```

  ```elvish elvish theme={null}
  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 theme={null}
  $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:

```bash theme={null}
msb --tree
```

You can scope it to a specific subcommand:

```bash theme={null}
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
```

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

```bash theme={null}
msb --tree -L 2
msb --tree --commands
msb image --tree --commands -L 1
msb --tree --brief --commands -L 2
msb --tree -Cb -L 2
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.