Skip to content
OSX-REIMS
Documentation: Commands

Documentation · Using OSX-REIMS

Commands

Reference for every osx-reims command and its options.

Alpha

This documentation covers OSX-REIMS 0.3.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
update-reims Updates Reims vGPU to the tested or the latest version and builds it
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
clean-cache [version] Deletes downloaded macOS installers (--all: all of them)
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

Lists the VMs, the state of each one and the running ones. The states are explained in Your first VM.

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.

Option What it does
-r, --ram <n> Memory, such as 8G or 16384M (default: 8G)
-c, --cpus <n> Processors, from 1 to 32 (default: 4)
--opencore <s> Which OpenCore starts the VM: image or esp (default: the VM's saved choice, otherwise image)
-n, --dry-run Shows the boot command and exits without starting the VM
-y, --yes Asks nothing; without a number, uses the current VM, usually the last one created

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.

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

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
-y, --yes Does not ask for confirmation

Environment variables

The REIMS_ROOT, RAILS_DIR, MACRECOVERY, QMP_TIMEOUT and NO_COLOR variables and the /etc/osx-reims.conf file are covered in Advanced configuration.