Migrating from Valet or Herd

If you’re coming from Laravel Valet, Herd, or DBngin, Butler can import your existing setup so you don’t have to relink everything by hand. Butler also deliberately matches Valet’s command names where it can, so your muscle memory mostly carries over.

Import an existing setup

butler migrate valet      # import from Laravel Valet
butler migrate herd       # import from Herd
butler migrate dbngin     # import databases from DBngin

Narrow what gets imported with a flag:

butler migrate valet --sites      # just the linked/parked sites
butler migrate herd --services    # just the services

Butler reads the other tool’s configuration and recreates the equivalent sites and services on its own stack. Your projects aren’t moved or modified — Butler just starts serving them.

Per-project config compatibility

Butler reads a valet.yml file as a fallback when there’s no butler.yml, so projects that already carry Valet’s per-project config keep working. When you’re ready, run butler init in the project to generate a native butler.yml.

Command familiarity

Many Butler commands mirror Valet’s — link, unlink, park, forget, secure, unsecure, secured, isolate, use, tld, share. Where Butler does something meaningfully different, the command diverges on purpose rather than pretending to be identical. Two to note:

butler install <component> downloads a single service binary (MySQL, Redis, …). It is not Valet’s full-install command — Butler’s machine bootstrap is butler system install.
butler trust installs Butler’s certificate authority (Valet folds this into other commands).

Running Herd alongside Butler

Running Laravel Herd and Butler at the same time is fraught. They’re both trying to be your machine’s local dev environment, and they collide in three ways:

PHP on your PATH — both want to provide php, so which one you get depends on shell ordering.
Ports 80 and 443 — only one process can bind them. Whichever starts first wins; the other fails.
Vite’s HTTPS certificates — the subtle one, below.

butler doctor warns whenever a Herd install is present. It’s an informational notice, not a failure — keeping Herd around is a legitimate choice — but you should run only one of the two at a time.

Herd takes priority for Vite certs

laravel-vite-plugin probes Herd’s config directory before Butler’s ~/.config/valet link. So if this directory exists:

~/Library/Application Support/Herd/config/valet

…Vite reads Herd’s certificates instead of Butler’s — even though Butler’s Valet-compat link is set up correctly and butler doctor’s Valet check is green. The symptom is Vite serving stale or wrong certificates for a site Butler secured.

butler doctor detects this specific case and sharpens its message accordingly.

Fixing it

If you’ve fully moved to Butler, uninstall Herd.app — that’s the cleanest fix.

If you want to keep Herd installed but let Butler drive Vite’s HTTPS, remove just the directory that shadows Butler. Back it up first:

ditto -c -k --keepParent \
  ~/Library/Application\ Support/Herd/config/valet \
  ~/herd-valet-backup.zip
rm -rf ~/Library/Application\ Support/Herd/config/valet

To clear Herd’s entire leftover data directory instead — again, backing up first:

ditto -c -k --keepParent \
  ~/Library/Application\ Support/Herd \
  ~/herd-backup.zip
rm -rf ~/Library/Application\ Support/Herd

Run butler doctor afterwards to confirm the warning is gone.

Backing up Valet’s config

The same advice applies to a real Valet install at ~/.config/valet. Butler never clobbers it — it skips its compatibility link rather than overwrite a directory you own. If you want Butler to own that path, archive and remove it yourself first:

ditto -c -k --keepParent ~/.config/valet ~/valet-config-backup.zip
rm -rf ~/.config/valet
butler system install

That directory holds Valet’s certificates and site config, so keep the archive until you’re sure you’ve migrated everything you need. See Vite and laravel-vite-plugin for what the link does.

See the full CLI reference for everything.