Skip to content
Butler

Linking sites

Butler serves projects from folders on your Mac. Point it at a directory and it becomes a .test site — no virtual hosts to edit, no restarts.

Section titled “Link a single project”

From inside a project folder:

Terminal window
cd ~/Sites/my-app
butler link

Or name the path explicitly:

Terminal window
butler link ~/Sites/my-app

Either way the folder is served at http://my-app.test (the site name is the folder name). Butler inspects the project and picks the right handling automatically — it recognizes Laravel, WordPress, Symfony, Drupal, Statamic and Craft, and falls back to sensible defaults for a plain PHP or static site. Open it right away:

Terminal window
open http://my-app.test

To give the site a different name, link from a folder of that name or set it in butler.yml.

Park a directory of projects

Section titled “Park a directory of projects”

If you keep all your projects under one parent folder, park it once and every subfolder becomes a site automatically:

Terminal window
butler park ~/Sites

Now ~/Sites/blog is blog.test, ~/Sites/api is api.test, and any new folder you create there is served without another command. Stop parking a directory with butler forget.

See what’s linked

Section titled “See what’s linked”
Terminal window
butler sites

This lists both individually linked sites and everything picked up by parked directories, along with each one’s address and PHP version. The Sites section of the menu bar app shows the same information with buttons for the common actions.

Remove a site

Section titled “Remove a site”
Terminal window
butler unlink my-app      # remove a single linked site
butler forget ~/Sites     # stop auto-serving a parked directory

Unlinking only removes the mapping — your project files are never touched.

Configure a site

Section titled “Configure a site”

Most projects need no configuration. When one does — a specific PHP version, a non-standard public directory, environment variables, a database, or reverse-proxy mode for a JS dev server — drop a butler.yml file at the project root. It’s the per-project override for everything Butler does. See the full butler.yml reference.

~/Sites/my-app/butler.yml
php: "8.3"
webserver: caddy
publicPath: public
env:
  APP_DEBUG: "true"

Initialize config interactively

Section titled “Initialize config interactively”

To generate a starter butler.yml (also reading any existing valet.yml, .valetrc or herd.yml):

Terminal window
butler init          # in the current project
butler init ~/Sites/my-app

Next steps

Section titled “Next steps”