---
title: CLI management
"og:title": Microsandbox CLI setup and management commands
sidebarTitle: "Management"
description: Inspect the active backend, diagnose runtime setup, and manage the microsandbox CLI installation.
icon: "wrench"
---

For first-time installation, see the [CLI overview](/cli/overview#install).

<a id="msb-install" className="msb-moved-command" href="/cli/sandbox-commands#msb-install">The msb install reference has moved to Sandbox commands.</a>
<a id="msb-uninstall" className="msb-moved-command" href="/cli/sandbox-commands#msb-uninstall">The msb uninstall reference has moved to Sandbox commands.</a>

## msb context

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

<CodeGroup>
```bash Shell
msb context
msb context --format json
msb context list
msb context use work
msb context reset
```
</CodeGroup>

| Subcommand | Purpose |
| --- | --- |
| `list` | List profiles, the selected profile, and whether each backend is allowed |
| `use <name>` | Save an existing profile as your preference |
| `reset` | Remove your saved preference |

All forms accept `--format json`. Listing and preference changes do not resolve credentials, contact cloud, or open the sandbox database. Incomplete or prohibited profiles remain visible. Plain `msb context` resolves the backend and reports configuration or credential errors.

Environment variables and managed selection can override your saved preference; the command warns when they do. `reset` leaves those overrides and backend restrictions in effect. Add profiles in [config.json](/configuration#profiles); there is no `context add` command.

An invalid configuration or empty backend allowlist stops these commands. To recover from a user restriction that leaves no usable profile, edit `allowed_backends` in your config file. For managed restrictions, contact your administrator.

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

<CodeGroup>
```bash Shell
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
```
</CodeGroup>

</Accordion>

| Subcommand | Description |
|------------|-------------|
| `doctor` (alias: `check`) | Check runtime files, supported host virtualization prerequisites, and non-blocking host performance capabilities |
| `repair [--sandbox SANDBOX]` | Inspect and repair legacy sandbox storage. In a terminal, omit `--sandbox` to select multiple sandboxes |
| `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.

Run downgrade from the newer CLI before replacing it: the older binary does not contain rollback steps for newer migrations. If you already installed an older binary and see `database schema is newer than this msb binary`, follow the [catalog recovery steps](/migrations/v0.7#database-schema-is-newer-than-this-msb-binary). [Snapshot groups can also block downgrade](/migrations/v0.7#snapshot-groups-can-block-downgrade).

Only one downgrade can run per installation. A second command fails immediately; wait for the first to finish or cancel it before retrying.

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.

### Check sandbox storage

`msb doctor --sandbox app` inspects storage for one local sandbox. Use `msb doctor --all` to inspect every sandbox in the configured home. Add `--format json` for automation. These checks read storage metadata and leave VMs running. Bare `msb doctor` checks the host. Positional sandbox names remain supported for both diagnosis and repair.

Storage checks exit with `0` for ready or eligible storage, `2` for a blocker or incomplete migration, `3` when a sandbox could not be inspected, and `1` for a command-level failure. Results for running sandboxes are provisional.

Run `msb self repair --sandbox app` in a terminal when the report calls for repair, or omit `--sandbox` to select multiple sandboxes. The picker hides verified-ready sandboxes by default; press `r` to show them. Repair imports supported storage without asking you to choose disk versions, asks before stopping a blocking VM, and reports each sandbox's result. Unresolved cases offer a diagnostic report to review and copy for the maintainers; nothing is uploaded automatically. Safety confirmations are interactive. For JSON output limits and macOS maintenance requirements, see [sandbox storage migration](/migrations/sandbox-storage).

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