Skip to content
Documentation: Commands

Documentation · Using OSX-REIMS

Commands

Reference for every osx-reims command and its options.

Alpha

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 -y

import

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 tahoe

list

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]
  • stop asks 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.
  • reset forces the VM to restart.
  • poweroff, or quit, forces the VM to power off, like pulling the plug.
  • term terminates 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.