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

> Inspect the active backend, diagnose setup, and manage the CLI

Inspect your CLI setup and manage the local installation.

## msb context

Show the selected backend, API endpoint, and how it was selected. Credentials are not printed. Alias: `msb ctx`.

```bash theme={null}
msb context
msb context --format json
```

## msb install

Install a sandbox as a system command. Creates an executable in `~/.microsandbox/bin/` that launches `msb run` with the specified image and options.

```bash theme={null}
msb install ubuntu                   # Install as 'ubuntu' command
msb install --name nodebox node      # Custom command name
msb install --tmp alpine             # Fresh sandbox every invocation
msb install -c 2 -m 1G python  # With resource limits
msb install --list                   # List installed commands
```

| Flag                                                                                             | Description                                                                                                                                   |
| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `-n`, `--name`                                                                                   | Command name for the alias (defaults to image name)                                                                                           |
| `-c`, `--cpus`                                                                                   | Number of virtual CPUs to allocate                                                                                                            |
| `-m`, `--memory`                                                                                 | Amount of memory (e.g. `512M`, `1G`)                                                                                                          |
| `-v`, `--volume`                                                                                 | Mount a host path or named volume (`SOURCE:DEST[:OPTIONS]`, e.g. `./src:/app:ro,noexec`)                                                      |
| `--mount-dir`                                                                                    | Mount a host directory: `SOURCE:DEST[:OPTIONS]`. Supports `quota` and paired `uid`/`gid`                                                      |
| `--mount-file`                                                                                   | Mount a host file: `SOURCE:DEST[:OPTIONS]`. Supports `quota` and paired `uid`/`gid`                                                           |
| `--mount-disk`                                                                                   | Mount a disk image: `SOURCE:DEST[:OPTIONS]`                                                                                                   |
| `--mount-named`                                                                                  | Create or reuse a named volume: `NAME:DEST[:OPTIONS]`. See [kind, size, and quota options](/cli/volume-commands#using-volumes-with-sandboxes) |
| `--security`                                                                                     | In-guest security profile (`default` or `restricted`)                                                                                         |
| `-w`, `--workdir`                                                                                | Working directory inside the sandbox                                                                                                          |
| `--shell`                                                                                        | Shell for interactive sessions                                                                                                                |
| `-e`, `--env`                                                                                    | Set an environment variable (`KEY=VALUE`)                                                                                                     |
| `-f`, `--force`                                                                                  | Overwrite an existing alias with the same name                                                                                                |
| `--no-pull`                                                                                      | Don't pull the image before installing                                                                                                        |
| `--tmp`                                                                                          | Create a fresh sandbox on every invocation (no persistent state)                                                                              |
| `-l`, `--list`                                                                                   | List all installed sandbox commands                                                                                                           |
| `--conf`                                                                                         | Load an explicit sparse [sandbox configuration](/cli/configuration). Repeatable                                                               |
| `--net-conf`, `--resource-conf`, `--runtime-conf`, `--fs-conf`, `--secret-conf`, `--script-conf` | Load an explicit [scoped config](/cli/configuration#scoped-config-files). Repeatable                                                          |

## msb uninstall

Remove an installed sandbox command.

```bash theme={null}
msb uninstall nodebox
msb uninstall ubuntu alpine   # Remove multiple
```

## msb self

Diagnose, update, downgrade, or remove the CLI. `msb doctor`, `msb update` (alias: `upgrade`), and `msb downgrade` are also available at the top level.

<Accordion title="Examples">
  ```bash theme={null}
  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 check               # Alias for doctor
  msb self update               # Update msb and libkrunfw to latest
  msb self update --force       # Re-download even if up to date
  msb self downgrade 0.6.0      # Downgrade to a supported older release
  msb self downgrade 0.6.0 -y   # Skip downgrade confirmations
  msb self uninstall            # Remove msb (with confirmation prompt)
  msb self uninstall --yes      # Skip confirmation
  ```
</Accordion>

| Subcommand                  | Description                                                                                                                                        |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `doctor` (alias: `check`)   | Check runtime files, supported host virtualization prerequisites, and non-blocking host performance capabilities                                   |
| `update` (alias: `upgrade`) | Update msb and libkrunfw to the latest release and refresh command links                                                                           |
| `downgrade <version>`       | Downgrade msb and compatible local state to a supported older release at or above 0.6.0, refusing unsafe downgrades before touching files or state |
| `uninstall`                 | Remove msb, libkrunfw, and command links                                                                                                           |

`msb self update` always targets the latest release; it does not accept a version argument. Use `msb self downgrade <version>` to move to a supported older release.

Downgrade checks compatibility and requires affected sandboxes to be stopped. Releases below 0.6.0 and irreversible state changes are rejected. Database rollback creates a retained backup unless `--no-backup` is set; affected image caches are cleared unless `--keep-cache` is set.

| Flag            | Subcommand  | Description                                                                                                                                                   |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--fix`         | `doctor`    | Try supported host setup fixes; on Windows this opens an elevated PowerShell prompt to enable Windows Hypervisor Platform without forcing an immediate reboot |
| `-f`, `--force` | `update`    | Re-download even if already on the latest version                                                                                                             |
| `-f`, `--force` | `downgrade` | Accepted for an explicit reinstall request; downgrade always reinstalls the target and this flag does not bypass safety checks                                |
| `-y`, `--yes`   | `downgrade` | Skip destructive-step confirmations                                                                                                                           |
| `--keep-cache`  | `downgrade` | Keep the image cache even when rollback metadata marks it affected                                                                                            |
| `--no-backup`   | `downgrade` | Skip the database backup before rolling back local state                                                                                                      |
| `-y`, `--yes`   | `uninstall` | Skip confirmation prompt                                                                                                                                      |

Doctor reports supported virtualization and storage capabilities. Disabled interrupt acceleration is a performance warning, not a failed health check; doctor does not reload kernel modules.

A temporary clone probe checks whether flat roots can use native copy-on-write. Probe files are removed afterward. See [Performance](/sandboxes/optimization) for details.

See [Performance](/sandboxes/optimization) for interpreting these checks, choosing sandbox-level policies, and preparing the host storage and virtualization environment.