Documentation · Using OSX-REIMS
Commands
Reference for every osx-reims command and its options.
This documentation covers OSX-REIMS 0.6.0, alpha software. Commands and options may change between versions; when in doubt, check osx-reims --help on the installed version.
Without a command, osx-reims opens the console. Everything the menu does is also a command, for those who prefer the terminal or want to automate.
osx-reims [command] [options]Summary
| Command | What it does |
|---|---|
setup |
Prepares the computer: packages, KVM, GPU access, Rust and Reims vGPU |
doctor |
Checks whether the computer is ready, changing nothing |
logs |
Lists the logs of recent runs and how each one ended |
update [file.deb] |
Installs a newer OSX-REIMS from a package you already downloaded |
update-reims |
Updates Reims vGPU to the tested or the latest version and builds it |
rebuild-reims |
Builds Reims vGPU again from scratch, at the same version |
create |
Creates a VM ready to install macOS |
import |
Creates a VM from the QCOW2 disk of a macOS already installed in another VM |
list |
Lists the VMs, the state of each one and the running ones |
start [VM] |
Starts the VM; without a number, asks which one |
stop [VM] |
Asks macOS to shut down and waits |
reset [VM] |
Forces the VM to restart |
poweroff [VM] |
Forces the VM to power off, like pulling the plug (also quit) |
term [VM] |
Terminates the VM process when it does not respond |
delete [VM] |
Deletes a VM that is shut down |
delete --all |
Deletes every VM; all must be shut down |
backup [VM] |
Backs up a VM into a single file (--list, --delete) |
restore [file] |
Restores a VM from a backup: over it or as a new VM |
clean-cache [version] |
Deletes downloaded macOS installers (--all: the whole cache) |
autostart [on|off] |
Whether a VM opens by itself when the computer is turned on |
network |
The VMs' network: NAT or the bridge that gives them an address of their own (bridge on|off) |
help |
Shows the help |
version, --version |
Shows the OSX-REIMS version |
Every command has its own help: osx-reims <command> --help.
Common options
| Option | What it does |
|---|---|
-y, --yes |
Asks nothing: uses the option values or the defaults |
--debug |
Includes the bash trace (set -x) in the log |
-h, --help |
Shows the command's help |
Where [VM] appears, use the VM number (for example, 13) or its folder name (macos-13). The -i <n> option works too.
Every action writes a log to /opt/osx-reims/logs/, with the action, date and time in the file name. The latest one is also available as latest.log.
Preparing the computer
setup
osx-reims setup [options]Prepares the computer: system packages, GPU access, KVM, Rust and Reims vGPU, downloaded into /opt/reims-vgpu and built. Run it as your normal user, without sudo: the administrator password is asked for only in the steps that need it. It is safe to run again, since steps that are already done are skipped. See Installation.
| Option | What it does |
|---|---|
--tested |
Follows the tested Reims vGPU commit (the default) |
--latest |
Follows the latest Reims vGPU commit, not tested |
--reims-ref <ref> |
Uses a Reims vGPU commit, tag or branch (advanced, not tested) |
--accept-license |
Accepts the license without asking (required with -y) |
--rebuild |
Builds Reims vGPU again, even if it is up to date |
--skip-build |
Stops before the build (for testing) |
-y, --yes |
Asks nothing; sudo may still ask for the password |
doctor
osx-reims doctor [options]Checks whether the computer is ready and shows what is wrong and how to fix it. It changes nothing and needs no password. Its log contains no serial numbers or other VM identity data, and it is the one to share when asking for help. See Troubleshooting.
| Option | What it does |
|---|---|
--online |
Also checks the connection to GitHub and to Rust's servers |
Exit code: 0 when no check failed (warnings allowed) and 1 when one failed.
update-reims
osx-reims update-reims [options]Updates Reims vGPU in /opt/reims-vgpu and builds it again, following the version you choose. Without --tested or --latest, it asks which one to follow, offering your current choice. All VMs must be shut down. If the new commit fails to build or to pass the checks, the previous commit is checked out and built again. See Reims vGPU version.
| Option | What it does |
|---|---|
--tested |
Moves to the tested commit and follows it |
--latest |
Moves to the newest commit of master and follows it (not tested) |
--reims-ref <ref> |
Uses a Reims vGPU commit, tag or branch (advanced, not tested) |
-y, --yes |
Asks nothing: keeps the current choice unless an option changes it |
VMs
create
osx-reims create [options]Creates a VM with an empty disk, OpenCore and the macOS installer: the recovery, downloaded from Apple (the installation uses the internet), or a full installer image. Without options, it asks for the values. Every VM gets its own serial number, MLB, UUID, ROM and MAC address. See Your first VM.
| Option | What it does |
|---|---|
-i, --id <n> |
VM number, from 10 to 99 (default: the first free one) |
-m, --macos <name> |
ventura, sonoma, sequoia or tahoe (default: ventura; with --installer, the image's version) |
-s, --disk-size <n> |
macOS disk size, such as 256G or 1T (default: 256G) |
--installer <image> |
Uses a full installer image instead of the recovery |
--redownload |
Downloads the recovery again, even if it is cached |
Example without questions:
osx-reims create -i 11 -m sonoma -s 256G -yimport
osx-reims import [options]Creates a VM from the QCOW2 disk of a macOS already installed in another VM, such as on OSX-PROXMOX, with its own boot disk. The disk is copied into the VM folder: the original file is not changed and can be deleted afterwards. The VM gets a new identity. Without options, it asks for the values. See Importing a VM.
| Option | What it does |
|---|---|
-i, --id <n> |
VM number, from 10 to 99 (default: the first free one) |
-d, --disk <file> |
QCOW2 disk to import |
-m, --macos <name> |
ventura, sonoma, sequoia, tahoe or other: the version shown in the VM list |
-y, --yes |
Asks nothing (requires --disk) |
Example:
osx-reims import -d ~/Downloads/macos.qcow2 -m tahoelist
osx-reims list [--json]Lists the VMs, the state of each one and the running ones. The states are explained in Your first VM. With --json, the same list comes out as a single JSON object, for a program to read, with no colours and no log.
start
osx-reims start [VM] [options]Starts the VM. Without a number, it asks which one; if the chosen VM is already running, it asks what to do with it. On the first start of a VM created with an installer, it opens the macOS installation.
Every setting answered by an option also becomes that VM's saved value. Without options, start shows a summary of what the VM will use and asks only whether to start it, change a setting or cancel. See VM settings.
| Option | What it does |
|---|---|
-r, --ram <n> |
Memory, such as 8G or 16384M (default: the VM's saved value, otherwise 8G) |
-c, --cpus <n> |
Processors, from 1 to 32 (default: the VM's saved value, otherwise 4) |
--opencore <s> |
Which OpenCore starts the VM: image or esp (default: the VM's saved choice, otherwise image) |
--install-esp |
With --opencore esp: when the macOS disk's EFI has no OpenCore, installs the VM's there before starting; an OpenCore already there is used as it is |
--attach-installer |
Attaches the VM's installer again for this start, for an interrupted installation; the disk is kept as it is and the next start is without it |
--fullscreen |
The VM takes the whole monitor, with no Ubuntu behind it |
--windowed |
The VM opens in a normal window (default of both: the VM's saved choice, otherwise a window) |
--x11 |
The VM window opens on X11, through XWayland |
--wayland |
The VM window opens on the session's Wayland (default of both: the VM's saved choice, otherwise the session's server) |
--nested |
macOS can run VMs of its own (Docker, VirtualBox); needs an Intel computer |
--no-nested |
macOS sees a processor with no VT-x (default of both: the VM's saved choice, otherwise off) |
--gpu <s> |
Which GPU runs the VM: auto or the vendor:device ID, such as 1002:73ff (default: the VM's saved choice, otherwise auto) |
--refresh <s> |
macOS's refresh rate: auto (the monitor's) or a rate in Hz, such as 120 (default: the VM's saved choice, otherwise auto) |
--net <s> |
The VM's network: nat or bridge, which needs osx-reims network bridge on (default: the VM's saved choice, otherwise nat) |
--audio |
The VM has sound: macOS's and OpenCore's boot chime |
--no-audio |
The VM has no audio device (default of both: the VM's saved choice, otherwise sound on) |
-n, --dry-run |
Shows the boot command and exits without starting the VM |
-y, --yes |
Asks nothing: uses the options, then what is saved in the VM, then the defaults; without a number, uses the current VM, usually the last one created |
Note
--fullscreen and --windowed, --x11 and --wayland, --nested and --no-nested, --audio and --no-audio are pairs: giving both of a pair is refused. All of these options apply to start only.
While a VM started by start is open, the terminal accepts keys, always pressed twice within 5 seconds:
| Key | What it does |
|---|---|
S |
Asks macOS to shut down |
R |
Forces the VM to restart |
F |
Forces the VM to power off |
T |
Terminates the VM process |
Pressing Ctrl+C twice also asks macOS to shut down. Closing the terminal does not shut the VM down; closing the VM window powers it off at once.
stop, reset, poweroff and term
osx-reims stop [VM] [options]
osx-reims reset [VM] [options]
osx-reims poweroff [VM] [options]
osx-reims term [VM] [options]stopasks macOS to shut down and waits. If macOS does not shut down in time, it asks whether to wait longer, force the VM off or cancel.resetforces the VM to restart.poweroff, orquit, forces the VM to power off, like pulling the plug.termterminates the VM process, for when it does not respond.
Warning
For macOS, reset, poweroff and term are a power cut: anything unsaved is lost. The VM disk stays intact in all three cases.
Without a number and with a single VM running, these commands act on that VM.
| Option | What it does |
|---|---|
--wait <s> |
stop: seconds to wait for macOS (default: 60) |
--pid <n> |
Acts on the QEMU process with that PID (required for VMs outside the VM folder) |
-y, --yes |
Does not ask for confirmation |
delete
osx-reims delete [VM] [options]
osx-reims delete --all [options]Deletes the VM's whole folder, including its disks. Without a number, it asks which one. The VM must be shut down; with --all, every VM must be, otherwise none is deleted. The installer cache is not touched.
Caution
Deleting a VM cannot be undone: the installed macOS and every file inside it are deleted.
| Option | What it does |
|---|---|
--all |
Deletes every VM |
-y, --yes |
Does not ask for confirmation |
backup and restore
osx-reims backup [VM] [options]
osx-reims backup --list [--json]
osx-reims backup --delete [file] [options]
osx-reims restore [file] [options]backup keeps the VM's whole folder — macOS disk, boot disk, firmware settings, identity and settings — in a single file in /opt/osx-reims/backup. The VM must be shut down while it is copied; a running VM is shut down first, if you agree. restore puts a backup back, over the VM it came from or as a new VM. Every option, and what happens in each case, is in Backup and restore.
The VMs' network
network
osx-reims network [status]
osx-reims network bridge on [--port <port>] [-y]
osx-reims network bridge off [-y]With no argument, shows the bridge, the VMs on it and the wired network ports. bridge on puts a wired port of this computer (the one the default route uses, or the one in --port) into the osxbr0 bridge, which takes over the port's address; the bridge comes up with the computer from then on. bridge off gives the port its own settings back and is refused while a VM on the bridge runs. Both ask for the administrator password. See Network.
| Option | What it does |
|---|---|
--port <name> |
bridge on: the wired port to use, such as enp6s0 |
-y, --yes |
Asks nothing |
Logs
logs
osx-reims logs [--json]Lists the logs of recent runs, newest first: when, which action, which VM, how it ended and the file — the same list as the console's View logs. With --json, the list comes out as a single JSON object, for a program to read. It writes nothing.
Updating OSX-REIMS
update
osx-reims update [file.deb] [options]Installs a newer OSX-REIMS from the .deb package you downloaded from the #osx-reims Discord channel. OSX-REIMS downloads nothing: the file is the one you saved. Without a file, it looks for osx-reims_*.deb in your Downloads and Desktop folders, in your home folder and in the current one, and asks which one when there is more than one.
It reads what the file really is (with dpkg-deb, not from its name), refuses another package or another architecture, compares the versions and installs it with apt so the dependencies resolve. An update, a reinstall of the same version and a downgrade are each confirmed in their own words. All VMs must be shut down. It needs neither setup nor an accepted license: a broken environment is a reason to update. See Updating and removing.
| Option | What it does |
|---|---|
--check |
Only says which version is published; installs nothing |
-y, --yes |
Asks nothing, including for a reinstall or a downgrade |
The published version and the SHA-256 of its package are read from UPDATE_CHECK_URL, the only address OSX-REIMS fetches on its own. Because that hash reaches the computer by a different route than the file does, a file that matches it is the one that was published — which the .sha256 saved next to the file cannot show, having come down with it. A file whose version matches the published one but whose hash does not is not installed.
rebuild-reims
osx-reims rebuild-reims [options]Builds QEMU-Reims again, from scratch, at the Reims vGPU commit already on the computer: it is for a build that used to work and stopped working, such as after a system update. Nothing is downloaded or updated — to move to another version, use update-reims. All VMs must be shut down.
The current build is not deleted first: it is moved aside and removed only once the new one passes the checks. If the build or the checks fail, or you interrupt it with Ctrl+C, the previous one goes back in place and the VMs start as before. See Reims vGPU version.
| Option | What it does |
|---|---|
-y, --yes |
Asks nothing |
Starting with the computer
autostart
osx-reims autostart [on|off|status] [VM] [options]Whether a VM opens by itself when the computer is turned on. Without an argument, it says what happens today. Only one VM can have it, and that VM must already have macOS installed. The VM starts with its own saved settings. See VM settings.
| Argument | What it does |
|---|---|
on [VM] |
That VM starts right after you log in to the session; takes autostart off any other VM |
off [VM] |
That VM stops starting by itself; a running VM keeps running |
status |
What starts with the session, and whether the computer logs in by itself |
| Option | What it does |
|---|---|
--login |
Also turns on Ubuntu's automatic login, with no password |
--no-login |
Asks for the password at login again |
-y, --yes |
Asks nothing (--login and --no-login still apply) |
The VM is started by a systemd user service (osx-reims-vm@<VM>.service), which runs with the graphical session: the VM window opens on the session's own screen, so it cannot start before somebody logs in. Automatic login is a setting of Ubuntu itself (/etc/gdm3/custom.conf) and is never changed without being asked for; on the first change, a copy of the file is kept.
Installers
clean-cache
osx-reims clean-cache [version|--all] [options]Deletes the macOS installers stored in /opt/osx-reims/cache/: each version's recovery and interrupted downloads. VMs that were already created are not affected, since each one has its own copy of the installer. The next creation with a deleted version downloads the installer again. Without a version or --all, it lists the cache and asks.
The version is ventura, sonoma, sequoia or tahoe.
| Option | What it does |
|---|---|
--all |
Deletes the whole cache, including the EFI components in cache/third-party/ |
-y, --yes |
Does not ask for confirmation |
Environment variables
The REIMS_ROOT, RAILS_DIR, MACRECOVERY, QMP_TIMEOUT, NO_COLOR and UPDATE_CHECK_URL variables and the /etc/osx-reims.conf file are covered in Advanced configuration.