cli

package
v1.22.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 27, 2026 License: MIT Imports: 68 Imported by: 0

Documentation

Index

Constants

View Source 
const MaxRemoteSetupFailures = 10

MaxRemoteSetupFailures is the number of wrong-code attempts that wipe the active token and force the user to generate a fresh one. The token's 8-character alphabet has ~55^8 ≈ 8 × 10^13 possible values, so 10 attempts is effectively zero brute-force progress — this lock is defense in depth, not a tight bound.

View Source 
const TinkerOutputSeparator = "\x1e"

TinkerOutputSeparator is the marker we inject between top-level statements so the frontend can split a single tinker run into one output block per statement. ASCII 0x1e (record separator) — unlikely to appear in user output, easy to escape inside a PHP double-quoted string as `\x1e`.

Variables

View Source 
var AfterWorkerMigration func()

AfterWorkerMigration is invoked once when the migration loop ends, regardless of success. The UI uses it to resume the cache poller it paused in BeforeWorkerMigration.

View Source 
var BeforeWorkerMigration func(units []string)

BeforeWorkerMigration is invoked once at the start of a worker-mode migration with the unit names about to be touched. The UI registers a callback that cancels any open `podman logs -f` SSE streams for those units and pauses the container-state cache poller, so the migration's stop/rm/start podman calls don't compete with the daemon's own podman connections for gvproxy connection slots. nil on the CLI path (no UI streams to cancel, no cache poller running).

View Source 
var SupportedPHPVersions = []string{"7.4", "8.0", "8.1", "8.2", "8.3", "8.4", "8.5"}

SupportedPHPVersions lists the PHP versions lerd can build FPM images for. 7.4 and 8.0 are a frozen legacy tier for old projects: still buildable from Alpine 3.16, but pinned (older xdebug, no mongodb ext) and not security-updated.

Functions

func ApplyAutostart added in v1.9.0 

func ApplyAutostart(disabled bool) error

ApplyAutostart writes the new flag to config.yaml, rewrites every lerd-*.container quadlet on disk so its [Install] section is present (when enabled) or absent (when disabled), runs `systemctl --user daemon-reload`, then enables/disables (and starts/stops) every lerd-* systemd user service. Safe to call when the flag is already in the requested state — every step is idempotent.

Exposed (capitalised) so the UI server can call it directly without duplicating the orchestration; the tray and CLI go through the same path.

func ApplyWorkersMode added in v1.19.0 

func ApplyWorkersMode(newMode string) error

ApplyWorkersMode is the exported wrapper around applyWorkersMode used by the dashboard handler so the web toggle drives the same migration path as the CLI. emit may be nil when called from the CLI; the streaming path is only used by the dashboard for live progress.

func ApplyWorkersModeStreaming added in v1.19.0 

func ApplyWorkersModeStreaming(newMode string, emit func(WorkerModePhaseEvent)) error

ApplyWorkersModeStreaming is the streaming variant called by the web dashboard. Emits phase events at every meaningful step so the modal shows "Stopping lerd-horizon-parkapp", "Starting lerd-schedule-frontend", etc. rather than a blank spinner for the whole migration.

func ApplyWorktreeBuildChoice added in v1.20.0 

func ApplyWorktreeBuildChoice(site *config.Site, worktreePath string, choice worktreeBuildChoice, log io.Writer)

ApplyWorktreeBuildChoice acts on a worktreeBuildChoice: starts the asset worker (kind "worker"), runs `npm run <value>` (kind "script"), or does nothing (kind "skip"). Progress is written to log (may be nil).

func ApplyWorktreeDBChoice added in v1.20.0 

func ApplyWorktreeDBChoice(site *config.Site, branch, choice string, log io.Writer) error

ApplyWorktreeDBChoice configures the worktree's database for branch per choice: "share"/"" (no isolation), "empty" (isolated empty schema), "reset" (drop any preserved isolated DB first, then empty schema), "reuse" (reconnect to a preserved isolated DB without touching its data), "clone-main", or "clone-<branch>". Progress is written to log (may be nil).

func AutoStartOptedInWorktreeWorkers added in v1.20.0 

func AutoStartOptedInWorktreeWorkers(site *config.Site, worktreePath, phpVersion string)

AutoStartOptedInWorktreeWorkers writes (and starts, on Linux) every host worker the user opted into via the parent's .lerd.yaml workers list, scoped to the given worktree path. Idempotent — used by the watcher's onAdded hook AND by the daemon's boot-time scanWorktrees pass so per-worktree units survive a daemon restart cleanly. Errors are surfaced as warnings so a single broken unit doesn't block siblings.

func AvailableBuildScripts added in v1.20.0 

func AvailableBuildScripts(worktreePath string) []string

AvailableBuildScripts returns the production-build-style scripts declared in package.json, in preference order. `dev` is intentionally excluded — it's a long-running watcher, not a one-shot the wrapper should spawn.

func ClearRemoteSetupToken added in v1.8.0 

func ClearRemoteSetupToken() error

ClearRemoteSetupToken removes the on-disk token file.

func CloneDatabase added in v1.19.0 

func CloneDatabase(svc, src, dst string) error

CloneDatabase copies the schema and data from src into dst inside the same service container. dst must already exist. Returns an error if the family has no clone strategy or the dump/restore fails.

func CollectRunningWorkerNames added in v1.5.0 

func CollectRunningWorkerNames(site *config.Site) []string

CollectRunningWorkerNames returns the names of active workers for the site, including stripe. Used to sync .lerd.yaml.

func CreateDatabase added in v1.19.0 

func CreateDatabase(svc, name string) (bool, error)

CreateDatabase is the exported variant of createDatabase. Used by callers outside the cli package (e.g. the worktree DB-isolation flow).

func DisableLANExposure added in v1.8.0 

func DisableLANExposure(progress LANProgressFunc) error

DisableLANExposure flips lerd back to the safe loopback default. Inverts EnableLANExposure: rewrites every container PublishPort to bind 127.0.0.1, stops the dns-forwarder, reverts dnsmasq to answer with 127.0.0.1, and revokes any outstanding remote-setup token (a code is only useful while the LAN forwarder is running). progress receives one event per step; pass nil for the silent path. Idempotent.

func DropDatabase added in v1.19.0 

func DropDatabase(svc, name string) (bool, error)

DropDatabase delegates to serviceops.DropDatabase for cli-package callers.

func DropOrphanedWorktreeDBs added in v1.19.0 

func DropOrphanedWorktreeDBs(site *config.Site)

DropOrphanedWorktreeDBs scans the registry for orphaned worktree state (LAN shares first, isolated databases last) and tears it down. Database drop is intentionally the LAST step so any earlier failure (LAN proxy stop, daemon notify, registry write) leaves the data intact and the user can recover by re-adding the worktree without losing migrations or seed data.

func DropOrphanedWorktreeLANShares added in v1.19.0 

func DropOrphanedWorktreeLANShares(site *config.Site, liveBranches map[string]bool)

DropOrphanedWorktreeLANShares removes registry entries and stops proxies for worktrees that no longer exist. Notifies the daemon over HTTP first so the close happens in lerd-ui's process where the listener actually lives; the watcher process's lanShareServers map is empty so a direct close would leave the listener bound. Falls back to in-process close + registry remove if the daemon is unreachable.

func EligibleBuildReplacers added in v1.20.0 

func EligibleBuildReplacers(site *config.Site, path string) []string

EligibleBuildReplacers returns every framework worker eligible to provide assets at the given path: replaces_build:true, per_worktree:true (when path is a worktree), and Check rule matches. Unlike OptedInBuildReplacers it does NOT require the worker to be in the parent's .lerd.yaml workers: list, so the worktree-add prompt can offer asset workers the user hasn't explicitly opted into yet.

func EnableLANExposure added in v1.8.0 

func EnableLANExposure(progress LANProgressFunc) (lanIP string, err error)

EnableLANExposure flips lerd from the safe-on-coffee-shop-wifi default (everything bound to 127.0.0.1) to LAN-exposed mode. Concretely:

  • persists cfg.LAN.Exposed=true so reinstalls and reboots restore the state
  • regenerates every installed lerd-* container quadlet via WriteQuadlet, which centrally rewrites PublishPort= lines to drop the loopback prefix
  • daemon-reloads systemd and restarts each rewritten container
  • rewrites the dnsmasq config to answer *.test queries with the host's LAN IP and restarts lerd-dns
  • installs and starts the userspace lerd-dns-forwarder.service that bridges LAN-IP:5300 → 127.0.0.1:5300 (rootless pasta cannot accept LAN-side traffic on its own, so a host-side forwarder is required)

progress, if non-nil, is invoked after each step so the caller can stream feedback to a user (e.g. NDJSON over HTTP for the dashboard). Idempotent: safe to call repeatedly.

func FindListenerCmd added in v1.19.1 

func FindListenerCmd(port string) string

FindListenerCmd returns the platform-appropriate shell command the user can run to identify the process bound to the given TCP port. The CLI/UI surfaces it in conflict hints so users don't have to know that ss is Linux-only and lsof is the macOS equivalent.

func FindParentSiteForWorktree added in v1.19.0 

func FindParentSiteForWorktree(dir string) (*config.Site, string, bool)

FindParentSiteForWorktree looks up the registered site whose worktrees contain dir. Returns (site, branch, true) on a match, otherwise (_, _, false).

func GenerateRemoteSetupToken added in v1.8.0 

func GenerateRemoteSetupToken(ttl time.Duration) (string, error)

GenerateRemoteSetupToken creates a fresh one-time setup code, persists it with the given TTL, and returns the code. Used by both the `lerd remote-setup` cobra command and the dashboard UI's loopback-only generate endpoint, so they share the exact same token format and storage path.

func HealSummary added in v1.19.0 

func HealSummary(r HealResult) string

HealSummary is the CLI-facing alias for workerheal.Summary.

func HealUnit added in v1.19.0 

func HealUnit(unit string) error

HealUnit is the CLI/UI-facing alias for workerheal.HealUnit.

func HorizonStartForSite added in v1.0.0 

func HorizonStartForSite(siteName, sitePath, phpVersion string) error

HorizonStartForSite starts Horizon for the named site. Conflicting workers (defined via ConflictsWith in the framework definition) are stopped first.

func HorizonStopForSite added in v1.0.0 

func HorizonStopForSite(siteName string) error

HorizonStopForSite stops and removes the Horizon unit for the named site.

func InstallPresetByName added in v1.9.0 

func InstallPresetByName(name, version string) (*config.CustomService, error)

InstallPresetByName is a thin wrapper around serviceops.InstallPresetByName kept for the existing call sites in cli (init wizard, link, web UI handler).

func IsMCPGloballyRegistered added in v1.1.0 

func IsMCPGloballyRegistered() bool

IsMCPGloballyRegistered reports whether lerd is registered with Claude Code. Uses `claude mcp get lerd` which returns exit 0 when the server is known and exit 1 otherwise. The older `claude mcp list --scope user` flag form breaks on newer Claude CLI releases.

func LANShareEnsurePort added in v1.13.0 

func LANShareEnsurePort(siteName string) (int, error)

LANShareEnsurePort assigns a stable port to the site if not already set and saves it to sites.yaml. It does NOT start the proxy — that is the daemon's job. CLI commands use this to persist the port, then notify the daemon via its API.

func LANShareRefreshIfRunning added in v1.20.2 

func LANShareRefreshIfRunning(siteName string) error

LANShareRefreshIfRunning closes any running share proxy for the site and re-opens it using the current site config — needed when TLS gets toggled (the proxy was bound to the previous backend port and Secured flag). No-op when no proxy is running. Also refreshes any worktree shares so the branch listeners pick up the same change.

func LANShareRunning added in v1.13.0 

func LANShareRunning(siteName string) bool

LANShareRunning reports whether a share proxy is active for the site.

func LANShareStart added in v1.13.0 

func LANShareStart(siteName string) (int, error)

LANShareStart starts the in-process reverse proxy for the site. It is intended to be called from the daemon (UI server) only — the proxy goroutine lives in the daemon process. CLI commands should notify the daemon via its HTTP API instead of calling this directly.

func LANShareStartWorktree added in v1.19.0 

func LANShareStartWorktree(siteName, branch string) (int, error)

LANShareStartWorktree starts the LAN share proxy for a worktree and persists its port. The proxy targets <branch>.<parent_domain> so nginx routes to the worktree's vhost. Idempotent.

func LANShareStop added in v1.13.0 

func LANShareStop(siteName string) error

LANShareStop stops the LAN share proxy for the site and clears its port from the site registry.

func LANShareStopServer added in v1.19.0 

func LANShareStopServer(siteName string)

LANShareStopServer closes the running proxy without clearing the site's stored LAN port. Used when pausing a site so the same port can be reused on unpause without invalidating any QR codes the user has shared.

func LANShareStopWorktree added in v1.19.0 

func LANShareStopWorktree(siteName, branch string) error

LANShareStopWorktree stops the proxy and clears the registry entry.

func LANShareURL added in v1.13.0 

func LANShareURL(lanPort int) string

func LANShareWorktreeRunning added in v1.19.0 

func LANShareWorktreeRunning(siteName, branch string) bool

LANShareWorktreeRunning reports whether a worktree share proxy is bound.

func ListVendorBins added in v1.7.0 

func ListVendorBins(cwd string) []string

ListVendorBins returns the names of executable files in <cwd>/vendor/bin, sorted alphabetically. Returns an empty slice if the directory doesn't exist.

func MissingPresetDependencies added in v1.9.0 

func MissingPresetDependencies(svc *config.CustomService) []string

MissingPresetDependencies is a thin wrapper around the serviceops helper.

func NewAboutCmd added in v1.0.0 

func NewAboutCmd() *cobra.Command

NewAboutCmd returns the about command.

func NewAutostartCmd added in v0.3.0 

func NewAutostartCmd() *cobra.Command

NewAutostartCmd returns the autostart command with enable/disable subcommands.

"Autostart" governs whether lerd comes up at login as a single switch: every lerd-* container quadlet, the lerd UI, the watcher, and every per-site worker/queue/schedule/horizon/reverb/stripe unit are enabled or disabled together. The state lives in cfg.Autostart.Disabled (zero value = enabled, so existing installs are unchanged) and is the canonical source of truth — `IsAutostartEnabled` reads it directly.

The toggle only affects what happens at the next login. Toggling to off does NOT stop currently-running services, and toggling to on does NOT start anything — the user is in the middle of working and a session-level switch should not yank infrastructure out from under them. Disabling does two things:

  1. Strips the [Install] section from every lerd-*.container quadlet on disk so the podman-system-generator stops emitting the `default.target.wants/<name>.service` symlink on the next daemon-reload. This is the only way to actually stop a quadlet from auto-starting; `systemctl --user disable` is a no-op for generator units.
  2. Runs `systemctl --user disable` on every lerd-*.service file (lerd-ui, lerd-watcher, every per-site worker/queue/schedule/ horizon/reverb/stripe), removing the `default.target.wants` symlink without touching the running unit.

Enabling reverses both steps. To actually stop or start a running environment use `lerd stop` / `lerd start` — those are the live-state commands.

func NewBugReportCmd added in v1.19.0 

func NewBugReportCmd() *cobra.Command

NewBugReportCmd returns the bug-report command. It writes a single plain-text file aggregating the diagnostics a maintainer needs to triage a GitHub issue: doctor output, config files, systemd/podman state, recent logs, network state, and a curated set of environment variables.

func NewCheckCmd added in v1.5.0 

func NewCheckCmd() *cobra.Command

NewCheckCmd returns the check command.

func NewComposerCmd added in v1.21.1 

func NewComposerCmd() *cobra.Command

NewComposerCmd returns the composer command. It runs `php composer.phar` inside the project's FPM container (so composer always has the matching PHP runtime) and, after the command exits, syncs `composer global` binaries from `$COMPOSER_HOME/vendor/bin/` into lerd's bin dir as wrapper scripts, so globally required packages like psy/psysh or laravel/installer become callable from the host shell on every supported platform.

func NewConsoleCmd added in v1.2.0 

func NewConsoleCmd() *cobra.Command

NewConsoleCmd returns the console command — runs framework console in the project's container.

func NewDBIsolateCmd added in v1.19.0 

func NewDBIsolateCmd() *cobra.Command

NewDBIsolateCmd returns the `lerd db:isolate` command.

func NewDBShareCmd added in v1.19.0 

func NewDBShareCmd() *cobra.Command

NewDBShareCmd returns the `lerd db:share` command (the off side of db:isolate).

func NewDNSForwarderCmd added in v1.8.0 

func NewDNSForwarderCmd() *cobra.Command

NewDNSForwarderCmd returns the hidden `lerd dns-forwarder` command that runs the userspace UDP+TCP relay used by `lerd lan:expose` to bridge LAN traffic to the rootless lerd-dns container. lan:expose internally needs this to make .test resolution work for remote machines.

Why this exists: rootless podman + pasta cannot accept inbound packets on the host's LAN interface — pasta only intercepts loopback traffic via the host's /proc/net tables, and binding to a LAN-facing socket requires CAP_NET_RAW which rootless containers don't have. Without a userspace helper, `lan:expose` would only work for clients on the server itself.

The forwarder runs as a systemd user service alongside lerd-watcher and lerd-ui, listening on <lan-ip>:5300 (UDP+TCP) and relaying every packet to 127.0.0.1:5300 where pasta does intercept correctly. The lerd binary owns this subcommand so users don't need socat or any other system tool.

func NewDashboardCmd added in v0.8.0 

func NewDashboardCmd() *cobra.Command

NewDashboardCmd returns the dashboard command.

func NewDbCmd added in v0.4.0 

func NewDbCmd() *cobra.Command

NewDbCmd returns the db parent command with import/export/create/shell subcommands.

func NewDbCreateCmd added in v0.5.1 

func NewDbCreateCmd() *cobra.Command

NewDbCreateCmd returns the standalone db:create command.

func NewDbExportCmd added in v0.4.0 

func NewDbExportCmd() *cobra.Command

NewDbExportCmd returns the standalone db:export command.

func NewDbImportCmd added in v0.4.0 

func NewDbImportCmd() *cobra.Command

NewDbImportCmd returns the standalone db:import command.

func NewDbRestoreCmd added in v1.22.0 

func NewDbRestoreCmd() *cobra.Command

NewDbRestoreCmd returns the standalone db:restore command.

func NewDbShellCmd added in v0.5.1 

func NewDbShellCmd() *cobra.Command

NewDbShellCmd returns the standalone db:shell command.

func NewDbSnapshotCmd added in v1.22.0 

func NewDbSnapshotCmd() *cobra.Command

NewDbSnapshotCmd returns the standalone db:snapshot command.

func NewDbSnapshotRmCmd added in v1.22.0 

func NewDbSnapshotRmCmd() *cobra.Command

NewDbSnapshotRmCmd returns the standalone db:snapshot:rm command.

func NewDbSnapshotsCmd added in v1.22.0 

func NewDbSnapshotsCmd() *cobra.Command

NewDbSnapshotsCmd returns the standalone db:snapshots command.

func NewDoctorCmd added in v0.9.0 

func NewDoctorCmd() *cobra.Command

NewDoctorCmd returns the doctor command.

func NewDomainCmd added in v1.5.0 

func NewDomainCmd() *cobra.Command

NewDomainCmd returns the domain command with add/remove/list subcommands.

func NewDumpCmd added in v1.20.0 

func NewDumpCmd() *cobra.Command

NewDumpCmd returns the parent `lerd dump` command. Subcommands toggle the dump bridge, tail received dumps, and inspect state.

func NewEnvCheckCmd added in v1.5.0 

func NewEnvCheckCmd() *cobra.Command

NewEnvCheckCmd returns the env:check command.

func NewEnvCmd added in v0.3.0 

func NewEnvCmd() *cobra.Command

NewEnvCmd returns the env command.

func NewEnvRestoreCmd added in v1.13.0 

func NewEnvRestoreCmd() *cobra.Command

NewEnvRestoreCmd returns the env:restore command.

func NewFetchCmd added in v0.4.0 

func NewFetchCmd() *cobra.Command

NewFetchCmd returns the fetch command.

func NewFrameworkCmd added in v1.0.0 

func NewFrameworkCmd() *cobra.Command

NewFrameworkCmd returns the framework parent command with subcommands.

func NewHorizonCmd added in v1.0.0 

func NewHorizonCmd() *cobra.Command

NewHorizonCmd returns the horizon parent command with start/stop subcommands.

func NewHorizonStartCmd added in v1.0.0 

func NewHorizonStartCmd() *cobra.Command

NewHorizonStartCmd returns the standalone horizon:start command.

func NewHorizonStopCmd added in v1.0.0 

func NewHorizonStopCmd() *cobra.Command

NewHorizonStopCmd returns the standalone horizon:stop command.

func NewImportCmd added in v1.13.0 

func NewImportCmd() *cobra.Command

NewImportCmd returns the import parent command with source subcommands.

func NewInitCmd added in v1.2.0 

func NewInitCmd() *cobra.Command

NewInitCmd returns the init command.

func NewInstallCmd 

func NewInstallCmd() *cobra.Command

NewInstallCmd returns the install command.

func NewIsolateCmd 

func NewIsolateCmd() *cobra.Command

NewIsolateCmd returns the isolate command.

func NewIsolateNodeCmd 

func NewIsolateNodeCmd() *cobra.Command

NewIsolateNodeCmd returns the isolate:node command.

func NewLANCmd added in v1.8.0 

func NewLANCmd() *cobra.Command

NewLANCmd returns the `lerd lan` parent command. Subcommands flip lerd between the safe-on-coffee-shop-wifi default (everything bound to 127.0.0.1) and the LAN-exposed state (containers bound to 0.0.0.0, dnsmasq answering with the LAN IP, lerd-ui on 0.0.0.0:7073). The previous standalone `lerd dns:expose` flag was folded in here because there is no meaningful state where the DNS resolver answers the LAN but the actual services don't.

func NewLANExposeCmd added in v1.8.0 

func NewLANExposeCmd() *cobra.Command

NewLANExposeCmd returns the `lerd lan:expose` colon-style alias.

func NewLANShareCmd added in v1.13.0 

func NewLANShareCmd() *cobra.Command

NewLANShareCmd returns the `lerd lan:share` colon-style alias.

func NewLANStatusCmd added in v1.8.0 

func NewLANStatusCmd() *cobra.Command

NewLANStatusCmd returns the `lerd lan:status` colon-style alias.

func NewLANUnexposeCmd added in v1.8.0 

func NewLANUnexposeCmd() *cobra.Command

NewLANUnexposeCmd returns the `lerd lan:unexpose` colon-style alias.

func NewLANUnshareCmd added in v1.13.0 

func NewLANUnshareCmd() *cobra.Command

NewLANUnshareCmd returns the `lerd lan:unshare` colon-style alias.

func NewLinkCmd 

func NewLinkCmd() *cobra.Command

NewLinkCmd returns the link command.

func NewLogsCmd added in v0.1.17 

func NewLogsCmd() *cobra.Command

NewLogsCmd returns the logs command.

func NewMCPCmd added in v0.3.0 

func NewMCPCmd() *cobra.Command

NewMCPCmd returns the mcp command — starts the MCP server over stdio.

func NewMCPEnableGlobalCmd added in v1.1.0 

func NewMCPEnableGlobalCmd() *cobra.Command

NewMCPEnableGlobalCmd returns the mcp:enable-global command.

func NewMCPInjectCmd added in v0.3.0 

func NewMCPInjectCmd() *cobra.Command

NewMCPInjectCmd returns the mcp:inject command.

func NewManCmd added in v1.0.0 

func NewManCmd() *cobra.Command

NewManCmd returns the man command.

func NewMinioMigrateCmd added in v1.0.2 

func NewMinioMigrateCmd() *cobra.Command

NewMinioMigrateCmd returns the minio:migrate command.

func NewNewCmd added in v1.1.0 

func NewNewCmd() *cobra.Command

NewNewCmd returns the new command — scaffold a new PHP project.

func NewNodeCmd added in v0.1.16 

func NewNodeCmd() *cobra.Command

NewNodeCmd returns the node command.

func NewNodeInstallCmd added in v0.5.9 

func NewNodeInstallCmd() *cobra.Command

NewNodeInstallCmd returns the node:install command.

func NewNodeUninstallCmd added in v0.5.9 

func NewNodeUninstallCmd() *cobra.Command

NewNodeUninstallCmd returns the node:uninstall command.

func NewNodeUseCmd added in v0.6.0 

func NewNodeUseCmd() *cobra.Command

NewNodeUseCmd returns the node:use command.

func NewNotifyCmd added in v1.21.0 

func NewNotifyCmd() *cobra.Command

NewNotifyCmd returns the parent `lerd notify` command. Subcommands flip the global notification toggle (dashboard banners + Web Push fanout) and report current status.

func NewNpmCmd added in v0.1.16 

func NewNpmCmd() *cobra.Command

NewNpmCmd returns the npm command.

func NewNpxCmd added in v0.1.16 

func NewNpxCmd() *cobra.Command

NewNpxCmd returns the npx command.

func NewOpenCmd added in v0.3.0 

func NewOpenCmd() *cobra.Command

NewOpenCmd returns the open command.

func NewParkCmd 

func NewParkCmd() *cobra.Command

NewParkCmd returns the park command.

func NewPauseCmd added in v1.0.0 

func NewPauseCmd() *cobra.Command

NewPauseCmd returns the pause command.

func NewPhpCmd added in v0.1.16 

func NewPhpCmd() *cobra.Command

NewPhpCmd returns the php command — runs PHP in the appropriate FPM container.

func NewPhpExtCmd added in v0.5.5 

func NewPhpExtCmd() *cobra.Command

NewPhpExtCmd returns the php:ext parent command.

func NewPhpIniCmd added in v0.5.5 

func NewPhpIniCmd() *cobra.Command

NewPhpIniCmd returns the php:ini command.

func NewPhpListCmd 

func NewPhpListCmd() *cobra.Command

NewPhpListCmd returns the php:list command.

func NewPhpRebuildCmd added in v0.1.17 

func NewPhpRebuildCmd() *cobra.Command

NewPhpRebuildCmd returns the php:rebuild command.

func NewPhpShellCmd added in v1.0.1 

func NewPhpShellCmd() *cobra.Command

NewPhpShellCmd returns the shell command — opens an interactive sh session in the PHP-FPM container.

func NewProfileCmd added in v1.22.0 

func NewProfileCmd() *cobra.Command

NewProfileCmd returns the parent `lerd profile` command. Subcommands turn the global SPX profiler on and off, show its state, and open its web UI.

func NewQueueCmd added in v0.3.0 

func NewQueueCmd() *cobra.Command

NewQueueCmd returns the queue parent command with start/stop subcommands.

func NewQueueStartCmd added in v0.3.0 

func NewQueueStartCmd() *cobra.Command

NewQueueStartCmd returns the standalone queue:start command.

func NewQueueStopCmd added in v0.3.0 

func NewQueueStopCmd() *cobra.Command

NewQueueStopCmd returns the standalone queue:stop command.

func NewQuitCmd added in v0.7.0 

func NewQuitCmd() *cobra.Command

NewQuitCmd returns the quit command.

func NewRebuildCmd added in v1.15.0 

func NewRebuildCmd() *cobra.Command

NewRebuildCmd returns the rebuild command.

func NewRemoteControlCmd added in v1.8.0 

func NewRemoteControlCmd() *cobra.Command

NewRemoteControlCmd returns the `lerd remote-control` parent command with on / off / status subcommands. Controls whether the lerd dashboard at http://<server>:7073 accepts requests from non-loopback (LAN) sources.

State machine (single field, presence of cfg.UI.PasswordHash):

  • empty: loopback only — LAN sources get 403 Forbidden
  • present: loopback bypasses, LAN sources must present HTTP Basic auth

The `/api/remote-setup` bootstrap endpoint is not affected by this gate (it has its own token + IP + brute-force gate). Loopback always bypasses both states so the local user can never lock themselves out of their own machine.

func NewRemoteControlOffCmd added in v1.8.0 

func NewRemoteControlOffCmd() *cobra.Command

NewRemoteControlOffCmd returns the `lerd remote-control:off` colon alias.

func NewRemoteControlOnCmd added in v1.8.0 

func NewRemoteControlOnCmd() *cobra.Command

NewRemoteControlOnCmd returns the `lerd remote-control:on` colon alias.

func NewRemoteControlStatusCmd added in v1.8.0 

func NewRemoteControlStatusCmd() *cobra.Command

NewRemoteControlStatusCmd returns the `lerd remote-control:status` colon alias.

func NewRemoteSetupCmd added in v1.8.0 

func NewRemoteSetupCmd() *cobra.Command

NewRemoteSetupCmd returns the `lerd remote-setup` command — generates a one-time code that authorizes a single laptop to call /api/remote-setup and provision itself against this lerd instance.

func NewRestartCmd added in v1.15.0 

func NewRestartCmd() *cobra.Command

NewRestartCmd returns the restart command.

func NewReverbCmd added in v0.8.0 

func NewReverbCmd() *cobra.Command

NewReverbCmd returns the reverb parent command with start/stop subcommands.

func NewReverbStartCmd added in v0.8.0 

func NewReverbStartCmd() *cobra.Command

NewReverbStartCmd returns the standalone reverb:start command.

func NewReverbStopCmd added in v0.8.0 

func NewReverbStopCmd() *cobra.Command

NewReverbStopCmd returns the standalone reverb:stop command.

func NewRunCmd added in v1.21.0 

func NewRunCmd() *cobra.Command

NewRunCmd returns the `lerd run` command, the CLI alias for the framework commands feature. With no args it lists available commands for the current site; with a name it executes that command in the project directory.

func NewRuntimeCmd added in v1.18.0 

func NewRuntimeCmd() *cobra.Command

NewRuntimeCmd returns the `lerd runtime` parent command.

func NewSailCmd added in v1.13.0 

func NewSailCmd() *cobra.Command

NewSailCmd returns a top-level `lerd sail` command. Registering it as a known cobra command prevents the vendor-bin dispatcher from intercepting `lerd sail import`. The `import` subcommand is handled by lerd; every other argument is passed through to vendor/bin/sail so existing Sail workflows (lerd sail up, lerd sail artisan migrate, …) continue to work.

func NewScheduleCmd added in v0.8.0 

func NewScheduleCmd() *cobra.Command

NewScheduleCmd returns the schedule parent command with start/stop subcommands.

func NewScheduleStartCmd added in v0.8.0 

func NewScheduleStartCmd() *cobra.Command

NewScheduleStartCmd returns the standalone schedule:start command.

func NewScheduleStopCmd added in v0.8.0 

func NewScheduleStopCmd() *cobra.Command

NewScheduleStopCmd returns the standalone schedule:stop command.

func NewSecureCmd 

func NewSecureCmd() *cobra.Command

NewSecureCmd returns the secure command.

func NewServiceCmd 

func NewServiceCmd() *cobra.Command

NewServiceCmd returns the service command with subcommands.

func NewSetupCmd added in v0.4.0 

func NewSetupCmd() *cobra.Command

NewSetupCmd returns the setup command.

func NewShareCmd added in v0.4.0 

func NewShareCmd() *cobra.Command

NewShareCmd returns the share command.

func NewSitesCmd 

func NewSitesCmd() *cobra.Command

NewSitesCmd returns the sites command.

func NewStartCmd added in v0.1.11 

func NewStartCmd() *cobra.Command

NewStartCmd returns the start command.

func NewStatusCmd 

func NewStatusCmd() *cobra.Command

NewStatusCmd returns the status command.

func NewStopCmd added in v0.1.11 

func NewStopCmd() *cobra.Command

NewStopCmd returns the stop command.

func NewStripeCmds added in v0.6.0 

func NewStripeCmds() []*cobra.Command

NewStripeCmds returns Stripe-related subcommands.

func NewTestCmd added in v1.7.0 

func NewTestCmd() *cobra.Command

NewTestCmd returns the `lerd test` command — shortcut for `lerd artisan test`.

func NewTrayCmd added in v0.5.0 

func NewTrayCmd() *cobra.Command

NewTrayCmd returns the tray command.

func NewTuiCmd added in v1.16.0 

func NewTuiCmd() *cobra.Command

NewTuiCmd returns the `lerd tui` command. Opens a btop-style dashboard in the terminal with live site / service / worker status and keybindings for common start / stop / restart actions.

func NewUninstallCmd 

func NewUninstallCmd() *cobra.Command

NewUninstallCmd returns the uninstall command.

func NewUnlinkCmd 

func NewUnlinkCmd() *cobra.Command

NewUnlinkCmd returns the unlink command.

func NewUnparkCmd added in v0.1.9 

func NewUnparkCmd() *cobra.Command

NewUnparkCmd returns the unpark command.

func NewUnpauseCmd added in v1.0.0 

func NewUnpauseCmd() *cobra.Command

NewUnpauseCmd returns the unpause command.

func NewUnsecureCmd added in v0.3.0 

func NewUnsecureCmd() *cobra.Command

NewUnsecureCmd returns the unsecure command.

func NewUpdateCmd 

func NewUpdateCmd(currentVersion string) *cobra.Command

NewUpdateCmd returns the update command.

func NewUseCmd 

func NewUseCmd() *cobra.Command

NewUseCmd returns the use command.

func NewVendorBinCmd added in v1.7.0 

func NewVendorBinCmd() *cobra.Command

NewVendorBinCmd returns the hidden `lerd vendor-bin <name> [args...]` command used by the top-level fallback in main.go to dispatch composer-installed binaries discovered in the project's vendor/bin directory.

func NewWhatsnewCmd added in v1.3.0 

func NewWhatsnewCmd() *cobra.Command

NewWhatsnewCmd returns the whatsnew command.

func NewWhichCmd added in v1.5.0 

func NewWhichCmd() *cobra.Command

NewWhichCmd returns the which command.

func NewWorkerCmd added in v1.0.0 

func NewWorkerCmd() *cobra.Command

NewWorkerCmd returns the worker parent command with start/stop/list subcommands.

func NewWorkersCmd added in v1.19.0 

func NewWorkersCmd() *cobra.Command

NewWorkersCmd returns the `lerd workers` parent command. Currently only `lerd workers mode [exec|container]` lives here, but the subcommand is structured as a group so future runtime-level options (concurrency, restart delay, ...) have an obvious home.

func NewWorktreeCmd added in v1.19.0 

func NewWorktreeCmd() *cobra.Command

NewWorktreeCmd returns the `lerd worktree` parent command, mirroring `git worktree`'s subcommand layout. Today only `add` is implemented; we can grow `list` / `remove` later if there's demand.

func NewXdebugCmd added in v0.4.0 

func NewXdebugCmd() *cobra.Command

NewXdebugCmd returns the xdebug parent command with on/off/status subcommands.

func OptedInBuildReplacers added in v1.20.0 

func OptedInBuildReplacers(site *config.Site, path string) []string

OptedInBuildReplacers returns names of workers (a) opted into via .lerd.yaml workers:, (b) declared replaces_build:true in the framework yaml, and (c) able to run at the given path. When path != site.Path the per_worktree:true gate applies; for the parent it doesn't.

func OptedInHostWorkers added in v1.20.0 

func OptedInHostWorkers(site *config.Site, worktreePath string) []string

OptedInHostWorkers returns the names of host-mode workers the user has opted into for this project (.lerd.yaml workers:) and whose check rule matches the worktree path. Worker auto-start now follows project intent instead of treating every host:true worker as implicitly desired.

Platform support is consulted before adding a name to the list — a host worker that workerSupportedOnPlatform rejects (macOS today) is excluded so the caller doesn't go on to print "Started …, skipping build" for a worker that will silently no-op in WorkerStartForSite.

func PauseSite added in v1.0.0 

func PauseSite(name string) error

PauseSite stops all running workers for the site, replaces its nginx vhost with a landing page, and marks it paused in the registry.

func PortInUse added in v1.19.1 

func PortInUse(port string) bool

PortInUse returns true if something is listening on the given TCP port.

func PortInUseIn added in v1.19.1 

func PortInUseIn(port, output string) bool

PortInUse is implemented per-platform in doctor_linux.go / doctor_darwin.go.

PortInUseIn checks whether the given TCP port appears in pre-fetched output from a port listing command (ss on Linux, lsof on macOS). Used by checkPortConflicts in startstop.go for batch checks.

func PortListOutput added in v1.19.1 

func PortListOutput() string

PortListOutput returns the raw output of ss -tlnp for batch port checks.

func PrintLANShareQR added in v1.13.0 

func PrintLANShareQR(rawURL string)

PrintLANShareQR prints a compact QR code for the given URL to stdout using half-block Unicode characters (two rows per terminal line).

func ProjectHasLerdSkills added in v1.18.0 

func ProjectHasLerdSkills(abs string) bool

ProjectHasLerdSkills is the opt-in signal for project-scoped refresh: true iff at least one lerd-owned marker file exists. Shared JSON configs are not checked because they may contain unrelated MCP servers.

func QueueRestartForSite added in v0.8.0 

func QueueRestartForSite(siteName, sitePath, phpVersion string) error

QueueRestartForSite signals the Laravel queue worker to gracefully restart by running php artisan queue:restart inside the PHP-FPM container. It is a no-op when no queue unit exists for the site. systemd restarts the worker after the graceful exit because the unit uses Restart=always.

func QueueStartForSite added in v0.3.0 

func QueueStartForSite(siteName, sitePath, phpVersion string) error

QueueStartForSite starts a queue worker for the given site using the command from the framework definition.

func QueueStopForSite added in v0.3.0 

func QueueStopForSite(siteName string) error

QueueStopForSite stops and removes the queue worker for the named site.

func RebuildSite added in v1.15.0 

func RebuildSite(name string) error

RebuildSite rebuilds the custom container image from the Containerfile and restarts the container. For PHP sites this is a no-op (use php:rebuild).

func RecordRemoteSetupFailure added in v1.8.0 

func RecordRemoteSetupFailure() (closed bool, err error)

RecordRemoteSetupFailure increments the failure counter on the active token. When the count reaches MaxRemoteSetupFailures the token is wiped from disk and `closed` is true — subsequent calls to the endpoint return 404 until the user generates a new token. Idempotent against concurrent callers in the worst case (one extra increment).

func RegenerateFamilyConsumersForService added in v1.9.0 

func RegenerateFamilyConsumersForService(name string)

RegenerateFamilyConsumersForService is the public entry the Web UI uses after a start/stop. Forwards to serviceops.

func RegisterProject added in v0.3.0 

func RegisterProject(projectDir string, cfg *config.GlobalConfig) (bool, error)

RegisterProject registers a single project directory as a lerd site if it looks like a PHP project. It detects the framework first; if none matches it falls back to auto-detecting the public directory. Returns true if newly registered.

func RemoveGlobalAISkills added in v1.18.0 

func RemoveGlobalAISkills(home string, verbose bool) error

RemoveGlobalAISkills tears down every user-scope artefact written by the Write/RunMCPEnableGlobal path: skill + rules files, shared mcp.json entries, Claude Code user-scope MCP registration, and the Junie guidelines block.

func RemoveProjectAISkills added in v1.18.0 

func RemoveProjectAISkills(abs string, verbose bool) error

RemoveProjectAISkills removes every lerd-owned artefact under abs: skill + rules files, MCP entries in the project's shared mcp.json files, and the lerd section of .junie/guidelines.md. Opt-out counterpart of Write.

func RemoveWorktreeAndCleanup added in v1.20.0 

func RemoveWorktreeAndCleanup(site *config.Site, branch string, force, dropDB bool, log io.Writer) error

RemoveWorktreeAndCleanup runs `git worktree remove [--force]` for branch, stops its per-worktree worker units, and (when dropDB) drops the isolated database and its registry entry. The daemon watcher still handles vhost and LAN-share teardown asynchronously. Progress is written to log (may be nil).

func RestartSite added in v1.15.0 

func RestartSite(name string) error

RestartSite restarts the custom container for a site. For PHP sites it restarts the shared FPM container for that site's PHP version.

func RestartStripeIfActive added in v1.20.2 

func RestartStripeIfActive(site *config.Site)

RestartStripeIfActive is exported so the daemon's stripe:refresh HTTP handler can run the same Stripe restart logic as the CLI. SetSecured posts to that endpoint after every toggle, so this is the single implementation across CLI / UI / MCP.

func RestoreLANShareProxies added in v1.13.0 

func RestoreLANShareProxies()

RestoreLANShareProxies restarts share proxies for every site that has a LANPort stored in the registry. Called once when the UI server starts.

func ReverbStartForSite added in v0.8.0 

func ReverbStartForSite(siteName, sitePath, phpVersion string) error

ReverbStartForSite starts the Reverb WebSocket server for the named site. This is an alias that looks up the "reverb" worker from the framework definition and delegates to the generic WorkerStartForSite, which handles proxy port assignment and nginx regeneration automatically.

func ReverbStopForSite added in v0.8.0 

func ReverbStopForSite(siteName string) error

ReverbStopForSite stops and removes the Reverb unit for the named site.

func RunDoctorTo added in v1.19.0 

func RunDoctorTo(w io.Writer, useColor bool) (fails, warns int, err error)

RunDoctorTo runs the full doctor diagnostic, writing human-readable output to w. When useColor is false ANSI escapes are stripped so the output is safe to embed in a plain-text file (used by `lerd bug-report`). Returns the failure and warning counts for callers that want to summarise.

func RunMCPEnableGlobal added in v1.1.0 

func RunMCPEnableGlobal() error

RunMCPEnableGlobal registers lerd MCP at user scope for all supported AI tools. It is exported so the install command can call it directly.

func RunPHP added in v1.7.0 

func RunPHP(cwd string, args []string) error

RunPHP execs `php <args...>` inside the project's PHP-FPM container, with stdio wired to the current terminal. Used by `lerd php`, the vendor/bin fallback, and other passthrough commands that need a PHP runtime. The child's exit code is propagated via os.Exit; callers that need to do work after the child exits (e.g. sync wrappers after a failed composer remove) should use RunPHPCapture instead.

func RunPHPCapture added in v1.21.1 

func RunPHPCapture(cwd string, args []string) (int, error)

RunPHPCapture is the non-exiting variant of RunPHP. It returns the child process's exit code separately from any setup error (container not running, version detection failure, etc.), so callers can run their own work after the child exits before propagating the code to the parent shell.

func RunPHPCaptureEnv added in v1.22.0 

func RunPHPCaptureEnv(cwd string, args []string, extraEnv []string) (int, error)

RunPHPCaptureEnv is RunPHPCapture with extra KEY=VALUE environment entries injected into the container exec — used by `lerd profile run` to set SPX_ENABLED so a CLI command is profiled.

func RunParallel added in v0.5.6 

func RunParallel(jobs []BuildJob) error

RunParallel executes all jobs concurrently with a compact spinner UI. In a non-TTY environment it falls back to plain sequential output. Returns the first non-nil error, or nil if all jobs succeed.

func RunQuit added in v0.7.0 

func RunQuit() error

RunQuit stops all lerd processes and containers (exported for use by the UI server).

func RunStart added in v0.7.0 

func RunStart() error

RunStart starts all lerd services (exported for use by the UI server).

func RunStop added in v0.7.0 

func RunStop() error

RunStop stops lerd containers (exported for use by the UI server).

func RunWorktreeAdd added in v1.20.0 

func RunWorktreeAdd(site *config.Site, req WorktreeAddRequest, log io.Writer) (string, string, []string, error)

RunWorktreeAdd creates a git worktree for site, runs composer + JS install with output streamed to log, applies the build choice, configures the database, and optionally runs migrations. Progress lines are written to log (may be nil). Returns the sanitized branch name, the checkout path, and any "[WARN]" lines emitted along the way so callers (e.g. the dashboard) can keep the modal open and surface them instead of silently treating the setup as success.

The install runs inside this process — not the watcher daemon — so its stdout/stderr lands directly in the dashboard's SSE stream. A cross- process flock (acquired before git worktree add so the watcher's fsnotify-triggered install loses the race) keeps the watcher from running its own composer install in parallel and clobbering vendor/.

func RunWorktreeMigrations added in v1.20.0 

func RunWorktreeMigrations(site *config.Site, branch string, log io.Writer) error

RunWorktreeMigrations runs `php artisan migrate --force` inside the worktree's checkout (via the FPM container's php shim). It's a no-op when the worktree isn't a Laravel project or has disappeared. Output is written to log (may be nil).

func SaveRemoteSetupToken added in v1.8.0 

func SaveRemoteSetupToken(t *RemoteSetupToken) error

SaveRemoteSetupToken writes the token to disk with mode 0600.

func ScheduleStartForSite added in v0.8.0 

func ScheduleStartForSite(siteName, sitePath, phpVersion string) error

ScheduleStartForSite starts the task scheduler for the named site using the "schedule" worker from the framework definition. The version-aware loader (GetFrameworkForDir) is used so per-version overrides — like Laravel 10's `schedule: minutely` cron entry — actually take effect instead of falling back to the version-less built-in defaults.

func ScheduleStopForSite added in v0.8.0 

func ScheduleStopForSite(siteName string) error

ScheduleStopForSite stops and removes the scheduler unit for the named site.

func SetWorktreeDBIsolated added in v1.19.0 

func SetWorktreeDBIsolated(site *config.Site, branch string, isolated bool, source string) error

SetWorktreeDBIsolated is the shared lifecycle helper used by both the HTTP handler and the `lerd db:isolate` / `lerd db:share` CLI commands. On enable it creates `<parent_db>_<sanitized_branch>` in the same service the parent uses, optionally clones from `source` (empty / "main" / another isolated branch), records the worktree-DB pair in the registry, and rewrites DB_DATABASE in the worktree's .env. On disable it drops the DB and restores the parent's value. Idempotent.

func SiteHasHorizon added in v1.0.0 

func SiteHasHorizon(sitePath string) bool

SiteHasHorizon returns true if composer.json lists laravel/horizon as a dependency.

func SiteHasProxyWorker added in v1.10.0 

func SiteHasProxyWorker(sitePath, workerName string) bool

SiteHasProxyWorker returns true if the site's framework defines a worker with a proxy configuration and that worker's check rule passes.

func SiteHasReverb added in v0.8.0 

func SiteHasReverb(sitePath string) bool

SiteHasReverb returns true if the site's framework defines a "reverb" worker and the worker's check rule passes (e.g. laravel/reverb is in composer.json).

func SiteUsesReverb added in v0.8.0 

func SiteUsesReverb(sitePath string) bool

SiteUsesReverb returns true if the site has a reverb worker configured and optionally checks for BROADCAST_CONNECTION=reverb in the env file.

func StartServiceDependencies added in v1.9.0 

func StartServiceDependencies(svc *config.CustomService) error

StartServiceDependencies and StopServiceAndDependents are thin wrappers so the Web UI can share the same semantics as the CLI.

func StopAllWorkersForWorktree added in v1.20.0 

func StopAllWorkersForWorktree(siteName, wtBase string) error

StopAllWorkersForWorktree stops every per-worktree worker unit attached to the given (site, worktree) pair. Called from `lerd worktree remove` and from the watcher's onRemoved hook so units don't restart-loop against a deleted WorkingDirectory after the user tears down a worktree. Returns the first underlying error so the caller can log it; siblings keep being torn down regardless.

func StopServiceAndDependents added in v1.9.0 

func StopServiceAndDependents(name string)

func StripeRestoreUnit added in v1.18.0 

func StripeRestoreUnit(siteName, sitePath, siteBaseURL string) error

StripeRestoreUnit writes the stripe listener unit without starting it. Used by install's restore path so workers launch in phase order — FPM and nginx come up first, then `startRestoredServices` starts every worker.

func StripeSecretSet added in v0.6.0 

func StripeSecretSet(sitePath string) bool

StripeSecretSet returns true if STRIPE_SECRET is present in the site's .env.

func StripeStartForSite added in v0.6.0 

func StripeStartForSite(siteName, sitePath, siteBaseURL string) error

StripeStartForSite starts a Stripe listener for the given site, reading the key from its .env.

func StripeStopForSite added in v0.6.0 

func StripeStopForSite(siteName string) error

StripeStopForSite stops and removes the Stripe listener for the named site.

func UnlinkSite added in v0.3.0 

func UnlinkSite(name string) error

UnlinkSite removes the nginx vhost for the named site. For sites under a parked directory, the registry entry is kept but marked Ignored so the watcher does not re-register it. For manually-linked sites the entry is removed entirely.

func UnpauseSite added in v1.0.0 

func UnpauseSite(name string) error

UnpauseSite restores the site's nginx vhost, restarts any workers that were running when the site was paused, and clears the paused state.

func VendorBinExists added in v1.7.0 

func VendorBinExists(cwd, name string) bool

VendorBinExists reports whether the project rooted at cwd has an executable vendor/bin/<name> on disk. Used by the top-level command-not-found fallback to decide whether to dispatch unknown subcommands to a composer binary.

func WaitForWorktreeReady added in v1.20.0 

func WaitForWorktreeReady(worktreePath string, deadline time.Duration) error

WaitForWorktreeReady polls until the worktree's vendor + node_modules + .env are in place, signalling that lerd's watcher-driven install pipeline has finished. The frontend build is no longer part of this wait — `lerd worktree add` invokes RunFrontendBuild explicitly after installs succeed.

func WorkerMigrationActive added in v1.19.0 

func WorkerMigrationActive() bool

WorkerMigrationActive reports whether a worker-mode migration is currently running on this process. Nil-safe and zero-cost when not active.

func WorkerStartForSite added in v1.0.0 

func WorkerStartForSite(siteName, sitePath, phpVersion, workerName string, w config.FrameworkWorker, persist bool) error

WorkerStartForSite writes a systemd unit for the given framework worker and starts it. The unit name is lerd-{workerName}-{siteName}. If the worker has a Proxy config, the proxy port is auto-assigned and the nginx vhost is regenerated to include the WebSocket/HTTP proxy block. When persist is false the worker is not added to .lerd.yaml, used by the auto-start path so worktree vite workers don't appear as user-opted entries.

func WorkerStopForSite added in v1.0.0 

func WorkerStopForSite(siteName, sitePath, workerName string) error

WorkerStopForSite stops and removes the named worker unit for the given site. When sitePath is a path under a worktree (i.e. differs from the registered site path), the per-worktree unit is targeted instead of the parent's. Pass site.Path (or any path on the parent site) to stop the parent unit.

func WorkerSupportedOnPlatform added in v1.20.0 

func WorkerSupportedOnPlatform(w config.FrameworkWorker) (bool, string)

WorkerSupportedOnPlatform is the exported entry point to the platform support gate. External packages (the watcher's exec_workers loop, future callers) consult it before enumerating a worker as "expected to be running" — without the gate they would re-issue start attempts every tick for workers that the platform-specific writeWorkerUnitFile silently skips.

The actual policy lives in the build-tagged worker_supported_<goos>.go files via the workerSupportedOnPlatform package var, which tests can substitute. This wrapper is here so the var can stay unexported.

func WorktreeCheckoutPath added in v1.20.0 

func WorktreeCheckoutPath(sitePath, branch string) string

WorktreeCheckoutPath returns the directory a new worktree for branch should be checked out into: a child of the parent site, "<sitePath>/<base>-<slug>" where <base> is filepath.Base(sitePath). Bumps a numeric suffix if the default path already exists. RunWorktreeAdd also writes a `/<base>-*/` pattern into .git/info/exclude so git status doesn't show siblings. Caveat: non-git tools (composer, IDEs, find/rsync/tar) walking the parent tree DO descend into the worktree — gitignore doesn't hide it from them. Most callers don't care; flag if you do.

func WorktreeDBName added in v1.19.0 

func WorktreeDBName(parentDB, branch string) string

WorktreeDBName mirrors the projectDBName convention so a parent named "acme_app" with branch "feat-x" becomes "acme_app_feat_x".

func WriteGlobalAISkills added in v1.17.0 

func WriteGlobalAISkills(home string, verbose bool) error

WriteGlobalAISkills writes the user-scope skill, rules, and guidelines files used by Claude Code, Cursor, and JetBrains Junie. It is called both from mcp:enable-global and from lerd update so the docs the AI reads stay aligned with the currently installed binary's tool set. When verbose is true each written path is printed to stdout.

func WriteProjectAISkills added in v1.18.0 

func WriteProjectAISkills(abs string, verbose bool) error

WriteProjectAISkills writes the per-project AI artefacts for abs. MCP config JSONs and .junie/guidelines.md preserve non-lerd entries; SKILL.md and lerd.mdc are overwritten. verbose=true prints each written path.

Types

type BuildJob added in v0.5.6 

type BuildJob struct {
	Label string
	Run   func(w io.Writer) error
}

BuildJob is a labeled build task that writes its output to the provided writer.

type HealEvent added in v1.19.0 

type HealEvent = workerheal.Event

type HealFailure added in v1.19.0 

type HealFailure = workerheal.Failure

type HealResult added in v1.19.0 

type HealResult = workerheal.Result

func HealWorkers added in v1.19.0 

func HealWorkers(emit func(HealEvent)) (HealResult, error)

HealWorkers is the CLI/UI-facing alias for workerheal.HealAll.

type LANProgressFunc added in v1.8.0 

type LANProgressFunc func(step string)

LANProgressFunc is invoked by EnableLANExposure / DisableLANExposure after every meaningful step completes. The argument is a short human-readable label suitable for streaming to a frontend ("Rewriting container quadlets", "Restarting lerd-dns", "Done — LAN IP 192.168.x.y"). May be nil; the no-progress path is the common case (CLI without streaming, internal idempotent re-application from `lerd remote-setup`).

type LintDiagnostic added in v1.19.0 

type LintDiagnostic struct {
	Line     int    `json:"line"`
	Column   int    `json:"column"`
	Message  string `json:"message"`
	Severity string `json:"severity"` // "error" | "warning"
}

LintDiagnostic is one issue surfaced by the linter, suitable for the frontend to render as a CodeMirror diagnostic.

func LintTinkerCode added in v1.19.0 

func LintTinkerCode(ctx context.Context, sitePath, code string) ([]LintDiagnostic, error)

LintTinkerCode runs `php -l` against the given code in the site's PHP container and parses the output. We pipe the code via stdin (`php -l` reads from stdin when given `-` or no file argument depending on the build, but the most portable is to write the code to a stdin pipe and invoke `php -l /dev/stdin`).

type PortCheck added in v1.19.1 

type PortCheck struct {
	Port      string // host port number
	Label     string // e.g. "nginx HTTP", "mysql"
	Container string // lerd container name
}

PortCheck pairs a host port with a human-readable label and container name.

func CollectPortChecks added in v1.19.1 

func CollectPortChecks(units []string) []PortCheck

CollectPortChecks builds the list of ports to verify for the given units.

type RemoteSetupToken added in v1.8.0 

type RemoteSetupToken struct {
	Token    string    `json:"token"`
	Expires  time.Time `json:"expires"`
	Failures int       `json:"failures,omitempty"`
}

RemoteSetupToken is the on-disk representation of a one-time code that authorizes a remote device to call the /api/remote-setup endpoint.

Stored in <DataDir>/remote-setup-token.json with mode 0600. The token is short (8 characters), high-entropy enough for the LAN-only threat model, gated by a TTL so a forgotten token doesn't grant indefinite access, and counted against a per-token failure limit so brute-force attempts close the endpoint instead of running indefinitely.

func LoadRemoteSetupToken added in v1.8.0 

func LoadRemoteSetupToken() (*RemoteSetupToken, error)

LoadRemoteSetupToken reads the current token from disk. Returns nil (no error) when the file doesn't exist — i.e. no token is active.

type StepRunner added in v0.5.6 

type StepRunner struct {
	// contains filtered or unexported fields
}

StepRunner runs labeled steps sequentially with a compact in-place TUI. Each step's output is hidden by default; press Ctrl+O to toggle it. Falls back to plain " --> label ... OK" output when stdout is not a TTY.

func NewStepRunner added in v0.5.6 

func NewStepRunner() *StepRunner

NewStepRunner creates and starts a StepRunner. Call Close() when all steps are done to restore the terminal.

func (*StepRunner) Close added in v0.5.6 

func (r *StepRunner) Close()

Close stops the render loop, restores the terminal, and prints a final newline.

func (*StepRunner) Run added in v0.5.6 

func (r *StepRunner) Run(label string, fn func(w io.Writer) error) error

Run executes fn as a labeled step. In TUI mode the step shows a spinner while running and ✓/✗ when done. Returns fn's error.

func (*StepRunner) RunInteractive added in v0.5.6 

func (r *StepRunner) RunInteractive(label string, fn func() error) error

RunInteractive temporarily restores the terminal to cooked mode so that steps which need interactive sudo (password prompts, etc.) work correctly. The spinner pauses, the step runs with full terminal access, then raw mode resumes.

type TinkerResult added in v1.19.0 

type TinkerResult struct {
	Stdout     string `json:"stdout"`
	Stderr     string `json:"stderr"`
	ExitCode   int    `json:"exit_code"`
	DurationMs int64  `json:"duration_ms"`
	Mode       string `json:"mode"`
}

func RunTinker added in v1.19.0 

func RunTinker(ctx context.Context, sitePath, siteName, branch, code string) (TinkerResult, error)

RunTinker evaluates user PHP code inside the site's PHP container and captures stdout/stderr. Mode is driven by the framework definition's `tinker:` block when present, with a plain-`php` fallback. The mode label returned in the response is the framework name (e.g. "laravel") or "php" for the fallback.

siteName + branch are forwarded to the container as LERD_SITE / LERD_BRANCH env vars so the dump bridge tags `dump()` / `dd()` events with the same identifiers FPM requests use (otherwise tinker dumps land under the worktree's directory basename rather than the parent site).

type TinkerSymbols added in v1.19.0 

type TinkerSymbols struct {
	Models    []string `json:"models"`
	Classes   []string `json:"classes"`
	Functions []string `json:"functions"`
}

TinkerSymbols is the set of project-defined names surfaced to the Tinker editor's autocomplete. Keep it minimal: classes the user is likely to type at the REPL.

func CollectTinkerSymbols added in v1.19.0 

func CollectTinkerSymbols(sitePath string) TinkerSymbols

CollectTinkerSymbols scans the site for class declarations and flags model/entity-shaped ones. Source roots come from composer.json's `autoload.psr-4` section (works for Laravel `app/`, Symfony `src/`, and any framework that uses standard PSR-4 autoloading), with fallbacks for projects that don't declare PSR-4 paths.

type UnhealthyWorker added in v1.19.0 

type UnhealthyWorker = workerheal.UnhealthyWorker

func DetectUnhealthyWorkers added in v1.19.0 

func DetectUnhealthyWorkers() ([]UnhealthyWorker, error)

DetectUnhealthyWorkers is the CLI/UI-facing alias for workerheal.Detect.

type WorkerModePhaseEvent added in v1.19.0 

type WorkerModePhaseEvent struct {
	Phase   string `json:"phase"` // "saving_config" | "migrating_worker" | "done" | "error"
	Unit    string `json:"unit,omitempty"`
	Step    string `json:"step,omitempty"` // "stopping" | "cleaning" | "starting"
	Message string `json:"message,omitempty"`
	Error   string `json:"error,omitempty"`
}

WorkerModePhaseEvent is one step in the migration. The dashboard streams these as NDJSON so the confirm modal can show real progress instead of a blind 30-60s spinner.

type WorktreeAddRequest added in v1.20.0 

type WorktreeAddRequest struct {
	NewBranch      string // create this branch with `git worktree add -b`
	ExistingBranch string // check out an already-existing branch
	BaseRef        string // start point for a new branch (optional; defaults to HEAD)
	DBChoice       string // "share" | "empty" | "clone-main" | "clone-<branch>" | "reuse" | "reset"
	RunMigrations  bool   // run `php artisan migrate --force` when DBChoice yields an empty schema
	Build          string // "auto" | "skip" | "worker:<name>" | "script:<name>"
}

WorktreeAddRequest carries the choices the dashboard (or any non-interactive caller) makes for `lerd worktree add`, mirroring what the CLI's huh prompts gather. Exactly one of NewBranch / ExistingBranch must be set.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.