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 [name]	Serve the current folder as a .test site (named after the folder unless you pass a name).
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.

Node, Python & Ruby

Each language’s versions are managed by a component you install once — fnm for Node, uv for Python, rv for Ruby. Butler passes through to each, so you never need them on your PATH separately.

Command	What it does
butler fnm [...]	Run fnm — install, list or default a Node version.
butler node [...]	Run node at the version resolved for this directory.
butler uv [...]	Run uv — Python versions, virtualenvs, project management.
butler rv [...]	Run rv — Ruby versions.
butler shell install	Put the whole toolchain on your PATH, with per-directory switching.
butler which	Show Butler’s paths (config, components, data, run, logs).

With shell integration installed, node, npm, npx, python, python3, pip, venv, ruby, bundle, gem, rake, irb, pnpm and composer are on your PATH directly — as real files, so editors, build scripts and git hooks resolve the same versions your terminal does. butler doctor reports what each one resolves to.

See Node.js versions, Python versions and Ruby 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.