Bots and scripts
Some Crawlers send robots into the dungeon instead of going themselves. The System respects the hustle. This guide shows you how to call Pomme from shell scripts, CI jobs, and coding agents. It covers machine-readable output, exit codes, command discovery, and how to run commands without interactive prompts. The viewers find scripts dull to watch. Scripts don’t care.
Before you descend
Section titled “Before you descend”- Install Pomme. For details, see Install Pomme.
- To follow the examples, install jq, a command-line JSON processor.
Request structured output
Section titled “Request structured output”Most commands accept --format with one of the following values:
| Value | Output |
|---|---|
table |
Human-readable text. This is the default. |
json |
One JSON object. |
jsonl |
One JSON object per line. For list commands, each item is its own line. |
--json is a shorthand for --format json.
For example, to print the names of running VMs, run the following:
pomme list --json | jq -r '.vms[] | select(.vmState == "running") | .name'To print each installed template with its macOS version and build, run the following:
pomme template list --json \ | jq -r '.templates[] | "\(.name)\t\(.version)\t\(.build)"'With --format jsonl, pomme list writes one VM per line, which works well
with line-oriented tools:
pomme list --format jsonl | jq -r '.name'Result objects include ok, which is true on success, and most include
hostExitCode, the exit status that the command returns. When a command acts
on several VMs, JSON output wraps the per-VM results:
{ "ok": true, "results": [ { "name": "dev-a", "ok": true, "vmState": "stopped", "hostExitCode": 0 }, { "name": "dev-b", "ok": true, "vmState": "running", "hostExitCode": 0 } ]}For the fields that each command returns, see Structured output.
Control the progress display
Section titled “Control the progress display”Long-running commands, such as pomme create and pomme ipsw download, show
their progress on standard error, so it never mixes with the results on
standard output. On an interactive terminal, one status line shows a small
square whose dots fill in and empty as they swirl around it, changing color
with each lap. The elapsed time follows the square, and then the VM name and
the current step. Restore-image downloads and macOS installation also show a
percentage. The System is very proud of the little square. Please admire it.
To choose how progress appears, pass --progress with one of the following
values:
| Value | Display |
|---|---|
auto |
The default. Animates the status line on an interactive terminal. When standard error isn’t a terminal, or TERM is dumb, prints one line per step instead. |
plain |
Prints one line per step, without animation. |
off |
Hides progress. Warnings and errors still appear. |
With --format json or --format jsonl, Pomme hides progress unless you pass
--progress plain. With --debug, Pomme prints one line per step along with
its diagnostics. To turn off color, set the NO_COLOR environment variable. In
a locale that doesn’t use UTF-8, Pomme draws progress with ASCII characters.
Pomme prints a notice about a newer release only when standard error is a terminal and the output is a table, so scripts and JSON consumers never receive it. For details, see Update notices.
Check exit codes
Section titled “Check exit codes”Test the exit status of every command, Crawler. Robots that ignore exit codes walk straight into the spike pit. Pomme uses the following conventions:
0means success.1means the command failed. Pomme printsError:, a message, and an error code to standard error. With--format jsonor--format jsonl, standard output also contains a failed result with the same code in itserrorCodefield.64means the arguments were invalid, for example a missing VM name.- For
pomme exec, a guest program’s exit code passes through. A program ended by a signal returns128plus the signal number, a foreground timeout returns124, and an interrupted foreground command returns130.
For the full list, see Exit codes.
The following example stops a script when a VM doesn’t exist:
if ! pomme status "$VM" --json > status.json; then echo "Pomme could not read the status of $VM" >&2 exit 1fiMatch on error codes
Section titled “Match on error codes”Every failed result carries an errorCode, such as vm-not-found or
guest-agent-unavailable, that doesn’t change between releases. Match on the
code rather than on the message text, which can change. The System rewrites
its insults all the time. The codes stay put. The following example waits and
retries while the guest agent connects:
until pomme exec "$VM" --json -- /usr/bin/true > result.json; do code=$(jq -r '.errorCode' result.json) case "$code" in guest-agent-unavailable|guest-agent-connecting) sleep 5 ;; *) echo "pomme failed with $code" >&2; exit 1 ;; esacdoneFor every code, see Errors. The hint field
holds the next step, and causes holds the underlying operating-system or
framework reasons.
Set a default VM
Section titled “Set a default VM”Commands that take an optional VM name use the POMME_VM_NAME environment
variable when you omit the name. Pomme never picks a VM for you, even if only
one VM is running. Mind reading costs extra, and nobody’s paying.
export POMME_VM_NAME=devpomme statuspomme exec -- /usr/bin/sw_versFor details, see Environment variables.
To act on every VM instead, pass --all (-a) to pomme stop, pomme pause,
pomme resume, or pomme delete. Each command selects only the VMs that it
applies to; for example, pomme stop --all stops the running and paused VMs.
When no VM matches, the command exits with status 0 and, with --json,
prints an empty results array. For details, see
Act on every VM.
Avoid interactive prompts
Section titled “Avoid interactive prompts”Some commands ask for confirmation in a terminal. When standard input isn’t a
terminal, these commands fail instead of waiting. Add --force (-f) to
confirm in advance:
| Command | Effect of --force |
|---|---|
pomme delete, pomme rm |
Deletes without prompting, and stops a running VM first. With --all, deletes every VM. |
pomme template delete |
Deletes the template without prompting. |
pomme snapshot delete |
Deletes the snapshot without prompting. |
pomme snapshot restore |
Restores without prompting and accepts recorded drift. |
pomme sip, pomme amfi, pomme mdm |
Allows creating the owner account on a verified fresh VM. |
Without --force and without a terminal, a deletion fails with the following
error:
Deletion requires an interactive terminal. Pass -f/--force to delete without prompting.The following commands always need a terminal and don’t have a
non-interactive form: pomme tui, pomme config init, pomme shell without
--detach, pomme exec --pty, and pomme sessions attach. To run a
terminal program from a script, create a detached session with
pomme exec --pty --detach and read its output with pomme sessions logs. For
details, see Use durable terminal sessions.
For owner credentials in security workflows, set both POMME_AUTHORIZED_USER
and POMME_AUTHORIZED_PASSWORD, or store the VM-scoped credential in your
login Keychain. For details, see
Change SIP and AMFI.
Repeat commands to resume work
Section titled “Repeat commands to resume work”Pomme’s long-running workflows are journaled. If one stops partway, run the same command again to continue from the first unfinished step. Think of it as a checkpoint that you didn’t have to earn:
| Workflow | How to resume |
|---|---|
| VM creation | pomme create VM_NAME --resume |
| SIP or AMFI change | Repeat the same enable or disable command with the same --final-state. |
| MDM enrollment | Repeat the same pomme mdm command with the same profile, --enrollment-mode, and --final-security. |
Commands whose request is already satisfied don’t change the VM. For example,
pomme agent repair exits with status 0 when the agent is already healthy,
and pomme agent update exits with status 0 and reports "updated": false
when the agent already matches the host build.
This makes it safe to retry these commands in automation. Retry all you like.
The ratings can’t drop any further during a no-op.
Discover commands
Section titled “Discover commands”Two commands describe the command-line tool without needing a VM:
pomme toolslists the command groups and the UI automation capabilities of this build.pomme agent-helpprints a compact command inventory for coding agents.
Both accept --format table|json|jsonl. Their JSON output is the same; with
--format jsonl, they write one command group per line:
pomme tools --format jsonl{"name":"vm","commands":["create","list|ls","start","stop","restart","pause","resume","delete|rm","status","inspect","snapshot","template","firmware"]}{"name":"agent","commands":["agent status","agent repair","agent update"]}{"name":"guest","commands":["exec","shell","log","jobs","sessions","cp","cat","install"]}...Give a coding agent the output of pomme agent-help so that it knows which
commands exist, then let it read pomme help COMMAND for details. It’s the
dungeon map, Crawler. Hand it to your robot before you send it in.