> ## Documentation Index
> Fetch the complete documentation index at: https://superradcompanyinc-mintlify-8d0a72e9.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI overview

> Manage sandboxes from the terminal

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 [cloud compatibility section](/cloud/overview#compatibility) summarizes them.

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

## Quick reference

```bash theme={null}
# 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
msb volumes              # Also: msb vols
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 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>

Then restart your shell.

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

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