CLI commands

Everything Butler does is a butler subcommand. Run butler --help for the authoritative, always-current list, or butler <command> --help for a specific command’s flags. Running butler with no arguments is the same as butler status.

Tip

Override the daemon socket Butler talks to with the BUTLER_SOCKET environment variable — rarely needed, but useful for advanced or headless setups.

Status & health

Command	What it does
butler status	Show service status (the default command).
butler doctor	Run health checks and report anything that needs attention.
butler log <name>	Tail a program’s log output.

Machine setup

Butler’s own machine-level lifecycle lives under butler system. (These are distinct from top-level butler install/butler uninstall, which manage downloadable components — see Components & services.)

Command	What it does
butler system install	First-run bootstrap — registers background jobs, DNS, CA and the butler symlink.
butler system install --no-launchd	Write config but don’t install the background jobs (foreground/CI use).
butler system uninstall	Remove Butler’s background jobs.
butler system uninstall --force	Also wipe Butler’s state and downloads.
butler shutdown	Stop Butler’s background jobs (bring them back with butler system install).

Sites

Command	What it does
butler sites	List linked and parked sites.
butler link [path]	Serve a folder as a .test site (defaults to the current dir).
butler unlink [name]	Remove a linked site.
butler park [path]	Auto-serve every subfolder of a directory.
butler forget [path]	Stop auto-serving a parked directory.
butler init [path]	Generate a starter butler.yml (reads valet.yml/.valetrc/herd.yml).

See Linking sites.

HTTPS

Command	What it does
butler secure [name]	Issue a trusted certificate and switch the site to HTTPS.
butler unsecure [name]	Revert a site to HTTP.
butler secured	List sites served over HTTPS.
butler renew	Renew certificates (--expiring 30d, --ca).
butler trust	Install Butler’s certificate authority into the keychain.

See HTTPS & trusted certs.

PHP

Command	What it does
butler use <version>	Set the global default PHP version.
butler isolate <version> [--site <name>]	Pin a PHP version to one site (defaults to the current directory’s site).
butler unisolate <name>	Remove a site’s pinned version.
butler php [...]	Run the active PHP for the current directory.
butler composer [...]	Run Composer through the active PHP.

See PHP versions.

Components & services

Command	What it does
butler install [component...]	Download a component (PHP, MySQL, Redis, …); no args opens an interactive picker.
butler uninstall [component...]	Remove installed components (the inverse of install); no args opens an interactive picker.
butler components	List installed components.
butler component <verb>	Install/list/remove/track/rebuild a component.
butler service <verb> <name>	Add/start/stop/restart/status a service instance.
butler start [name]	Start Butler’s services (bulk-confirms with no name).
butler stop [name]	Stop services.
butler restart <name>	Restart a service.

See Databases & services.

Sharing

Command	What it does
butler share [name]	Put a local site on a public URL (Cloudflare Tunnel or Expose).
butler unshare [name]	Stop sharing.
butler expose [...]	Pass commands straight through to the Expose client.

See Sharing sites publicly.

Domains & migration

Command	What it does
butler tld <suffix>	Change the site TLD (e.g. .test → .dev).
butler migrate <herd|valet|dbngin>	Import an existing setup (--sites, --services).

See The .test domain & DNS and Migrating from Valet or Herd.