Herd Command Line Interface
Herd ships with a powerful CLI that allows you to manage your entire development environment from the terminal. The CLI is also a great tool for AI coding agents that need to interact with your local development setup. You can get the full list of commands by runningherd list in your terminal. Run herd help COMMAND to see all arguments and options of a command.
Many commands support a --json option that prints machine-readable output instead of a table. This is especially useful for scripts and AI agents.
The
status, site:info, site:services, node:list, mail:* and insights:* commands talk to the Herd app and require Herd to be running.Git Bash
If you want to use the Herd binaries in Git Bash, add these aliases to your.bash_profile:
Site Management
herd park
Park a directory so that all its subdirectories become available as.test sites.
herd parked
List all sites within parked paths.herd forget
Remove the current working directory (or a specified directory) from Herd’s list of parked paths.herd link
Register a site outside of a parked path. Supports linking multiple domains to a single application.herd links
Display all linked sites.herd unlink
Remove the configuration for a linked site.herd sites
List all sites that Herd is currently serving.herd paths
Display all registered paths (parked directories).herd open
Open the site for the current (or specified) directory in your browser.herd edit
Open the current directory in your configured IDE.herd site:info
Show everything about a site: its URL, PHP and Node.js versions, the services that its.env file points to, detected capabilities like php artisan dev, Pail or queues, and its workspaces.
herd site:env
Read and edit the.env file of a site. Herd keeps comments and the order of your variables, and quotes values with spaces.
herd site:services
Show or change which service a site uses for its database, queue, cache and broadcasting (Herd Pro). See Per-Site Services.herd site-information
Display information about the specified site as JSON. For Laravel applications, this shows the result ofphp artisan about, but you can replace that with a custom driver.
herd which
Display which Herd driver serves the current working directory. Useful when debugging issues with custom Herd drivers.Herd Studio
herd studio
Open Herd Studio for the current or given site in your browser.Workspaces
Workspaces are isolated copies of a site on their own git branch and domain.herd workspace
Create a new workspace for the site in the current directory. Inside an existing git worktree, this command registers the worktree as a workspace.herd workspaces
List the workspaces of the site in the current directory. Use--site= for another site or --all for the workspaces of all sites.
herd workspace:switch
Switch your terminal to the directory of a workspace. In the Command Prompt, Herd changes the current directory of your session. In PowerShell, Herd prints the path of the workspace so that you cancd into it.
herd workspace:open
Open a workspace in your browser.herd workspace:merge
Merge the branch of a workspace into its base branch. Use--push to push the base branch afterwards and --delete to delete the workspace.
herd workspace:delete
Delete a workspace including its site, certificate and isolated database. The branch stays in your repository.Databases
The database commands use the database connection of the site’s.env file and work with MySQL, MariaDB, PostgreSQL and SQLite.
herd db
Open the database of the current or given site in your database client like TablePlus, using the credentials from the.env file.
herd db:connection
Show the database connection of a site – driver, host, port, database and user – and a ready-to-use connection URL.herd db:list
List all databases on the server that the site uses.herd db:use
Point the site at another database on the same server by updatingDB_DATABASE. If the database doesn’t exist, Herd asks whether to create it. Use --create to create it without asking.
herd db:create
Create a database on the server that the site uses. Without a name, Herd creates the database fromDB_DATABASE. For SQLite, Herd creates the database file.
herd db:drop
Drop a database on the server that the site uses. Herd refuses to drop the database from the site’sDB_DATABASE unless you pass --force.
PHP Version Management
herd use
Change the global PHP version that Herd uses to serve all sites that don’t have an isolated version.herd isolate
Tell Herd to use a specific PHP version for the current directory when serving sites or using theherd composer or herd php commands.
herd unisolate
Revert a site back to Herd’s global PHP version.herd isolated
List all sites using isolated PHP versions.herd php
Proxy PHP commands using the isolated site’s PHP executable.herd composer
Proxy Composer commands using the isolated site’s PHP executable. We recommend setting up a shell alias so that runningcomposer always uses herd composer and picks up the correct PHP version for your site.
herd which-php
Display which PHP binary Herd uses to serve the application at your current terminal path.herd ini
Open thephp.ini file for your current global PHP version in your configured IDE. When running this command in an isolated project path, Herd opens the php.ini for the isolated PHP version.
herd php:list
List all PHP versions and their installation status.herd php:install
Install a PHP version.herd php:update
Update a PHP version to the latest patch release.Node.js Version Management
herd node:list
List the Node.js versions that you installed via Herd’s nvm and the version that your shell currently uses.herd node:install
Install a Node.js version via nvm, or update an installed major version to its latest release.SSL/TLS
herd secure
Generate a trusted TLS certificate for the site in the current directory.herd unsecure
Remove the TLS certificate and the HTTPS redirect from nginx. Make sure to restart your browser session or clear your redirect cache afterwards.herd secured
List all currently secured sites with certificate expiration dates.Proxies
herd proxy
Create an Nginx proxy site for the specified host. Useful for services like Reverb or Docker containers.herd unproxy
Remove an Nginx proxy configuration.herd proxies
Display all configured proxy sites.Services (Herd Pro)
Herd Pro users can manage services like MySQL, PostgreSQL, Redis, and more entirely from the CLI. See Services for more details.herd services:list
List all installed service instances and their current status.herd services:available
List all available service types that can be created.herd services:versions
List all available versions for a service type.herd services:create
Create a new service instance.herd services:start
Start a service instance.herd services:stop
Stop a service instance.herd services:clone
Clone an existing service instance including its data and configuration.herd services:delete
Delete a service and all its data.Mail (Herd Pro)
The mail commands read the mails that Herd’s local mail server captured. They are great for testing sign-up or password-reset flows from the terminal or with an AI agent.mail:list, mail:latest and mail:wait accept filters: --mailbox=, --to=, --from= and --subject=. All filters are case-insensitive, and all except --mailbox match parts of the value.
herd mail:list
List captured mails, newest first. Use--since= to only show mails received after a date or a time like "5 minutes ago", and --limit= to change the number of mails (default 50).
herd mail:show
Show a mail with its sender, recipients, subject, attachments and body as plain text. Use--format=html, --format=raw or --format=json for other formats, and --headers to print all headers.
herd mail:latest
Show the newest mail. This is handy right after an action that sends a mail.herd mail:wait
Wait until a new mail arrives that matches the filters, and show it. Only mails that arrive after you start the command count. The command exits with code 1 after a timeout of 30 seconds, which you can change with--timeout=.
herd mail:links
Print all links of a mail, one per line – for example the verification or password-reset URL.herd mail:attachments
List the attachments of a mail with the path where Herd stored each file.herd mail:attachment
Copy an attachment of a mail into the current directory or the path from--out=.
herd mail:mailboxes
List all mailboxes. A mailbox is the SMTP username that an application used to send the mail.herd mail:delete
Delete a mail and its attachments.herd mail:clear
Delete all captured mails, or only the mails of a mailbox.herd mail:config
Show the host and port of Herd’s mail server and the.env values that an application needs to send mails to Herd.
Insights (Herd Pro)
The insights commands read the runtime context that Herd captured for Insights –dump() and dd() output, queries, logs, jobs, HTTP requests and cache events. By default, they show the entries of the site in the current directory. Use --site= for another site or --all for all sites, and --type= to only show one type like query or log.
herd insights:list
Show the captured entries of a site, grouped by request. Each request starts with a summary line with the route, status, time, number of queries and issues.herd insights:watch
Stream new entries as they arrive. Stop the command withCtrl+C. With --json, Herd prints one JSON object per line.
herd insights:analyze
Find N+1 queries, duplicate queries, slow queries, errors and slow requests, with the file and line and a hint how to fix them. To verify a fix, load the page again and pass the cursor that the previous run printed to--after.
herd insights:clear
Discard the captured entries of the current site, or of all sites with--all.
herd insights:status
Show whether Herd captures runtime context and which sites have captured entries.herd insights:capture
Show whether Herd captures runtime context, or turn capturing on or off.Debugging
herd debug
Proxy PHP commands with the isolated site’s PHP executable and automatically load yourdebug.ini. The debug.ini usually includes Xdebug, so this is how to debug artisan commands from your terminal.
herd coverage
Run PHP commands with Xdebug coverage enabled using the isolated PHP executable.herd debug:start
Start a debug session (Herd Pro).herd debug:stop
Stop a debug session and display the captured data (Herd Pro). Use--json to only print the captured data as JSON.
herd log
Tail log files from Herd. Without arguments, it displays all available log files. Specify a service to tail its logs.herd tinker
Start a Tinker session with your Laravel application. If Herd detects Tinkerwell on your machine, it automatically opens the application in Tinkerwell.Sharing
herd share
Share a local application via an Expose tunnel.herd fetch-share-url
Get the URL to the current Expose share tunnel.Configuration
herd loopback
Get or set the loopback address used for Herd sites.herd directory-listing
Determine directory-listing behavior. Default is off, which means a 404 will display.Core Services
herd status
Show a health check of your Herd setup: the Herd version, the default PHP and Node.js versions, the mail and dump servers, and the state of every service.herd start
Start all Herd services, or one ofnginx, dnsmasq or php.
herd stop
Stop all Herd services – from nginx to all Herd Pro services.herd restart
Restart all Herd services.Initialization & Tooling
herd init
If aherd.yml file is present in the directory, Herd configures your application according to the manifest file. Without a herd.yml, the command starts the wizard to create one.
herd init:fresh
Initialize a freshherd.yml manifest file.