cli

package

v1.28.1 Latest Latest Go to latest Published: Jul 8, 2026 License: MIT Imports: 82 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/geodro/lerd

Links

Documentation ¶

Rendered for

Index ¶

Constants
Variables
func ApplyAutostart(disabled bool) error
func ApplyHorizonReload(siteName, sitePath, phpVersion string, enabled bool) error
func ApplyOctaneReload(siteName, sitePath, phpVersion string, enabled bool) error
func ApplyWorkersMode(newMode string) error
func ApplyWorkersModeStreaming(newMode string, emit func(WorkerModePhaseEvent)) error
func ApplyWorktreeBuildChoice(site *config.Site, worktreePath string, choice worktreeBuildChoice, ...)
func ApplyWorktreeDBChoice(site *config.Site, branch, choice string, log io.Writer) error
func AutoStartOptedInWorktreeWorkers(site *config.Site, worktreePath, phpVersion string)
func AvailableBuildScripts(worktreePath string) []string
func AvailableDevScripts(cwd string) []string
func ClearIdleSuspendOnStart(siteName, sitePath, workerName string)
func ClearRemoteSetupToken() error
func CloneDatabase(svc, src, dst string) error
func CollectRunningWorkerNames(site *config.Site) []string
func CreateDatabase(svc, name string) (bool, error)
func DisableLANExposure(progress LANProgressFunc) error
func DropDatabase(svc, name string) (bool, error)
func DropOrphanedWorktreeDBs(site *config.Site)
func DropOrphanedWorktreeLANShares(site *config.Site, liveBranches map[string]bool)
func EligibleBuildReplacers(site *config.Site, path string) []string
func EnableLANExposure(progress LANProgressFunc) (lanIP string, err error)
func EnsureWorktreeIsolatedDB(site *config.Site, branch, worktreePath string) (bool, error)
func FindListenerCmd(port string) string
func FindParentSiteForWorktree(dir string) (*config.Site, string, bool)
func GenerateRemoteSetupToken(ttl time.Duration) (string, error)
func HealSummary(r HealResult) string
func HealUnit(unit string) error
func HorizonStartForSite(siteName, sitePath, phpVersion string) error
func HorizonStopForSite(siteName string) error
func IdleSuspendStateIsStale(site *config.Site) bool
func InstallChokidar(sitePath string) error
func InstallPHPVersion(version string, w io.Writer) error
func InstallPresetByName(name, version string) (*config.CustomService, error)
func IsLegacyPHPVersion(v string) bool
func IsMCPGloballyRegistered() bool
func IsSupportedPHPVersion(v string) bool
func LANShareEnsurePort(siteName string) (int, error)
func LANShareRefreshIfRunning(siteName string) error
func LANShareRunning(siteName string) bool
func LANShareStart(siteName string) (int, error)
func LANShareStartWorktree(siteName, branch string) (int, error)
func LANShareStop(siteName string) error
func LANShareStopServer(siteName string)
func LANShareStopWorktree(siteName, branch string) error
func LANShareURL(lanPort int) string
func LANShareWorktreeRunning(siteName, branch string) bool
func ListInstallablePresets() ([]config.PresetMeta, error)
func ListVendorBins(cwd string) []string
func MissingPresetDependencies(svc *config.CustomService) []string
func NewAboutCmd() *cobra.Command
func NewAuthCmd() *cobra.Command
func NewAutostartCmd() *cobra.Command
func NewBugReportCmd() *cobra.Command
func NewCheckCmd() *cobra.Command
func NewCleanupCmd() *cobra.Command
func NewClientExecCmd() *cobra.Command
func NewComposerCmd() *cobra.Command
func NewConsoleCmd() *cobra.Command
func NewDBIsolateCmd() *cobra.Command
func NewDBShareCmd() *cobra.Command
func NewDNSDisableCmd() *cobra.Command
func NewDNSEnableCmd() *cobra.Command
func NewDNSForwarderCmd() *cobra.Command
func NewDNSRepairCmd() *cobra.Command
func NewDashboardCmd() *cobra.Command
func NewDbCmd() *cobra.Command
func NewDbCreateCmd() *cobra.Command
func NewDbExportCmd() *cobra.Command
func NewDbImportCmd() *cobra.Command
func NewDbMoveCmd() *cobra.Command
func NewDbRestoreCmd() *cobra.Command
func NewDbShellCmd() *cobra.Command
func NewDbSnapshotCmd() *cobra.Command
func NewDbSnapshotRmCmd() *cobra.Command
func NewDbSnapshotsCmd() *cobra.Command
func NewDoctorCmd() *cobra.Command
func NewDomainCmd() *cobra.Command
func NewDumpCmd() *cobra.Command
func NewEnvCheckCmd() *cobra.Command
func NewEnvCmd() *cobra.Command
func NewEnvOverrideCmd() *cobra.Command
func NewEnvRestoreCmd() *cobra.Command
func NewFetchCmd() *cobra.Command
func NewFrameworkCmd() *cobra.Command
func NewGroupCmd() *cobra.Command
func NewHorizonCmd() *cobra.Command
func NewHorizonReloadCmd() *cobra.Command
func NewHorizonStartCmd() *cobra.Command
func NewHorizonStopCmd() *cobra.Command
func NewIdleCmd() *cobra.Command
func NewImportCmd() *cobra.Command
func NewInitCmd() *cobra.Command
func NewInstallCmd() *cobra.Command
func NewIsolateCmd() *cobra.Command
func NewIsolateNodeCmd() *cobra.Command
func NewJSRuntimeCmd() *cobra.Command
func NewLANCmd() *cobra.Command
func NewLANExposeCmd() *cobra.Command
func NewLANShareCmd() *cobra.Command
func NewLANStatusCmd() *cobra.Command
func NewLANUnexposeCmd() *cobra.Command
func NewLANUnshareCmd() *cobra.Command
func NewLinkCmd() *cobra.Command
func NewLogsCmd() *cobra.Command
func NewMCPCmd() *cobra.Command
func NewMCPDisableGlobalCmd() *cobra.Command
func NewMCPEjectCmd() *cobra.Command
func NewMCPEnableGlobalCmd() *cobra.Command
func NewMCPInjectCmd() *cobra.Command
func NewMachineCmd() *cobra.Command
func NewManCmd() *cobra.Command
func NewMinioMigrateCmd() *cobra.Command
func NewNewCmd() *cobra.Command
func NewNginxCmd() *cobra.Command
func NewNodeCmd() *cobra.Command
func NewNodeInstallCmd() *cobra.Command
func NewNodeManageCmd() *cobra.Command
func NewNodeUninstallCmd() *cobra.Command
func NewNodeUnmanageCmd() *cobra.Command
func NewNodeUseCmd() *cobra.Command
func NewNotifyCmd() *cobra.Command
func NewNpmCmd() *cobra.Command
func NewNpxCmd() *cobra.Command
func NewOctaneCmd() *cobra.Command
func NewOctaneReloadCmd() *cobra.Command
func NewOpenCmd() *cobra.Command
func NewParkCmd() *cobra.Command
func NewPauseCmd() *cobra.Command
func NewPestBrowserCmd() *cobra.Command
func NewPhpBunCmd() *cobra.Command
func NewPhpCmd() *cobra.Command
func NewPhpExtCmd() *cobra.Command
func NewPhpIniCmd() *cobra.Command
func NewPhpListCmd() *cobra.Command
func NewPhpPkgCmd() *cobra.Command
func NewPhpPortsCmd() *cobra.Command
func NewPhpRebuildCmd() *cobra.Command
func NewPhpShellCmd() *cobra.Command
func NewProfileCmd() *cobra.Command
func NewQueueCmd() *cobra.Command
func NewQueueStartCmd() *cobra.Command
func NewQueueStopCmd() *cobra.Command
func NewQuitCmd() *cobra.Command
func NewRebuildCmd() *cobra.Command
func NewRemoteControlCmd() *cobra.Command
func NewRemoteControlOffCmd() *cobra.Command
func NewRemoteControlOnCmd() *cobra.Command
func NewRemoteControlStatusCmd() *cobra.Command
func NewRemoteSetupCmd() *cobra.Command
func NewRestartCmd() *cobra.Command
func NewReverbCmd() *cobra.Command
func NewReverbStartCmd() *cobra.Command
func NewReverbStopCmd() *cobra.Command
func NewRunCmd() *cobra.Command
func NewRuntimeCmd() *cobra.Command
func NewSailCmd() *cobra.Command
func NewScheduleCmd() *cobra.Command
func NewScheduleStartCmd() *cobra.Command
func NewScheduleStopCmd() *cobra.Command
func NewSecureCmd() *cobra.Command
func NewServiceCmd() *cobra.Command
func NewSetupCmd() *cobra.Command
func NewShareCmd() *cobra.Command
func NewShimsCmd() *cobra.Command
func NewSiteDoctorCmd() *cobra.Command
func NewSitesCmd() *cobra.Command
func NewStartCmd() *cobra.Command
func NewStatusCmd() *cobra.Command
func NewStopCmd() *cobra.Command
func NewStripeCmds() []*cobra.Command
func NewTestCmd() *cobra.Command
func NewTrayCmd() *cobra.Command
func NewTuiCmd() *cobra.Command
func NewUninstallCmd() *cobra.Command
func NewUnlinkCmd() *cobra.Command
func NewUnparkCmd() *cobra.Command
func NewUnpauseCmd() *cobra.Command
func NewUnsecureCmd() *cobra.Command
func NewUpdateCmd(currentVersion string) *cobra.Command
func NewUseCmd() *cobra.Command
func NewVendorBinCmd() *cobra.Command
func NewWSLSetupCmd() *cobra.Command
func NewWhatsnewCmd() *cobra.Command
func NewWhichCmd() *cobra.Command
func NewWorkerCmd() *cobra.Command
func NewWorkersCmd() *cobra.Command
func NewWorktreeCmd() *cobra.Command
func NewXdebugCmd() *cobra.Command
func OptedInBuildReplacers(site *config.Site, path string) []string
func OptedInHostWorkers(site *config.Site, worktreePath string) []string
func PauseSite(name string) error
func PortInUse(port string) bool
func PortInUseIn(port, output string) bool
func PortListOutput() string
func PrintLANShareQR(rawURL string)
func ProjectHasChokidar(sitePath string) bool
func ProjectHasLerdSkills(abs string) bool
func QueueRestartForSite(siteName, sitePath, phpVersion string) error
func QueueStartForSite(siteName, sitePath, phpVersion string) error
func QueueStopForSite(siteName string) error
func RebuildSite(name string) error
func RecordRemoteSetupFailure() (closed bool, err error)
func RefreshGlobalAISkills(home string, verbose bool) error
func RefreshProjectAISkills(abs string, verbose bool) error
func RegenerateFamilyConsumersForService(name string)
func RegenerateHostProxyVhostsOnGatewayChange()
func RegenerateHostWorkersForSite(s config.Site)
func RegisterProject(projectDir string, cfg *config.GlobalConfig) (bool, error)
func RemoveGlobalAISkills(home string, verbose bool) error
func RemoveProjectAISkills(abs string, verbose bool) error
func RemoveWorktreeAndCleanup(site *config.Site, branch string, force, dropDB bool, log io.Writer) error
func RestartSite(name string) error
func RestartStripeIfActive(site *config.Site)
func RestoreLANShareProxies()
func ResumeWorkersForIdle(site *config.Site, workers []string)
func ResumeWorktreeWorkersForIdle(site *config.Site, wtPath string, workers []string)
func ReverbStartForSite(siteName, sitePath, phpVersion string) error
func ReverbStopForSite(siteName string) error
func RunDoctorTo(w io.Writer, useColor bool) (fails, warns int, err error)
func RunMCPDisableGlobal() error
func RunMCPEnableGlobal() error
func RunPHP(cwd string, args []string) error
func RunPHPCapture(cwd string, args []string) (int, error)
func RunPHPCaptureEnv(cwd string, args []string, extraEnv []string) (int, error)
func RunParallel(jobs []BuildJob) error
func RunQuit() error
func RunStart() error
func RunStop() error
func RunWorktreeAdd(site *config.Site, req WorktreeAddRequest, log io.Writer) (string, string, []string, error)
func RunWorktreeMigrations(site *config.Site, branch string, log io.Writer) error
func SaveRemoteSetupToken(t *RemoteSetupToken) error
func ScheduleStartForSite(siteName, sitePath, phpVersion string) error
func ScheduleStopForSite(siteName string) error
func SetSitePinned(name string, pinned bool) error
func SetWorktreeDBIsolated(site *config.Site, branch string, isolated bool, source string) error
func SetupHostProxyWorktree(site config.Site, wtPath, wtDomain string) error
func SiteHasHorizon(sitePath string) bool
func SiteHasOctane(sitePath string) bool
func SiteHasProxyWorker(sitePath, workerName string) bool
func SiteHasReverb(sitePath string) bool
func SiteUsesReverb(sitePath string) bool
func StartServiceDependencies(svc *config.CustomService) error
func StopAllWorkersForWorktree(siteName, wtBase string) error
func StopServiceAndDependents(name string)
func StripeRestoreUnit(siteName, sitePath, siteBaseURL string) error
func StripeSecretSet(sitePath string) bool
func StripeStartForSite(siteName, sitePath, siteBaseURL string) error
func StripeStopForSite(siteName string) error
func SuspendWorkersForIdle(site *config.Site) []string
func SuspendWorktreeWorkersForIdle(site *config.Site, wtPath string) []string
func UnlinkSite(name string) error
func UnpauseSite(name string) error
func VendorBinExists(cwd, name string) bool
func WaitForWorktreeReady(worktreePath string, deadline time.Duration) error
func WorkerMigrationActive() bool
func WorkerStartForSite(siteName, sitePath, phpVersion, workerName string, w config.FrameworkWorker, ...) error
func WorkerStopForSite(siteName, sitePath, workerName string) error
func WorkerSupportedOnPlatform(w config.FrameworkWorker) (bool, string)
func WorktreeCheckoutPath(sitePath, branch string) string
func WorktreeDBName(parentDB, branch string) string
func WorktreeHostPort(parentPort int, wtPath, portEnvKey string) int
func WorktreeIdleSuspendStateIsStale(site *config.Site, wtBase string, suspended []string) bool
func WriteGlobalAISkills(home string, verbose bool) error
func WriteProjectAISkills(abs string, verbose bool) error
type BuildJob
type HealEvent
type HealFailure
type HealResult
- func HealWorkers(emit func(HealEvent)) (HealResult, error)
type LANProgressFunc
type PortCheck
- func CollectPortChecks(units []string) []PortCheck
type RemoteSetupToken
- func LoadRemoteSetupToken() (*RemoteSetupToken, error)
type StepRunner
- func NewStepRunner() *StepRunner
- func (r *StepRunner) Close()
- func (r *StepRunner) Run(label string, fn func(w io.Writer) error) error
- func (r *StepRunner) RunInteractive(label string, fn func() error) error
type TinkerResult
- func RunTinker(ctx context.Context, sitePath, siteName, branch, code string) (TinkerResult, error)
type UnhealthyWorker
- func DetectUnhealthyWorkers() ([]UnhealthyWorker, error)
type WorkerModePhaseEvent
type WorktreeAddRequest

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 TinkerBlockFieldSeparator = "\x1f"

TinkerBlockFieldSeparator ends the per-block source-line field that follows the record separator (`\x1e<line>\x1f<output>`). ASCII 0x1f (unit separator), same rationale as the record separator.

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`.

View Source

const TinkerQueryMarker = "\x02"

TinkerQueryMarker (ASCII 0x02, STX) prefixes a block's payload to mark it as a captured SQL query rather than statement output. It sits right after the `\x1e<line>\x1f` block marker.

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 LegacyPHPVersions = []string{"7.4", "8.0"}

LegacyPHPVersions is the frozen legacy tier built from Alpine 3.16 with an old bundled Node. Kept here next to SupportedPHPVersions so the single definition of "legacy" is reused (e.g. pest:browser, which needs a modern Node) instead of being duplicated as literals elsewhere.

View Source

var SupportedPHPVersions = config.SupportedPHPVersions

SupportedPHPVersions re-exports the canonical list from internal/config, the single source of truth shared with the FrankenPHP image picker.

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 ApplyHorizonReload ¶ added in v1.24.0

func ApplyHorizonReload(siteName, sitePath, phpVersion string, enabled bool) error

ApplyHorizonReload persists the per-project Horizon auto-reload preference and, when a Horizon worker is currently running for the site, restarts it so the new command takes effect immediately. The restart reuses HorizonStartForSite, which resolves the command (standard or horizon:listen) from the freshly persisted preference.

func ApplyOctaneReload ¶ added in v1.25.0

func ApplyOctaneReload(siteName, sitePath, phpVersion string, enabled bool) error

ApplyOctaneReload persists the per-project Octane auto-reload preference and, when the site currently serves via FrankenPHP worker mode, re-applies the FrankenPHP container so the new entrypoint (watch vs standard) takes effect. FinishFrankenPHPLink re-resolves the entrypoint from the freshly persisted preference and restarts the container only when the quadlet content changed.

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 AvailableDevScripts ¶ added in v1.24.0

func AvailableDevScripts(cwd string) []string

AvailableDevScripts returns the dev-server scripts present in the project's package.json, in preference order, each rendered as "npm run <name>".

func ClearIdleSuspendOnStart ¶ added in v1.25.0

func ClearIdleSuspendOnStart(siteName, sitePath, workerName string)

ClearIdleSuspendOnStart drops workerName from the site's (or, for a worktree checkout, that worktree's) persisted idle-suspended set whenever the worker is (re)started outside the idle engine: an install, a relink, or `lerd worker start`. A running worker can't be idle-suspended, so a stale entry would make the engine boot believing the site is asleep and never re-suspend it. Cheap no-op (one read, no write) when the worker isn't in the set, which is the common case for the vast majority of starts.

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 EnsureWorktreeIsolatedDB ¶ added in v1.26.0

func EnsureWorktreeIsolatedDB(site *config.Site, branch, worktreePath string) (bool, error)

EnsureWorktreeIsolatedDB provisions the isolated database for a worktree that committed `db_isolated: true` in its .lerd.yaml but has no database yet. This is the case when a site is linked with a pre-existing worktree (or one is materialised on a daemon that was offline): the interactive add-time prompt that normally creates the DB never ran, so the worktree's vhost and workers come up but its .env points at a database that was never created.

It is a no-op when the worktree didn't opt in or its DB is already in the registry, so it is safe to call on every scan. The database is seeded empty (the worktree's own migrations populate it); cloning from the parent stays an explicit `lerd db:isolate` / `lerd worktree add` choice. Returns true only when it created the database this call.

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 IdleSuspendStateIsStale ¶ added in v1.25.0

func IdleSuspendStateIsStale(site *config.Site) bool

IdleSuspendStateIsStale reports whether a site's persisted idle-suspended set has drifted from reality: a worker it claims to have suspended is actually running. That happens when the workers were (re)started outside the idle engine by an install or relink with an older lerd that didn't reconcile the list. Left uncorrected it wedges the engine into believing the site is asleep forever, so its idle workers never get re-suspended. The engine calls this at startup to discard a stale list rather than seed itself from it.

func InstallChokidar ¶ added in v1.24.0

func InstallChokidar(sitePath string) error

InstallChokidar runs `npm install --save-dev chokidar` in the project (via runNpmCaptured, the shared fnm helper) so Horizon's horizon:listen watcher can resolve chokidar (Vite 8 no longer ships it transitively). Output is folded into the error on failure so the UI can show why it failed.

func InstallPHPVersion ¶ added in v1.23.0

func InstallPHPVersion(version string, w io.Writer) error

InstallPHPVersion builds the FPM image for the given version, registers its quadlet and starts the service, streaming build output to w. It is the programmatic entry point behind the UI's "add PHP version" flow.

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 IsLegacyPHPVersion ¶ added in v1.25.0

func IsLegacyPHPVersion(v string) bool

IsLegacyPHPVersion reports whether v belongs to the frozen legacy tier.

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 IsSupportedPHPVersion ¶ added in v1.23.0

func IsSupportedPHPVersion(v string) bool

IsSupportedPHPVersion reports whether v is a version lerd can install.

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 ListInstallablePresets ¶ added in v1.28.1

func ListInstallablePresets() ([]config.PresetMeta, error)

ListInstallablePresets returns every preset a user can install: the local presets (embedded defaults plus anything already cached) merged with the external store index for add-ons that aren't local yet. The store fetch is best-effort — offline, the local set is returned so the picker still works. Store entries carry enough (versions, image, description) to render the picker; the full definition is fetched on install.

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 NewAuthCmd ¶ added in v1.27.0

func NewAuthCmd() *cobra.Command

NewAuthCmd returns the `auth` command group: sharing host credentials with the project containers.

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:

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.
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 NewCleanupCmd ¶ added in v1.27.0

func NewCleanupCmd() *cobra.Command

NewCleanupCmd returns the cleanup command: reclaim podman disk that lerd's own image rebuilds have orphaned, without ever touching a non-lerd resource.

func NewClientExecCmd ¶ added in v1.28.1

func NewClientExecCmd() *cobra.Command

NewClientExecCmd returns the hidden `client-exec` command every client shim dispatches to. It resolves the service container backing the tool, starts it if it is down, mounts the working directory so dumps and CA certs on the host are reachable, and execs the tool with all arguments passed straight through.

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 NewDNSDisableCmd ¶ added in v1.28.1

func NewDNSDisableCmd() *cobra.Command

NewDNSDisableCmd returns the dns:disable command, which stops lerd-managed DNS, tears down dnsmasq, and moves sites to *.localhost plain HTTP.

func NewDNSEnableCmd ¶ added in v1.28.1

func NewDNSEnableCmd() *cobra.Command

NewDNSEnableCmd returns the dns:enable command, which turns on lerd-managed DNS (dnsmasq + .test + HTTPS) after install and repairs an already-enabled but broken setup.

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 NewDNSRepairCmd ¶ added in v1.28.1

func NewDNSRepairCmd() *cobra.Command

NewDNSRepairCmd returns the dns:repair command, which re-runs the DNS setup (mkcert CA, dnsmasq config, sudoers, resolver, container) to fix a broken but enabled DNS without changing the mode.

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 NewDbMoveCmd ¶ added in v1.24.0

func NewDbMoveCmd() *cobra.Command

NewDbMoveCmd returns the standalone db:move 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 debug 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 NewEnvOverrideCmd ¶ added in v1.23.0

func NewEnvOverrideCmd() *cobra.Command

NewEnvOverrideCmd returns the env:override command, which scaffolds (and optionally seeds) the personal .env.lerd_override file and gitignores it.

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 NewGroupCmd ¶ added in v1.24.0

func NewGroupCmd() *cobra.Command

NewGroupCmd returns the group command for managing site groups: a main site owns a base domain and secondaries occupy subdomains of it.

func NewHorizonCmd ¶ added in v1.0.0

func NewHorizonCmd() *cobra.Command

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

func NewHorizonReloadCmd ¶ added in v1.24.0

func NewHorizonReloadCmd() *cobra.Command

NewHorizonReloadCmd returns the standalone horizon:reload command.

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 NewIdleCmd ¶ added in v1.25.0

func NewIdleCmd() *cobra.Command

NewIdleCmd returns the parent `lerd idle` command: a global on/off toggle, a global timeout, and a status readout. Idle-suspend is a single global policy, not configured per site.

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 NewJSRuntimeCmd ¶ added in v1.25.0

func NewJSRuntimeCmd() *cobra.Command

NewJSRuntimeCmd returns the js:runtime command, the CLI counterpart to the dashboard's bun/Node toggle. It pins js_runtime in the current site's .lerd.yaml and re-syncs the host workers so the dev/Vite worker switches runtime immediately, exactly like the UI does. With no argument it prints the current setting and what it resolves to.

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 NewMCPDisableGlobalCmd ¶ added in v1.28.1

func NewMCPDisableGlobalCmd() *cobra.Command

NewMCPDisableGlobalCmd returns the mcp:disable-global command, the inverse of mcp:enable-global.

func NewMCPEjectCmd ¶ added in v1.28.1

func NewMCPEjectCmd() *cobra.Command

NewMCPEjectCmd returns the mcp:eject command, the inverse of mcp:inject.

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 NewMachineCmd ¶ added in v1.24.0

func NewMachineCmd() *cobra.Command

NewMachineCmd returns the machine parent command for Podman Machine maintenance operations.

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 NewNginxCmd ¶ added in v1.23.0

func NewNginxCmd() *cobra.Command

NewNginxCmd returns the `lerd nginx` command group for the per-site custom nginx override. Saving goes through the same edit service as the web UI, so `nginx -t` validation, backups, and the reload all behave identically.

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 NewNodeManageCmd ¶ added in v1.25.0

func NewNodeManageCmd() *cobra.Command

NewNodeManageCmd returns the node:manage command, which opts the host into lerd-managed Node.js (fnm shims) after the fact, for users who declined at `lerd install` time.

func NewNodeUninstallCmd ¶ added in v0.5.9

func NewNodeUninstallCmd() *cobra.Command

NewNodeUninstallCmd returns the node:uninstall command.

func NewNodeUnmanageCmd ¶ added in v1.25.0

func NewNodeUnmanageCmd() *cobra.Command

NewNodeUnmanageCmd returns the node:unmanage command, which removes lerd's node shims and the fnm-installed Node binaries, leaving a clean system so the user can rely on bun or their own system Node.

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 NewOctaneCmd ¶ added in v1.25.0

func NewOctaneCmd() *cobra.Command

NewOctaneCmd returns the octane parent command with a reload subcommand.

func NewOctaneReloadCmd ¶ added in v1.25.0

func NewOctaneReloadCmd() *cobra.Command

NewOctaneReloadCmd returns the standalone octane:reload 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 NewPestBrowserCmd ¶ added in v1.25.0

func NewPestBrowserCmd() *cobra.Command

NewPestBrowserCmd returns the pest:browser parent command, which sets up in-container Pest browser testing. Pest drives Playwright locally where the tests run, so the browser must live in the PHP-FPM container. This bakes Alpine's musl chromium into the shared image (opt-in, like php:pkg) and shims Playwright's glibc browser to it, so no per-site Containerfile is needed.

func NewPhpBunCmd ¶ added in v1.25.0

func NewPhpBunCmd() *cobra.Command

NewPhpBunCmd returns the php:bun parent command, which manages an optional in-container bun runtime. lerd never pins or version-manages bun: install pulls the latest musl build into a persistent volume via the bundled npm, and `bun upgrade` (run inside `lerd shell`) self-updates from there.

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 NewPhpPkgCmd ¶ added in v1.25.0

func NewPhpPkgCmd() *cobra.Command

NewPhpPkgCmd returns the php:pkg parent command, which manages extra Alpine packages baked into the PHP-FPM image's runtime stage. Unlike php:bun (a runtime install into a volume), these are layered into the image at build time and re-applied on every rebuild, like php:ext.

func NewPhpPortsCmd ¶ added in v1.28.1

func NewPhpPortsCmd() *cobra.Command

NewPhpPortsCmd returns the php:ports parent command, which manages extra host ports published on a PHP version's shared FPM container so a process bound inside `lerd shell` is reachable at localhost:PORT. The list is per version and independent; a host port already claimed is shifted to the next free one.

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 NewShimsCmd ¶ added in v1.28.1

func NewShimsCmd() *cobra.Command

NewShimsCmd returns the `shims` command group for managing the client-tool host shims services expose (mysqldump, pg_dump, psql…). With no subcommand it lists the current state.

func NewSiteDoctorCmd ¶ added in v1.27.0

func NewSiteDoctorCmd() *cobra.Command

NewSiteDoctorCmd returns the `site:doctor` command — framework-agnostic app-level health checks for a single site (distinct from `lerd doctor`, which diagnoses the lerd environment).

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 NewWSLSetupCmd ¶ added in v1.23.0

func NewWSLSetupCmd() *cobra.Command

NewWSLSetupCmd returns `lerd wsl:setup`, which applies the WSL2-specific tweaks the install guide documents: enabling systemd, the journald events logger podman needs for `logs --follow`, mirrored networking in the Windows .wslconfig, trusting the mkcert root CA from Windows browsers, and masking the tray (WSL has no tray host). Everything is idempotent; the only step it can't do for you is `wsl --shutdown`, which has to run from Windows.

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 ProjectHasChokidar ¶ added in v1.24.0

func ProjectHasChokidar(sitePath string) bool

ProjectHasChokidar is the exported view of projectHasChokidar, for the UI snapshot to report whether Horizon auto-reload can be enabled for a site.

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 gracefully restarts the queue worker by running the framework's RestartCommand in the FPM container. No-op when the site has no queue unit or the framework declares no restart command (e.g. CodeIgniter).

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 RefreshGlobalAISkills ¶ added in v1.24.0

func RefreshGlobalAISkills(home string, verbose bool) error

RefreshGlobalAISkills re-writes only the user-scope context docs that already exist, so `lerd update` keeps them aligned with the installed binary's tool set without creating files (~/.codex/AGENTS.md, ~/.gemini/GEMINI.md) for clients the user never enabled.

func RefreshProjectAISkills ¶ added in v1.24.0

func RefreshProjectAISkills(abs string, verbose bool) error

RefreshProjectAISkills re-writes only the per-project artefacts a client was already set up with, so `lerd update` keeps existing files current without expanding a project's footprint with files for clients it never opted into. A project that set mcp_inject: false in .lerd.yaml is skipped entirely so lerd never touches its committed config on a self-update.

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 RegenerateHostProxyVhostsOnGatewayChange ¶ added in v1.24.0

func RegenerateHostProxyVhostsOnGatewayChange()

RegenerateHostProxyVhostsOnGatewayChange rewrites every host-proxy site's nginx vhost so the host-gateway IP baked into proxy_pass (Linux only) tracks a network change, then reloads nginx. Wired to the host-gateway watcher from main. No-op on macOS, where the upstream is the gvproxy-resolved host.containers.internal hostname rather than a literal IP.

func RegenerateHostWorkersForSite ¶ added in v1.25.0

func RegenerateHostWorkersForSite(s config.Site)

RegenerateHostWorkersForSite rewrites and restarts (only when changed) the host worker units of one site, so a JS-runtime change (e.g. flipping js_runtime to bun from the dashboard) takes effect on its Vite/dev worker without a manual restart. Best-effort. Paused/ignored sites are skipped so a runtime toggle does not resurrect a worker the user stopped.

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 across the whole client registry: context docs, global MCP config entries, and the Claude Code user-scope registration.

func RemoveProjectAISkills ¶ added in v1.18.0

func RemoveProjectAISkills(abs string, verbose bool) error

RemoveProjectAISkills removes every lerd-owned artefact under abs across the client registry: project MCP config entries and context docs. Opt-out counterpart of WriteProjectAISkills.

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 ResumeWorkersForIdle ¶ added in v1.25.0

func ResumeWorkersForIdle(site *config.Site, workers []string)

ResumeWorkersForIdle restarts workers previously suspended by idle-suspend. Idempotent: starting an already-running worker is harmless, which lets the engine self-heal stale suspended state after a `lerd start` restarted them.

func ResumeWorktreeWorkersForIdle ¶ added in v1.25.0

func ResumeWorktreeWorkersForIdle(site *config.Site, wtPath string, workers []string)

ResumeWorktreeWorkersForIdle restarts a worktree's previously suspended workers. Idempotent, like ResumeWorkersForIdle.

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 RunMCPDisableGlobal ¶ added in v1.28.1

func RunMCPDisableGlobal() error

RunMCPDisableGlobal tears down the user-scope lerd MCP registration.

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 SetSitePinned ¶ added in v1.25.0

func SetSitePinned(name string, pinned bool) error

SetSitePinned toggles whether a site is excluded from idle-suspend. It delegates to the locked, single-field config mutator so a pin/unpin can't clobber a concurrent idle-engine write (the old FindSite -> mutate -> AddSite replaced the whole record and would lose a SetSiteIdleSuspendedWorkers write that raced it).

func SetWorktreeDBIsolated ¶ added in v1.19.0

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

func SetupHostProxyWorktree ¶ added in v1.24.0

func SetupHostProxyWorktree(site config.Site, wtPath, wtDomain string) error

SetupHostProxyWorktree wires a host-proxy site's worktree: it mirrors the parent's dev command on a per-worktree port, generates the worktree proxy vhost, and starts the dev server from the worktree checkout. The unit name (lerd-app-<site>-<branch>) and teardown are handled by the shared per-worktree worker machinery.

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 SiteHasOctane ¶ added in v1.25.0

func SiteHasOctane(sitePath string) bool

SiteHasOctane returns true if composer.json lists laravel/octane 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 a Stripe secret is present in the site's .env under its configured or any recognised env key.

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 and webhook path from the project's .env and .lerd.yaml.

func StripeStopForSite ¶ added in v0.6.0

func StripeStopForSite(siteName string) error

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

func SuspendWorkersForIdle ¶ added in v1.25.0

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

SuspendWorkersForIdle stops ALL of the site's running workers (queue, Horizon, scheduler, Stripe, vite, ...) and returns the names to persist as Site.IdleSuspendedWorkers. An idle site does no background work.

Vite is the one special case: stopping it makes Laravel's @vite directive fall back to the built asset manifest, so a site with no build would serve a broken page. So before sleeping we ensure a usable build exists (running `npm run build` if missing) and clear public/hot; if no build can be produced, vite is left running for that site. Idempotent.

The returned set also includes declared workers whose unit was removed entirely (see appendLostSuspended), so an idle site whose persisted suspended list was wiped while its units stayed gone (e.g. a reinstall) is re-marked as sleepy rather than left showing as "off" with no way for the engine to recover it.

func SuspendWorktreeWorkersForIdle ¶ added in v1.25.0

func SuspendWorktreeWorkersForIdle(site *config.Site, wtPath string) []string

SuspendWorktreeWorkersForIdle stops a git worktree's own per-worktree workers (for Laravel that's just vite) by their worktree unit names and returns the names stopped, for the caller to persist. Mirrors SuspendWorkersForIdle but targets lerd-<w>-<site>-<wtBase> units and runs the vite build in the worktree checkout so a sleeping worktree serves built assets. wtPath is the worktree's checkout directory.

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 WorktreeHostPort ¶ added in v1.24.0

func WorktreeHostPort(parentPort int, wtPath, portEnvKey string) int

WorktreeHostPort returns the dev-server port for a host-proxy site's worktree: the value persisted in the worktree's .env if present, otherwise a freshly allocated free port (best-effort persisted so it stays stable). A worktree is reached by its domain, so a floating port until a .env exists is harmless.

func WorktreeIdleSuspendStateIsStale ¶ added in v1.25.0

func WorktreeIdleSuspendStateIsStale(site *config.Site, wtBase string, suspended []string) bool

WorktreeIdleSuspendStateIsStale is IdleSuspendStateIsStale for a single git worktree: it reports whether the worktree's persisted idle-suspended set has drifted from reality (a worker it claims suspended is actually running, e.g. an install/relink restarted it without clearing the slot). The engine calls it at startup so a stale worktree list is discarded rather than seeded from, which would wedge the worktree as suspended forever and never re-suspend it.

func WriteGlobalAISkills ¶ added in v1.17.0

func WriteGlobalAISkills(home string, verbose bool) error

WriteGlobalAISkills writes the user-scope context/instructions docs for every client in the registry (SKILL.md, lerd.mdc, guidelines.md, GEMINI.md, AGENTS.md), creating any that are missing. Called from mcp:enable-global. MCP registration itself is handled separately by writeGlobalMCPConfigs.

func WriteProjectAISkills ¶ added in v1.18.0

func WriteProjectAISkills(abs string, verbose bool) error

WriteProjectAISkills writes the per-project AI artefacts for abs by iterating the aiClients registry, creating every client's files. MCP config files and sentinel context docs preserve non-lerd entries; overwrite docs (SKILL.md, lerd.mdc) are replaced only when their content changed. verbose=true prints each written path. This is the opt-in path (mcp:inject).

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 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 debug 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 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

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL