Installation & Quick Start

Install the app

1. Open the downloaded .dmg and drag BitL into Applications.
2. Launch BitL. It lives in the menu bar (look for the B icon) — there is no Dock icon by default.
3. BitL is signed with an Apple Developer ID and notarized by Apple, so it opens normally — no right-click or Open Anyway step needed.

First launch

The welcome screen installs three things, then asks for your administrator password once:

• nginx web server
• dnsmasq plus /etc/resolver/test, so every *.test name resolves to 127.0.0.1
• a default PHP runtime (8.5)

It also registers BitLHelper, a small privileged helper. After this one approval BitL can start services, write resolver files and update the CLI without prompting again. When you see “You're all set!”, the core stack is running and .test domains are live.

The bitl CLI

The helper installs the CLI to /usr/local/bitl/bin/bitl and symlinks it to /usr/local/bin/bitl, which is already on the default macOS PATH. Check it:

bitl --versionbitl doctor

bitl doctor checks PHP, nginx, dnsmasq, the .test resolver, ports, BitL's directories, installed services and the local CA, and prints a fix for anything that fails. Want tab completion?

bitl completions install        # detects zsh, bash or fish

To use BitL's PHP, Composer and other binaries directly in your shell (for example php artisan without the bitl prefix), put BitL's bin directory on your PATH:

bitl php path --check   # is it already set up?bitl php path --install    # append it to ~/.zshrcsource ~/.zshrc

Quick start

1. 1

   Link a project

   From the project directory — or click + in the Sites list:

   cd ~/Sites/my-laravel-appbitl link

   The site is now at http://my-laravel-app.test. BitL detects Laravel, Symfony, Statamic, WordPress and static sites and serves the right document root automatically.

2. 2

   Turn on HTTPS

   bitl secure

   BitL issues a certificate from its own local CA. The first time, it may print a one-line sudo security add-trusted-cert … command — run it once so browsers trust every BitL certificate from then on.

3. 3

   Add a database

   bitl services install mysqlbitl services start mysqlbitl env-sync            # writes DB_HOST, DB_PORT, … into .env

   BitL services use non-standard ports (MySQL on 3360) so they never fight a Homebrew or Docker install. env-sync takes care of the details.

4. 4

   Open it

   bitl open

Start a new project

bitl new scaffolds a project in the current directory and links it in one go:

cd ~/Sitesbitl new laravel shop       # → ~/Sites/shop, served at shop.testbitl new wordpress blogbitl new static landing

Coming from Laravel Herd or Valet

BitL imports linked sites, parked directories, SSL certificates and per-site PHP isolations.

bitl migrate                   # detect a Herd or Valet installbitl migrate herd --dry-run    # preview, change nothingbitl migrate herd              # importbitl migrate valet             # same, from Valet

Add --force to overwrite configuration BitL already has. Projects with a herd.yml keep working — see herd.yml support.

Updates & uninstall

The app updates itself (Settings → Updates). The CLI can also update on its own:

bitl self-update --check     # just lookbitl self-update             # install the latest releasebitl self-update --beta      # include pre-releasesbitl self-update --rollback  # go back one version

To remove BitL completely, quit the app, delete it from Applications, then: