msl --help
Every msl command in Terminal.app, grouped the way msl --help prints them.
On this page 8 sections
Type these in Terminal.app. msl --help prints the same list, and msl files opens MSL Files.
Get started#
| Command | Does |
|---|---|
msl | What you have and what to type next |
msl install <distro> | Download a distro, then set up its first instance - name, CPUs, memory and disk |
msl run <instance> | Open a shell. Short form: msl <instance> |
msl run <instance> <command> | Run one command; exits with its exit code, like ssh |
msl run | Open a shell in the instance you used last |
msl -- <command> | Run one command in the instance you used last |
msl distros | Every distro you can install, and which you already have |
msl files | Open MSL Files, to browse your instances from the Mac (also --files) |
msl help | This list, in your terminal |
msl version | Which MSL this is (also --version, -v) |
Shell options#
| Command | Does |
|---|---|
-u, --user <name> | Log in as this user instead of your default account (root is always there) |
-d, --distro <distro> | The distro for a new instance: alpine, debian, ubuntu, kali, arch, fedora, rocky, alma, centos, oracle, opensuse, nix, or custom:<image> |
Instances#
| Command | Does |
|---|---|
msl list | Every instance and whether it's running (also: instances, ls) |
msl list online | Every distro you can install, with its download size |
msl list installed | The distro images already downloaded to this Mac |
msl new [name] [sizes] | Create an instance without opening a shell. No name: asks for name, CPUs, memory and disk |
msl resources [instance] [sizes] | Show or change CPUs, memory and disk (also: config) |
msl storage [instance] [show/fixed <size>/dynamic <size>] | Disk size, and whether its space is reserved on your Mac |
msl status [instance] | Whether an instance is running, paused or off |
msl suspend / resume [instance] | Pause in memory and continue - keeps everything exactly as it is, apps and all |
msl hibernate [instance] | Save to disk and stop. Survives a Mac restart, but Linux apps are closed and reopened - only suspend keeps their windows |
msl --shutdown [instance] | Power off cleanly; every running instance if none is named |
msl snapshot save/restore <instance> <name> | Save or return to a named point |
msl snapshot list [instance] | The snapshots an instance has |
msl forward <instance> <mac port>:<linux port> [--ssh] | Reach a guest's port at localhost on this Mac |
msl forward <instance> list | What is forwarded for an instance |
msl unforward <mac port> | Close a forwarded port |
msl vault <instance> [status/unlock/lock/adopt] | Whose key opens its container, and supply one you hold |
msl protect <instance> | Move its disk into an encrypted container, so a copy of the file is useless |
msl unprotect <instance> | Move it back out, as a plain file |
msl identity [instance] | Where an instance came from - whether it is an original or a copy |
msl rename <instance> <new name> | Give an instance another name, carrying its disk and settings with it |
msl clone <instance> <new name> | Make a second instance from this one - its disk, accounts and settings |
msl remove <instance> [--keep-disk] | Delete an instance. Removing a distro's last instance also deletes its disk |
msl remove-distro <distro> [--yes] | Delete every instance of a distro and its disk |
msl <instance> --shipment [-o FILE] | Package the whole instance into one .mslship file |
msl shipment info <file> | What a shipment contains, without installing it |
msl shipment install <file> [--name N] | Install a shipment as a new instance |
msl lock [instance] [on / off] | Ask for Touch ID or your password before this instance starts |
msl dns [instance] [auto / cloudflare / google / quad9 / <address>] | Which resolver the instance uses for name lookups |
msl vpn [instance] [status / install / remove] | The hide.me VPN client inside one instance; you log in with your own account |
Sizes, for new and resources#
| Command | Does |
|---|---|
--cpus <n> | How many CPU cores the instance gets |
--memory 6G / 2G-8G | A fixed amount, or a range that grows and shrinks with use |
--disk 64G | Disk size; your Mac only gives up space as files are written |
--disk-fixed 64G | Disk size, reserved on your Mac up front |
Linux apps#
| Command | Does |
|---|---|
msl apps list / scan [instance] | The instance's GUI apps; scan reads them again from Linux |
msl apps install <instance> <app> | Make a Mac app for it in ~/Applications/MSL (install-all: every app) |
msl apps uninstall <instance> <app> | Remove that Mac app |
msl apps pin / unpin <instance> <app> | Add or remove its Dock tile |
Connect#
| Command | Does |
|---|---|
msl ssh [instance] [--print] | SSH in, setting access up the first time; --print shows the command |
msl images [list/open] | Your own images in Custom Images; use one with --distro custom:<image> |
msl images new <image> --distro <distro> | Start a custom image as a copy of an installed distro |
msl usb list | USB devices on the Mac: which macOS driver holds each one, and which instance has it |
msl usb attach <device> [instance] | Give that USB device to a running instance. <device> is a location ID or vendor:product from the list. A device macOS has no driver for goes straight through; one it does asks for your password and goes back on detach |
msl usb detach <device> [instance] | Take it back; macOS picks it up again |
msl usb test [instance] | Attach MSL's own virtual test device - checks passthrough works with nothing plugged in |
Maintenance#
| Command | Does |
|---|---|
msl doctor [--fix] | Find leftover state, missing images and uninstalled tools; --fix cleans up |
msl fix-home [instance] [--dry-run] | Give files back to your Linux account after apps that ran as root left root-owned files behind |
msl keyboard [--keysyms] | The Mac keyboard layout, and what Linux apps see |
msl kitty [on / off / <words>] | The cat at the top of every shell, with the greeting under her. With words, she says them in a speech bubble instead; on and off decide whether she turns up in shells |
msl greeter [on / off] | The greeting line under the shell banner |
msl update [--download / --install] | Check for a newer MSL; download it to your Downloads, or download it and replace this one |
msl install-tools | From a build: install msl and mslhd into Application Support |
msl uninstall [--everything] [--dry-run] | Remove MSL and keep your Linux; --everything deletes that too |
msl help [--no-app] | This help, and MSL Help in the app; --no-app just prints |
Experimental and debugging#
| Command | Does |
|---|---|
msl gui-native <instance> [app] | Run a Linux app on MSL's own display server |
msl gui <instance> [app] | Run a Linux app through XQuartz |
msl cage-view <instance> [app] | A Wayland (cage) session in a Mac window |
msl cage-bridge-test / cage-input-test <instance> | Wayland frame and input round-trip checks |
msl power-test <event> | Replay a power event: sleep, shutdown, logout, lowbattery, wake, battery... |