HTTPS & trusted certs

Butler can serve any site over HTTPS with a certificate your browser actually trusts — no red padlock, no “your connection is not private” warning. It does this with its own certificate authority (CA) that’s installed into your Mac’s keychain during setup.

Secure a site

butler secure my-app

That issues a certificate for my-app.test and flips the site to HTTPS. Reload the page and https://my-app.test loads cleanly. Omit the name to secure the site in the current directory:

cd ~/Sites/my-app
butler secure

You can also secure a site from the Sites section of the menu bar app.

Back to plain HTTP

butler unsecure my-app

List secured sites

butler secured

HTTPS modes

By default Butler secures sites individually — a site serves plain HTTP until you butler secure it. You can change that globally from the menu bar app’s Settings → HTTPS Mode:

Mode	What it does
Manual (default)	A site serves HTTP until you secure it explicitly.
Automatic	Every site is secured with its own certificate — no per-site action.

The certificate authority

For browsers to trust Butler’s certificates, Butler’s CA has to be trusted by your system. This happens automatically during butler system install, which is why it prompts for your password once.

If you ever need to install the trust manually — for example after clearing your keychain — run:

butler trust

On a CLI-only install this needs to run under sudo in a terminal so it can add the CA to the system keychain. If you use the app, it can handle the trust prompt for you through the standard macOS security dialog.

Why a private CA?

There’s no public certificate authority that will issue certificates for .test domains, because they never resolve on the public internet. A locally-trusted CA is the standard way tools like Butler provide real HTTPS for local development.

Vite and laravel-vite-plugin

If you use Vite through laravel-vite-plugin, its automatic HTTPS detection (detectTls) works with Butler out of the box — npm run dev serves over https:// using the same certificate as your site, with no vite.config.js changes.

It works because Butler keeps a Valet-shaped home at:

~/Library/Application Support/Butler/Config/valet/
├── config.json            # the active TLD (the plugin reads .tld from it)
├── Certificates/          # <hostname>.crt + .key — the certs `butler secure` issues
├── Sites/                 # one symlink per linked site
└── CA/                    # Butler's certificate authority

The plugin looks for a Valet install at ~/.config/valet, so Butler symlinks that path at its own home:

~/.config/valet → ~/Library/Application Support/Butler/Config/valet

butler system install creates the link, and Butler keeps it pointing at the right place (repairing its own link if it goes stale). The per-site certificates in Certificates/ are the real ones Butler issues — nothing is copied or duplicated, so a cert you create with butler secure is immediately what Vite serves.

Butler never clobbers a real Valet install

If ~/.config/valet is a real directory — an actual Valet install — Butler refuses to touch it and skips the link (you’ll see a warning). Move or remove that directory yourself, then re-run butler system install to create the link. Back it up first:

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

Herd wins this probe

The plugin checks Herd’s config directory before ~/.config/valet. So if Laravel Herd is installed, Vite uses Herd’s certificates even when Butler’s link is perfectly set up. See Running Herd alongside Butler.

Bring your own certificate

If you’d rather use a certificate you already have (say, a wildcard cert), point a site at it in butler.yml instead of using Butler’s CA:

ssl:
  cert: /abs/path/to/site.pem
  key:  /abs/path/to/site-key.pem

Renewing certificates

Butler’s certificates are issued with a limited lifetime. To renew:

butler renew                 # renew site certificates
butler renew --expiring 30d  # only those expiring within 30 days
butler renew --ca            # renew the CA itself

Renewing the CA re-issues the root; you may be prompted to re-trust it.