Command-line reference

This reference describes every pomme command, generated from the help text of pomme 0.1.0 (2cde15f-dirty). To see the same information in a terminal, run pomme help COMMAND or pomme COMMAND --help.

Commands

Command	Description
pomme create	Create a managed macOS VM.
pomme list	List all managed VMs.
pomme start	Start or resume VMs.
pomme stop	Stop VMs.
pomme restart	Restart VMs.
pomme pause	Pause VMs.
pomme resume	Resume paused VMs.
pomme delete	Delete managed VMs.
pomme status	Show VM state.
pomme inspect	Inspect VM configuration and health.
pomme log	View Pomme guest-agent unified logs.
pomme exec	Execute a program in a running VM.
pomme shell	Open a durable guest shell session.
pomme jobs	Manage background guest jobs.
pomme sessions	Manage durable guest terminal sessions.
pomme cp	Copy files between the host and a VM.
pomme cat	Read a guest file through the transfer agent.
pomme sip	Manage System Integrity Protection; repeat the same enable/disable action and --final-state to resume a retained operation.
pomme amfi	Manage AMFI policy and boot-argument configuration; repeat the same enable/disable action and --final-state to resume a retained operation.
pomme mdm	Enroll a VM in MDM from any state: create or finish it, finish retained SIP/AMFI work, prepare only the security enrollment needs, and enroll.
pomme remote-login	Manage Remote Login.
pomme screen-sharing	Manage Screen Sharing. Requires a guest agent with Screen Sharing support.
pomme snapshot	Manage named VM saved-state snapshots.
pomme template	Manage installed macOS templates for fast VM creation.
pomme agent	Inspect, repair, and update Pomme-owned durable agent workflows.
pomme config	Manage VM creation configs.
pomme ipsw	Manage macOS restore images.
pomme ui	Automate the guest through the host display.
pomme tui	Open the interactive terminal UI.
pomme tools	Print command and capability discovery data.
pomme agent-help	Print a compact command inventory for coding agents.

Syntax conventions

The command synopses on these pages use the following conventions.

Convention	Meaning
UPPERCASE	A placeholder that you replace with a value. For example, replace NAME with the name of a VM.
[ ]	An optional argument or flag.
...	An argument that you can repeat. For example, [NAMES ...] accepts one or more VM names.
--	The end of pomme flags. Everything after -- is passed to the guest program.
[FLAGS]	One or more flags described in the command’s flag table.

Common flags

Most commands accept the following flags. A command’s own page lists a flag only when the command gives it a different meaning.

Flag	Description
--format FORMAT	Output format: table, json, or jsonl. Table output is the default. For details, see Structured output.
--json	Print JSON output. Equivalent to --format json.
--debug	Print verbose diagnostics, and keep screenshots of automatic Recovery navigation in a private temporary directory.
--progress PROGRESS	How to show progress on standard error: auto, plain, or off. The default, auto, keeps one updating status line when standard error is a terminal, prints one line per step otherwise, and shows nothing when the output format is JSON or JSONL. plain always prints one line per step. off shows no progress.
-h, --help	Show help for the command.

VM name resolution

Commands that act on a VM take its name as a positional argument. If you omit the name, commands that accept an optional VM name use the value of the POMME_VM_NAME environment variable. Pomme never picks a VM for you, even if only one VM is running. For details, see Environment variables.