Installation

Butler runs on macOS (Apple Silicon). There are two ways to install it — pick whichever suits you. Both give you the same butler command; the app additionally gives you the menu-bar dashboard.

Option 1 — The app

The app is the easiest route, and it’s what most people should use. It bundles the butler binary, registers the background services, and can prompt you for the one permission macOS requires.

1. Download Butler.app from getbutler.dev.
2. Drag it to your Applications folder and open it.
3. Follow the first-run onboarding — it picks your web server and PHP version and finishes setup for you.

Allow Butler at login

macOS won’t let Butler bind the web ports (80 and 443) until you allow it in System Settings → General → Login Items & Extensions. Onboarding walks you through this; butler doctor will remind you if it’s still off.

The app keeps itself up to date automatically.

Option 2 — The command line

If you’d rather not install an app, the one-line installer fetches just the butler binary, verifies its checksum, and drops it on your PATH:

curl -fsSL https://getbutler.dev/install.sh | sh

The installer runs butler system install at the end, which registers the background services and prompts once (via sudo) for the DNS resolver, the CA certificate, and the privileged port binder.

You can influence the installer with environment variables:

Variable	Default	Purpose
BUTLER_VERSION	latest	Pin a specific version, e.g. 0.1.0.
BUTLER_INSTALL_DIR	/usr/local/bin	Where the binary lands.
BUTLER_NO_SETUP	—	Set to 1 to skip the butler system install step.

If you skipped that step, run it yourself when you’re ready:

butler system install

You can install the app later on top of a CLI install — it takes over the background services cleanly and adds the menu bar experience.

What butler system install does

butler system install is the one-time bootstrap. It:

• Registers two background jobs — a per-user service that does all the real work, and a small privileged one that binds ports 80 and 443 at login.
• Adds a DNS resolver so *.test addresses resolve to your machine.
• Installs Butler’s certificate authority so HTTPS is trusted (see HTTPS & trusted certs).
• Symlinks the butler command onto your PATH.

It prompts for your password once for the parts that genuinely need it.

Verify it’s working

butler doctor

doctor runs a health check and tells you if anything still needs attention — most commonly the Login Items toggle mentioned above. When it’s happy, you’re ready to link your first site.

Uninstalling

To stop Butler’s background services without removing anything:

butler shutdown

To remove Butler entirely — its services and, optionally, all of its state:

butler system uninstall          # remove the background jobs
butler system uninstall --force  # also wipe Butler's state and downloads

butler uninstall removes a component, not Butler

Top-level butler uninstall <name> is the inverse of butler install <name> — it removes a downloaded component (see Databases & services). The machine-level teardown is butler system uninstall.

If you installed the app, drag it to the Trash afterwards.