Install Pomme
This page shows you how to install Pomme, keep it up to date, and confirm that your shell runs the installed executable.
Pomme publishes two kinds of builds:
- Stable releases, such as
0.1.0, which Homebrew, the install script, and the installer package install by default. - Alphas, such as
0.1.0-alpha.3. Each change to Pomme’smainbranch that passes CI publishes one.
Choose an install method:
| Method | Installs | Location | Updates with |
|---|---|---|---|
| Homebrew | Stable releases | Homebrew’s bin directory |
pomme update or brew upgrade |
| Install script | Stable releases or alphas | ~/.local/bin/pomme |
pomme update |
| Installer package | Stable releases or alphas | /usr/local/bin/pomme |
pomme update |
| Source | Your checkout | ~/.local/bin/pomme |
Rebuilding |
Before you begin
Section titled “Before you begin”Check that your Mac meets the system requirements: a Mac with Apple silicon and macOS 15 or later. Building from source also needs Xcode and the project’s signing certificate.
Install with Homebrew
Section titled “Install with Homebrew”To install the newest stable release with Homebrew, run the following command:
brew install weswhet/tap/pommeHomebrew installs pomme and its shell completions for zsh, bash, and fish.
The formula installs only stable releases.
Install with the install script
Section titled “Install with the install script”The install script is a Perl program that runs with the Perl that macOS
includes at /usr/bin/perl. To install the newest stable release in
~/.local/bin, run the following command:
curl -fsSL https://pommevm.dev/install.pl | perlTo install the newest alpha instead, set POMME_CHANNEL to alpha:
curl -fsSL https://pommevm.dev/install.pl | POMME_CHANNEL=alpha perlThe script does the following:
- Downloads the release’s
pomme-VERSION-arm64.tar.gzandSHA256SUMSfiles from GitHub, and checks the tarball against the digest inSHA256SUMS. - Checks that the
pommeexecutable has Pomme’s Developer ID signature and reports the expected version. - Copies the executable to
~/.local/bin/pommein one atomic step.
The script doesn’t replace a pomme executable that isn’t signed like Pomme’s
releases, such as a Debug build. Pomme’s Keychain items trust only Pomme’s
Developer ID signature. To replace such an executable, delete it first. The
script doesn’t change your shell startup files. If ~/.local/bin isn’t on
your PATH, the script prints the line to add. For details, see
Add the install directory to your PATH.
Each option has an environment variable, which you set before perl. To pass
an option on the command line instead, put it after perl -, such as
perl - --alpha. Perl treats anything before the - as one of its own
options. The script accepts the following options:
| Environment variable | Option | Description |
|---|---|---|
POMME_VERSION=VERSION |
--version VERSION |
Installs this version, such as 0.1.0-alpha.3. Use it to return to an earlier version. |
POMME_CHANNEL=alpha |
--alpha |
Installs the newest alpha or stable release, whichever is newer. |
POMME_INSTALL_DIR=DIRECTORY |
--install-dir DIRECTORY |
Installs pomme in this directory, which must be an absolute path. The default is ~/.local/bin. |
POMME_PACKAGE=1 |
--package |
Installs with the installer package instead. For details, see the next section. |
To read the script before you run it, download it first:
curl -fsSL https://pommevm.dev/install.pl -o install.plperl install.pl --helpInstall the installer package
Section titled “Install the installer package”The installer package installs pomme at /usr/local/bin/pomme and needs
your administrator password. To download, check, and install the package,
run the following command:
curl -fsSL https://pommevm.dev/install.pl | POMME_PACKAGE=1 perlThe script checks the package against the digest in SHA256SUMS, checks its
Developer ID Installer signature, and then runs sudo installer. To install an
alpha, also set POMME_CHANNEL=alpha.
To check that a downloaded release file came from Pomme’s release workflow,
use gh, the GitHub command-line tool:
gh attestation verify pomme-VERSION-arm64.tar.gz --repo weswhet/pommeBuild from source
Section titled “Build from source”The Scripts/build-local.sh script builds a signed Release executable and
installs it. To build and install Pomme, follow these steps:
-
Clone the Pomme repository, and go to its root directory:
Terminal window git clone https://github.com/weswhet/pomme.gitcd pomme -
Run the build script as your normal user. Don’t use
sudo.Terminal window bash Scripts/build-local.shThe script does the following:
- Builds the
arm64Release configuration withxcodebuild. - Signs the executable with the project’s Developer ID certificate, the
com.github.weswhet.pommesigning identifier, Hardened Runtime, and a secure timestamp. - Verifies the signature, and checks that the only entitlement is
com.apple.security.virtualization. - If a
pommeexecutable is already installed, checks that the new build has the same designated requirement before it replaces the old one. - Keeps a copy of each signed executable, indexed by its SHA-256 digest, so that an interrupted VM creation can resume with the exact agent it started with.
- Copies the executable to
~/.local/bin/pommein one atomic step.
If any check fails, the script stops and leaves the installed executable unchanged.
- Builds the
To install to a different directory, pass an absolute path with
--install-dir:
bash Scripts/build-local.sh --install-dir INSTALL_DIRECTORYReplace INSTALL_DIRECTORY with the absolute path of the directory that
receives the pomme executable.
A build from source can’t update itself. To update it, pull the newest source and run the build script again.
Add the install directory to your PATH
Section titled “Add the install directory to your PATH”If ~/.local/bin isn’t on your PATH, the install script and the build script
print a reminder. To add it for zsh, add the following line to ~/.zprofile,
and then open a new terminal window:
export PATH="$HOME/.local/bin:$PATH"Verify the installation
Section titled “Verify the installation”To confirm that your shell runs the executable you just installed, follow these steps:
-
Check which executable your shell finds:
Terminal window command -v pommeThe output is the path of the installed executable, such as the following:
/Users/USERNAME/.local/bin/pomme -
Check the version:
Terminal window pomme --versionThe output shows the version and the commit that the executable was built from:
pomme 0.1.0-alpha.3 (9122520) -
Optional: list the available commands:
Terminal window pomme --help
Update Pomme
Section titled “Update Pomme”To update Pomme to the newest release, run the following command:
pomme updatePomme updates the same way that you installed it:
| Install method | What pomme update runs |
|---|---|
| Homebrew | brew upgrade weswhet/tap/pomme. |
| Install script | The install script, for the new version and the directory that holds your pomme. |
| Installer package | The install script with --package, which asks for your administrator password. |
| Source | Nothing. The command reports that you need to rebuild Pomme instead. |
An installed alpha updates to the newest alpha or stable release, whichever is newer. A stable release updates only to newer stable releases. After the update, Pomme runs the new executable and checks that it reports the new version.
pomme update updates only the pomme command on your Mac. To give an
existing VM the agent from the new version, see
Update the agent.
Check for an update
Section titled “Check for an update”To check for an update without installing it, run the following command:
pomme update --checkThe output looks similar to the following:
Pomme 0.1.0-alpha.5 is available. You have 0.1.0-alpha.3. To update, run `pomme update`.Release notes: https://github.com/weswhet/pomme/releases/tag/v0.1.0-alpha.5With --format json, the command reports the following fields:
| Field | Description |
|---|---|
installedVersion |
The installed version. After an update, the new version. |
latestVersion |
The newest version that this installation can update to. |
updateAvailable |
true when latestVersion is newer than installedVersion. |
installMethod |
homebrew, standalone for the install script, or package. |
channel |
alpha when the installation follows alphas, otherwise stable. |
updated |
true when the command installed a new version. |
updateCommand |
When an update is available, the command that installs it. |
previousVersion |
After an update, the version that the update replaced. |
Update notices
Section titled “Update notices”About once a day, a release build of Pomme checks for a newer version. When one is available, an interactive command prints a notice on standard error after it finishes:
Pomme 0.1.0-alpha.5 is available. You have 0.1.0-alpha.3. To update, run `pomme update`.The check never delays a command. It runs in a separate background process, and its result appears after a later command. Pomme shows the notice at most once a day for each new version.
Pomme skips the check and the notice in the following cases, so scripts and coding agents never see them:
- Standard error isn’t a terminal.
- The command prints JSON or JSONL output.
- The
CIenvironment variable exists. - You built Pomme from source.
To turn off the check, set POMME_NO_UPDATE_CHECK to 1. Pomme keeps the
result of the check in
~/Library/Caches/com.github.weswhet.pomme/update-check.json.
Keep Keychain access across updates
Section titled “Keep Keychain access across updates”Pomme stores each VM’s agent credential in your login Keychain. macOS grants
Keychain access based on the executable’s code-signing designated requirement,
not on its file hash. Pomme’s releases, Homebrew’s copy, and local builds all
use the same signing identifier, team, and certificate, so an updated or
rebuilt pomme keeps access to the Keychain items that earlier versions
created.
For this reason, don’t substitute an ad hoc, Apple Development, or unsigned build for the installed executable. The Debug build configuration is signed ad hoc and can’t read the credentials of existing VMs.
Uninstall Pomme
Section titled “Uninstall Pomme”To remove the pomme executable, run the command for your install method:
| Install method | Command |
|---|---|
| Homebrew | brew uninstall pomme |
| Install script or source | rm ~/.local/bin/pomme |
| Installer package | sudo rm /usr/local/bin/pomme, and then sudo pkgutil --forget com.github.weswhet.pomme |
Removing the executable doesn’t delete your VMs, templates, or restore images.
Pomme stores them in ~/Library/Application Support/pomme. For the layout of
that directory, see Files and paths.