### Initialize project setup

Source: https://geodro.github.io/lerd/features/project-setup

Run this command from the project root to start the automated setup wizard.

```bash
cd ~/Projects/my-app
lerd setup
```

--------------------------------

### AI Assistant Project Setup

Source: https://geodro.github.io/lerd/usage/frameworks

Example of using an AI assistant for project creation, linking, and environment setup.

```python
project_new(path: "/home/user/code/myapp")
site_link(path: "/home/user/code/myapp")
env_setup(path: "/home/user/code/myapp")
```

--------------------------------

### Setup steps selection prompt

Source: https://geodro.github.io/lerd/features/project-setup

The interactive checkbox list used to select which installation and configuration steps to execute.

```text
? Select setup steps to run:
  ◉ composer install
  ◉ npm ci
  ◉ lerd env
  ◯ lerd mcp:inject
  ◉ php artisan migrate
  ◯ php artisan db:seed
  ◉ php artisan storage:link
  ◉ npm run build
  ◯ lerd secure
  ◉ queue:start
  ◉ lerd open
```

--------------------------------

### Install Lerd from Source

Source: https://geodro.github.io/lerd/getting-started/installation

Clone the repository and use make to build and install the binary.

```bash
git clone https://github.com/geodro/lerd
cd lerd
make build
make install            # installs to ~/.local/bin/lerd
make install-installer  # installs lerd-installer to ~/.local/bin/
```

--------------------------------

### Link and Setup Project After Creation

Source: https://geodro.github.io/lerd/usage/frameworks

After creating a new project, use 'lerd link' and 'lerd setup' to register and bootstrap the site.

```bash
cd myapp
lerd link
lerd setup
```

--------------------------------

### Start Symfony Messenger Consumer

Source: https://geodro.github.io/lerd/usage/queue-workers

Example of starting a specific framework worker, the Symfony Messenger consumer. It shows the command and how to view its logs.

```bash
lerd worker start messenger
# Systemd unit: lerd-messenger-myapp.service
# Logs: journalctl --user -u lerd-messenger-myapp -f
```

--------------------------------

### Install Lerd via One-line Installer

Source: https://geodro.github.io/lerd/getting-started/installation

Use curl or wget to download and execute the installation script.

```bash
curl -fsSL https://raw.githubusercontent.com/geodro/lerd/main/install.sh | bash
```

```bash
wget -qO- https://raw.githubusercontent.com/geodro/lerd/main/install.sh | bash
```

--------------------------------

### Install Lerd from Local Build

Source: https://geodro.github.io/lerd/getting-started/installation

Use a previously built binary to perform the installation.

```bash
make build
bash install.sh --local ./build/lerd
```

--------------------------------

### Manage Lerd services and environment

Source: https://geodro.github.io/lerd/changelog

Commands for installing, starting, and stopping the Lerd infrastructure.

```bash
lerd install
```

```bash
lerd start
```

```bash
lerd stop
```

```bash
lerd service start
```

```bash
lerd service restart
```

--------------------------------

### Start Queue Worker with Options

Source: https://geodro.github.io/lerd/usage/queue-workers

Starts the queue worker with specific options for queue name, retries, and timeout. This example demonstrates configuring the worker's behavior.

```bash
cd ~/Lerd/my-app
lerd queue:start --queue=emails,default --tries=5 --timeout=120
# Systemd unit: lerd-queue-my-app.service
# Logs: journalctl --user -u lerd-queue-my-app -f
```

--------------------------------

### Framework YAML Schema Example

Source: https://geodro.github.io/lerd/usage/frameworks

Example of a comprehensive YAML schema for defining a framework, including name, label, public directory, detection rules, environment configuration, dependency installation, console commands, workers, setup commands, and log files.

```yaml
# Required
name: symfony                     # slug [a-z0-9-], must match filename stem
label: Symfony                    # display name
public_dir: public                # document root relative to project (e.g. public, web, .)

# Detection rules — any match is sufficient
detect:
  - file: symfony.lock            # file must exist in project root
  - composer: symfony/framework-bundle  # package in composer.json require/require-dev

# Env file configuration
env:
  file: .env                      # primary env file (default: .env)
  example_file: .env.dist         # copied to file if missing (like .env.example for Laravel)
  format: dotenv                  # dotenv (default) | php-const (for wp-config.php style)
  fallback_file: wp-config.php    # used when file doesn't exist (optional)
  fallback_format: php-const      # format for fallback_file (optional)
  url_key: DEFAULT_URI            # env key holding the app URL (default: APP_URL)

  # Per-service env detection and variable injection for `lerd env`
  services:
    mysql:
      detect:
        - key: DATABASE_URL
          value_prefix: "mysql://"
      vars:
        - "DATABASE_URL=mysql://root:lerd@lerd-mysql:3306/{{site}}?serverVersion={{mysql_version}}"
    redis:
      detect:
        - key: REDIS_URL
        - key: REDIS_DSN
      vars:
        - "REDIS_URL=redis://lerd-redis:6379"

# Scaffold command for "lerd new" — target directory is appended automatically
create: composer create-project myvendor/myframework

# Dependency installation
composer: auto                    # auto | true | false (auto = run if vendor/ missing)
npm: auto                         # auto | true | false (auto = run if node_modules/ missing)

# Console command (without 'php' prefix)
console: artisan                  # artisan (Laravel), bin/console (Symfony), etc.

# Background workers (systemd user services)
workers:
  messenger:
    label: Messenger               # display name (optional)
    command: php bin/console messenger:consume async --time-limit=3600
    restart: always               # always | on-failure (default: always)
    check:                         # only shown when check passes (optional)
      composer: symfony/messenger

# One-off setup commands shown in `lerd setup` wizard
setup:
  - label: "Run migrations"                     # display name and identifier
    command: "php bin/console doctrine:migrations:migrate --no-interaction"
    default: true                               # pre-selected in the wizard
    check:                                      # only shown when check passes (optional)
      composer: doctrine/doctrine-migrations-bundle
  - label: "Load fixtures"
    command: "php bin/console doctrine:fixtures:load --no-interaction"
    check:
      composer: doctrine/doctrine-fixtures-bundle  # skipped if package not installed

# Application log files shown in the UI "App Logs" tab
logs:
  - path: "var/log/*.log"             # glob relative to project root
    format: raw                       # monolog | raw (plain text, default)

```

--------------------------------

### Install Build Dependencies

Source: https://geodro.github.io/lerd/features/system-tray

System-specific commands to install the required libayatana-appindicator library for building the tray.

```bash
sudo pacman -S libayatana-appindicator
```

```bash
sudo apt install libayatana-appindicator3-dev
```

```bash
sudo dnf install libayatana-appindicator-gtk3
```

--------------------------------

### Bootstrap a New Laravel Project with Lerd

Source: https://geodro.github.io/lerd/getting-started/quick-start

Use `lerd setup` for a freshly cloned project to run all standard setup steps. A checkbox list allows you to toggle steps before execution.

```bash
cd ~/Lerd/my-app
lerd setup
```

--------------------------------

### Lerd Initialization Wizard Output

Source: https://geodro.github.io/lerd/usage/sites

Example output showing the interactive configuration process for PHP, HTTPS, database, and services.

```text
? PHP version: 8.4
? Node version (leave blank to skip):
? Enable HTTPS? No
? Database:
  > SQLite (no service)
    MySQL (lerd-mysql)
    PostgreSQL (lerd-postgres)
? Services:
  ◉ redis
  ◯ meilisearch
  ◯ rustfs
  ◯ mailpit
Saved .lerd.yaml
Linked: my-app -> my-app.test (PHP 8.4, Node 22, Framework: laravel)
```

--------------------------------

### Project Creation & Setup

Source: https://geodro.github.io/lerd/reference/commands

Commands for scaffolding new projects and configuring project-specific settings.

```APIDOC
## Lerd Project Management

### Description
Commands to scaffold new PHP projects and bootstrap project environments.

### Commands
- `lerd new <name>` - Scaffold a new PHP project.
- `lerd init` - Wizard to configure PHP version, HTTPS, and services.
- `lerd setup` - Bootstrap a project by running initialization and setup steps.
```

--------------------------------

### Start Stripe webhook listener

Source: https://geodro.github.io/lerd/usage/stripe

Commands to start forwarding Stripe webhooks to the local application.

```bash
cd ~/Lerd/myapp
lerd stripe:listen                         # forwards to https://myapp.test/stripe/webhook
lerd stripe:listen --path /webhooks/stripe # custom webhook path
lerd stripe:listen --api-key sk_test_...   # override key
```

--------------------------------

### Conditional npm Install with Lockfile

Source: https://geodro.github.io/lerd/changelog

The `lerd setup` command now uses `npm ci` if a lockfile (`package-lock.json` or `yarn.lock`) is present, falling back to `npm install` otherwise. This prevents failures on projects without lockfiles.

```bash
npm ci
npm install
```

--------------------------------

### Setup & Lifecycle Commands

Source: https://geodro.github.io/lerd/reference/commands

Commands for managing the Lerd environment lifecycle, updates, and system diagnostics.

```APIDOC
## Lerd Setup & Lifecycle

### Description
Commands to install, start, stop, and maintain the Lerd environment.

### Commands
- `lerd install` - One-time setup of directories, network, binaries, and services.
- `lerd start` - Start DNS, nginx, and PHP-FPM containers.
- `lerd stop` - Stop all Lerd containers and services.
- `lerd quit` - Stop all Lerd processes including UI and tray.
- `lerd update` - Check for and apply updates.
- `lerd doctor` - Run a full environment diagnostic.
```

--------------------------------

### Configure Autostart

Source: https://geodro.github.io/lerd/features/system-tray

Enable or disable the system tray from starting automatically upon user login.

```bash
lerd autostart tray enable
lerd autostart tray disable
```

--------------------------------

### Shell Completion Setup

Source: https://geodro.github.io/lerd/reference/commands

Instructions for setting up shell completion for Lerd in various shells.

```APIDOC
## Shell Completion Setup

### Description
Instructions for setting up shell completion for Lerd in various shells.

### Setup Commands

- **Bash**: `lerd completion bash` (add to `~/.bashrc`)
- **Zsh**: `lerd completion zsh` (add to `~/.zshrc`)
- **Fish**: `lerd completion fish` (add to `~/.config/fish/completions/lerd.fish`)
```

--------------------------------

### Install Laravel Installer Globally with Lerd

Source: https://geodro.github.io/lerd/changelog

Use `lerd install` to globally install `laravel/installer`. This creates a `laravel` shim routed through `lerd php`, allowing direct terminal use.

```bash
lerd install
```

--------------------------------

### Install Node.js Version

Source: https://geodro.github.io/lerd/usage/node

Install a specific Node.js version globally without pinning it to a project.

```bash
lerd node:install 22
```

--------------------------------

### DNS setup check

Source: https://geodro.github.io/lerd/changelog

The `dns.Setup()` function now checks if the necessary content already exists in `/etc/NetworkManager/conf.d/lerd.conf` and `/etc/NetworkManager/dnsmasq.d/lerd.conf`. If the configuration is already correct, it skips all sudo steps, preventing unnecessary password prompts during updates via the UI.

```go
func SetupDNS() error {
	// Check if DNS is already configured correctly
	if isDNSConfigured() {
		log.Println("DNS already configured.")
		return nil
	}

	// ... proceed with configuration steps requiring sudo ...
	return nil
}

func isDNSConfigured() bool {
	// Check content of NetworkManager config files
	_, err1 := os.Stat("/etc/NetworkManager/conf.d/lerd.conf")
	_, err2 := os.Stat("/etc/NetworkManager/dnsmasq.d/lerd.conf")
	// Add logic here to verify file content matches expected values
	return err1 == nil && err2 == nil // Simplified check
}

```

--------------------------------

### Configure WordPress Framework

Source: https://geodro.github.io/lerd/usage/frameworks

Example configuration for a WordPress project, specifying detection files and environment fallback settings.

```yaml
# ~/.config/lerd/frameworks/wordpress.yaml
name: wordpress
label: WordPress
detect:
  - file: wp-login.php
  - file: wp-config.php
public_dir: .
env:
  fallback_file: wp-config.php
  fallback_format: php-const
composer: false
npm: false
```

```bash
lerd framework add wordpress --from-file ~/.config/lerd/frameworks/wordpress.yaml
lerd link                          # auto-detected as WordPress
```

--------------------------------

### Install script dynamic unit discovery

Source: https://geodro.github.io/lerd/changelog

The `install.sh` script's `cmd_uninstall` function now dynamically discovers units from quadlet files on disk. This ensures that all installed services are correctly identified and removed during uninstallation.

```bash
#!/bin/bash
# ... other script content ...

cmd_uninstall() {
    # Dynamically discover units from quadlet files on disk
    local units=$(find /etc/systemd/user/ -name "*.service" -printf "%f\n" | sed 's/.service//')
    # ... rest of the uninstall logic ...
}

# ... rest of the script ...

```

--------------------------------

### Manage stripe-mock service

Source: https://geodro.github.io/lerd/usage/stripe

Commands to add and start the stripe-mock service.

```bash
lerd service add ~/.config/lerd/services/stripe-mock.yaml
lerd service start stripe-mock
```

--------------------------------

### Run Installer Tests

Source: https://geodro.github.io/lerd/contributing/pull-requests

Execute installer tests using `bats tests/installer/installer.bats`. This is an automated CI check that must pass for merging.

```bash
bats tests/installer/installer.bats

```

--------------------------------

### Example .lerd.yaml configuration output

Source: https://geodro.github.io/lerd/features/project-setup

The output displayed after completing the lerd init wizard, showing the saved configuration.

```text
→ Configuring site...
? PHP version: 8.4
? Node version (leave blank to skip): 22
? Enable HTTPS? No
? Services: [mysql, redis]
Saved .lerd.yaml
Linked: my-app -> my-app.test (PHP 8.4, Node 22, Framework: laravel)
```

--------------------------------

### Service Definition Diff Example

Source: https://geodro.github.io/lerd/reference/configuration

Example of a diff shown when a custom service definition in .lerd.yaml differs from an existing local service definition, prompting for replacement.

```text
~ service/mongodb already exists and differs:

--- service/mongodb (current)
+++ service/mongodb (.lerd.yaml)
@@ -1,4 +1,4 @@
 image: docker.io/library/mongo:7
-description: MongoDB
+description: MongoDB document store
 ...

Replace service/mongodb with the version from .lerd.yaml? (y/N)
```

--------------------------------

### Install Composer dependencies with Lerd

Source: https://geodro.github.io/lerd/usage/php

Run 'composer install' using Lerd's shims. This ensures dependencies are managed within the context of the selected PHP version.

```bash
composer install
```

--------------------------------

### Add Laravel Framework from File

Source: https://geodro.github.io/lerd/usage/frameworks

Use this command to add the Laravel framework configuration using a local YAML file. This starts the Horizon and Pulse workers.

```bash
lerd framework add laravel --from-file horizon.yaml
lerd worker start horizon    # starts lerd-horizon-<sitename>
```

--------------------------------

### Standard Node.js Usage

Source: https://geodro.github.io/lerd/usage/node

Execute standard Node.js commands after Lerd has installed the necessary shims.

```bash
node --version
npm install
npx tsc --init
```

--------------------------------

### Install script user-agent and accept headers

Source: https://geodro.github.io/lerd/changelog

The `install.sh` script now includes `User-Agent: lerd-installer` and `Accept: application/vnd.github+json` headers when making GitHub API requests. This is necessary for unauthenticated requests to avoid 403 errors.

```bash
#!/bin/bash
# ... other script content ...

latest_version() {
    local repo="${1:-geodro/lerd}"
    local url="https://api.github.com/repos/${repo}/releases/latest"
    # Send required headers for unauthenticated requests
    local tag=$(curl -s -H "User-Agent: lerd-installer" -H "Accept: application/vnd.github+json" "$url" | grep -o '"tag_name": "v\([0-9.]*\)"' | head -n 1 | sed 's/"tag_name": "v\(.*\)"/
/
')
    echo "$tag"
}

# ... rest of the script ...

```

--------------------------------

### Configure Symfony Framework

Source: https://geodro.github.io/lerd/usage/frameworks

Example configuration for a Symfony project, including environment variables, service detection, and worker definitions.

```yaml
# ~/.config/lerd/frameworks/symfony.yaml
name: symfony
label: Symfony
detect:
  - file: symfony.lock
  - composer: symfony/framework-bundle
public_dir: public
env:
  file: .env
  example_file: .env.dist
  format: dotenv
  url_key: DEFAULT_URI
  services:
    mysql:
      detect:
        - key: DATABASE_URL
          value_prefix: "mysql://"
        - key: DATABASE_URL
          value_prefix: "mariadb://"
      vars:
        - "DATABASE_URL=mysql://root:lerd@lerd-mysql:3306/{{site}}?serverVersion={{mysql_version}}"
    postgres:
      detect:
        - key: DATABASE_URL
          value_prefix: "postgresql://"
        - key: DATABASE_URL
          value_prefix: "postgres://"
      vars:
        - "DATABASE_URL=postgresql://postgres:lerd@lerd-postgres:5432/{{site}}?serverVersion={{postgres_version}}"
    redis:
      detect:
        - key: REDIS_URL
        - key: REDIS_DSN
      vars:
        - "REDIS_URL=redis://lerd-redis:6379"
    mailpit:
      detect:
        - key: MAILER_DSN
      vars:
        - "MAILER_DSN=smtp://lerd-mailpit:1025"
    meilisearch:
      detect:
        - key: MEILISEARCH_HOST
        - key: MEILISEARCH_DSN
      vars:
        - "MEILISEARCH_HOST=http://lerd-meilisearch:7700"
composer: auto
npm: auto
workers:
  messenger:
    label: Messenger
    command: php bin/console messenger:consume async --time-limit=3600
    restart: always
    check:
      composer: symfony/messenger
setup:
  - label: "Run migrations"
    command: "php bin/console doctrine:migrations:migrate --no-interaction --allow-no-migration"
    default: true
    check:
      composer: doctrine/doctrine-migrations-bundle
  - label: "Load fixtures"
    command: "php bin/console doctrine:fixtures:load --no-interaction"
    check:
      composer: doctrine/fixtures-bundle
  - label: "Clear cache"
    command: "php bin/console cache:clear"
    default: true
```

```bash
lerd framework add symfony --from-file ~/.config/lerd/frameworks/symfony.yaml
lerd link                          # auto-detected as Symfony
lerd setup                         # shows migrations, fixtures, and other steps
lerd worker start messenger        # starts lerd-messenger-<sitename>
```

--------------------------------

### Step failure prompt

Source: https://geodro.github.io/lerd/features/project-setup

The prompt displayed when a setup step encounters an error, allowing the user to decide whether to proceed.

```text
✗ migrate failed: exit status 1
  Continue with remaining steps? [y/N]:
```

--------------------------------

### Add Symfony Framework with Flags

Source: https://geodro.github.io/lerd/usage/frameworks

Quickly add the Symfony framework using command-line flags for label, public directory, detection files, environment settings, and dependency installation.

```bash
lerd framework add symfony \
  --label "Symfony" \
  --public-dir public \
  --detect-file symfony.lock \
  --detect-composer symfony/framework-bundle \
  --env-file .env \
  --env-format dotenv \
  --composer auto \
  --npm auto
```

--------------------------------

### Initialize Project on a New Machine

Source: https://geodro.github.io/lerd/usage/sites

Apply configuration directly from an existing .lerd.yaml file without triggering the interactive wizard.

```bash
git clone ...
cd my-app
lerd init
```

--------------------------------

### Register and Configure New Site with MCP

Source: https://geodro.github.io/lerd/changelog

After scaffolding a new project with `project_new`, use `site_link` and `env_setup` to register the site and configure its environment.

```bash
site_link
env_setup
```

--------------------------------

### Initialize Lerd Project with Database Selection

Source: https://geodro.github.io/lerd/changelog

Use `lerd init` to set up a new project. The wizard now includes a database selection step (sqlite, mysql, postgres) and configures environment variables automatically.

```bash
lerd init
```

--------------------------------

### Install script checks for certutil

Source: https://geodro.github.io/lerd/changelog

The install script now verifies the presence of `certutil` and offers to install it automatically. This is crucial for mkcert to register the CA in browsers like Chrome and Firefox, preventing `ERR_CERT_AUTHORITY_INVALID` errors.

```bash
#!/bin/bash
# ... other script content ...

# Check for certutil and offer to install
if ! command -v certutil &> /dev/null; then
    echo "certutil (nss-tools) is required for mkcert to register the CA."
    read -p "Do you want to attempt to install it? (y/N): " install_certutil
    if [[ "$install_certutil" =~ ^[Yy]$ ]]; then
        # ... installation commands ...
        echo "certutil installed."
    else
        echo "certutil not installed. HTTPS sites may not work."
    fi
fi

# ... rest of the script ...

```

--------------------------------

### Initialize a Lerd Project

Source: https://geodro.github.io/lerd/usage/sites

Run the interactive wizard to configure a project, save settings to .lerd.yaml, and apply the configuration.

```bash
cd ~/Projects/my-app
lerd init
```

--------------------------------

### Start Laravel Horizon

Source: https://geodro.github.io/lerd/usage/queue-workers

Starts Laravel Horizon as a systemd service. This is used when 'laravel/horizon' is present in composer.json.

```bash
lerd horizon:start
```

```bash
lerd horizon start
```

--------------------------------

### Start Generic Worker

Source: https://geodro.github.io/lerd/usage/queue-workers

Starts a named worker for the current project. Use this for any framework-defined worker not covered by specific commands.

```bash
lerd worker start <name>
```

--------------------------------

### Custom Worker Definition Example

Source: https://geodro.github.io/lerd/usage/frameworks

Example of a YAML file defining a custom worker, such as Horizon, to be added to a framework definition.

```yaml
# Example content for horizon.yaml
# This would typically define worker details like command, restart policy, etc.
```

--------------------------------

### Initialize Project Environment

Source: https://geodro.github.io/lerd/features/env-setup

Sets up the .env file for a Laravel project by detecting services and applying connection values.

```bash
cd ~/Lerd/my-app
lerd env
```

--------------------------------

### Start Queue Worker

Source: https://geodro.github.io/lerd/usage/queue-workers

Starts the queue worker for the current project. Use this for frameworks that define a 'queue' worker, like Laravel.

```bash
lerd queue:start
```

```bash
lerd queue start
```

--------------------------------

### Install NSS Tools for mkcert

Source: https://geodro.github.io/lerd/troubleshooting

Install the necessary NSS tools for your distribution to manage browser trust stores for mkcert. This is required for HTTPS certificate warnings.

```bash
sudo pacman -S nss
```

```bash
sudo apt install libnss3-tools
```

```bash
sudo dnf install nss-tools
```

--------------------------------

### Check Prerequisites

Source: https://geodro.github.io/lerd/getting-started/installation

Verify that all required dependencies are present.

```bash
bash install.sh --check
```

--------------------------------

### Create Project with Custom Framework Command

Source: https://geodro.github.io/lerd/usage/frameworks

Use 'lerd new' with the --framework flag to trigger the custom create command defined in the framework's YAML file.

```bash
lerd new myapp --framework=symfony
# runs: composer create-project symfony/skeleton /abs/path/to/myapp
```

--------------------------------

### Prevent Duplicate PATH Entry on Install

Source: https://geodro.github.io/lerd/changelog

The `add_to_path` function in `install.sh` now checks if the install directory is already in `$PATH` before modifying shell rc files. This prevents duplicate entries.

```bash
add_to_path
```

--------------------------------

### Manage Lerd Watcher Service

Source: https://geodro.github.io/lerd/troubleshooting

If the watcher service is not running, check its status with `lerd status` and start it using `systemctl --user start lerd-watcher`. You can also view its live log stream.

```bash
lerd status                            # shows watcher running/stopped
systemctl --user start lerd-watcher   # start it from the terminal
# or use the Start button in the UI → System → Watcher
```

```bash
journalctl --user -u lerd-watcher -f
# or open the live log stream in the UI → System → Watcher
```

```bash
systemctl --user edit lerd-watcher
# Add:
# [Service]

```

--------------------------------

### Check Environment File Synchronization

Source: https://geodro.github.io/lerd/features/env-setup

Compares all .env files against .env.example to identify missing or out-of-sync keys.

```bash
lerd env:check
```

--------------------------------

### Node.js Management

Source: https://geodro.github.io/lerd/reference/commands

Commands for installing, uninstalling, and managing Node.js versions.

```APIDOC
## Node.js Management

### `lerd node:install <version>`

**Description**: Install a Node.js version globally via fnm.

### `lerd node:uninstall <version>`

**Description**: Uninstall a Node.js version via fnm.

### `lerd node:use <version>`

**Description**: Set the default Node.js version.

### `lerd isolate:node <version>`

**Description**: Pin Node version for cwd — writes `.node-version`, runs `fnm install`.

### `lerd node [args...]`

**Description**: Run `node` using the project's pinned version via fnm.

### `lerd npm [args...]`

**Description**: Run `npm` using the project's pinned Node version via fnm.

### `lerd npx [args...]`

**Description**: Run `npx` using the project's pinned Node version via fnm.
```

--------------------------------

### Environment and Configuration

Source: https://geodro.github.io/lerd/features/mcp

Tools for setting up and checking environment configurations.

```APIDOC
## POST /env_setup

### Description
Configure `.env` for lerd: detects services, starts them, creates DB, and sets APP_KEY and APP_URL.

### Method
POST

### Endpoint
/env_setup

### Parameters
#### Request Body
- **path** (string) - Required - The path to the project directory.

### Request Example
```json
{
  "path": "/var/www/my-project"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the environment setup is complete.

#### Response Example
```json
{
  "message": "Environment configured successfully for /var/www/my-project."
}
```
```

```APIDOC
## POST /env_check

### Description
Compare all `.env` files against `.env.example` and flag missing or extra keys.

### Method
POST

### Endpoint
/env_check

### Parameters
#### Request Body
- **path** (string) - Required - The path to the project directory.

### Request Example
```json
{
  "path": "/var/www/my-project"
}
```

### Response
#### Success Response (200)
- **missing_keys** (array) - List of keys present in `.env.example` but missing in `.env`.
- **extra_keys** (array) - List of keys present in `.env` but not in `.env.example`.

#### Response Example
```json
{
  "missing_keys": ["STRIPE_SECRET"],
  "extra_keys": ["LEGACY_VAR"]
}
```
```

--------------------------------

### Manage Lerd on macOS

Source: https://geodro.github.io/lerd/getting-started/installation

Install, update, and uninstall Lerd using Homebrew.

```bash
brew install geodro/lerd/lerd
lerd install
```

```bash
brew upgrade lerd
lerd install
```

```bash
lerd uninstall
brew uninstall lerd
```

--------------------------------

### Queue Worker Management

Source: https://geodro.github.io/lerd/reference/commands

Commands for starting and stopping queue workers for the current project.

```APIDOC
## Queue Worker Management

### `lerd queue:start`

**Description**: Start a queue worker for the current project.

### `lerd queue:stop`

**Description**: Stop the queue worker for the current project.
```

--------------------------------

### Manage parked directories and versions

Source: https://geodro.github.io/lerd/changelog

Commands for linking project directories and switching PHP versions.

```bash
lerd unpark [directory]
```

```bash
lerd use <version>
```

```bash
lerd status
```

--------------------------------

### Build Beta Lerd for Linux

Source: https://geodro.github.io/lerd/getting-started/installation

Build from source using the macos-compat branch.

```bash
git clone -b macos-compat https://github.com/geodro/lerd
cd lerd
make build
bash install.sh --local ./build/lerd
```

--------------------------------

### Specify Framework for Project Creation

Source: https://geodro.github.io/lerd/changelog

When using `lerd new` or `lerd framework add`, you can specify a custom framework using the `--framework` flag. The framework definition must include a `create` property.

```bash
lerd new --framework=<name>
```

--------------------------------

### Add Custom Service with Flags

Source: https://geodro.github.io/lerd/usage/services

Quickly add a custom service using command-line flags for one-off configurations. Ensure all necessary parameters like name, image, ports, and environment variables are provided.

```bash
lerd service add \
  --name mongodb \
  --image docker.io/library/mongo:7 \
  --port 27017:27017 \
  --env MONGO_INITDB_ROOT_USERNAME=root \
  --env MONGO_INITDB_ROOT_PASSWORD=secret \
  --data-dir /data/db \
  --env-var "MONGO_DATABASE={{site}}" \
  --env-var "MONGO_URI=mongodb://root:secret@lerd-mongodb:27017/{{site}}" \
  --detect-key MONGO_URI \
  --init-exec "mongosh admin -u root -p secret --eval \"db.getSiblingDB('{{site}}').createCollection('_init')\""
```

--------------------------------

### Service Management

Source: https://geodro.github.io/lerd/features/mcp

Tools for managing built-in and custom services, including starting, stopping, adding, and configuring them.

```APIDOC
## POST /service_start

### Description
Start a built-in or custom service. If the service has `depends_on` defined, dependencies will start first, and dependent services will start after.

### Method
POST

### Endpoint
/service_start

### Parameters
#### Request Body
- **service_name** (string) - Required - The name of the service to start.

### Request Example
```json
{
  "service_name": "redis"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the service has started.

#### Response Example
```json
{
  "message": "Service 'redis' started successfully."
}
```
```

```APIDOC
## POST /service_stop

### Description
Stop a built-in or custom service. This action cascade-stops any custom services that depend on it first.

### Method
POST

### Endpoint
/service_stop

### Parameters
#### Request Body
- **service_name** (string) - Required - The name of the service to stop.

### Request Example
```json
{
  "service_name": "redis"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the service has stopped.

#### Response Example
```json
{
  "message": "Service 'redis' stopped successfully."
}
```
```

```APIDOC
## POST /service_add

### Description
Register a new custom OCI-based service (e.g., MongoDB, RabbitMQ). Supports `depends_on` for service dependencies.

### Method
POST

### Endpoint
/service_add

### Parameters
#### Request Body
- **service_name** (string) - Required - The name for the new custom service.
- **image** (string) - Required - The Docker image to use for the service.
- **ports** (array) - Optional - An array of port mappings (e.g., `"8080:8080"`).
- **volumes** (array) - Optional - An array of volume mappings (e.g., `"./data:/data"`).
- **environment** (object) - Optional - Key-value pairs for environment variables.
- **depends_on** (array) - Optional - An array of service names that this service depends on.

### Request Example
```json
{
  "service_name": "mongodb",
  "image": "mongo:latest",
  "ports": ["27017:27017"],
  "environment": {
    "MONGO_INITDB_ROOT_USERNAME": "user",
    "MONGO_INITDB_ROOT_PASSWORD": "password"
  },
  "depends_on": ["network"]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the service has been added.

#### Response Example
```json
{
  "message": "Custom service 'mongodb' added successfully."
}
```
```

```APIDOC
## POST /service_remove

### Description
Stop and deregister a custom service.

### Method
POST

### Endpoint
/service_remove

### Parameters
#### Request Body
- **service_name** (string) - Required - The name of the custom service to remove.

### Request Example
```json
{
  "service_name": "mongodb"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the service has been removed.

#### Response Example
```json
{
  "message": "Custom service 'mongodb' removed successfully."
}
```
```

```APIDOC
## POST /service_expose

### Description
Add or remove an extra published port on a built-in service. This change is persisted and will auto-restart if the service is running.

### Method
POST

### Endpoint
/service_expose

### Parameters
#### Request Body
- **service_name** (string) - Required - The name of the built-in service.
- **port** (string) - Required - The port mapping to add or remove (e.g., "5432:5432").
- **action** (string) - Required - Action to perform, either "add" or "remove".

### Request Example
```json
{
  "service_name": "postgres",
  "port": "5432:5432",
  "action": "add"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message about the port change.

#### Response Example
```json
{
  "message": "Port 5432:5432 added to service 'postgres'. Service restarted."
}
```
```

```APIDOC
## GET /service_env

### Description
Return the recommended `.env` connection variables for a built-in or custom service.

### Method
GET

### Endpoint
/service_env

### Parameters
#### Query Parameters
- **service_name** (string) - Required - The name of the service.

### Response
#### Success Response (200)
- **env_variables** (object) - An object containing recommended environment variables.

### Response Example
```json
{
  "env_variables": {
    "DB_HOST": "127.0.0.1",
    "DB_PORT": "5432",
    "DB_DATABASE": "myapp_db",
    "DB_USERNAME": "user",
    "DB_PASSWORD": "password"
  }
}
```
```

```APIDOC
## POST /service_pin

### Description
Pin a service so it is never auto-stopped, even when no sites reference it.

### Method
POST

### Endpoint
/service_pin

### Parameters
#### Request Body
- **service_name** (string) - Required - The name of the service to pin.

### Request Example
```json
{
  "service_name": "redis"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the service has been pinned.

#### Response Example
```json
{
  "message": "Service 'redis' pinned successfully."
}
```
```

```APIDOC
## POST /service_unpin

### Description
Unpin a service, allowing it to be auto-stopped when unused.

### Method
POST

### Endpoint
/service_unpin

### Parameters
#### Request Body
- **service_name** (string) - Required - The name of the service to unpin.

### Request Example
```json
{
  "service_name": "redis"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the service has been unpinned.

#### Response Example
```json
{
  "message": "Service 'redis' unpinned successfully."
}
```
```

--------------------------------

### Composer Extension Validation

Source: https://geodro.github.io/lerd/usage/php

Example output when lerd detects missing PHP extensions required by composer.json.

```text
[!] my-app requires PHP extensions not in the image: swoole
    Run: lerd php:ext add swoole
```

--------------------------------

### Create New Project with Lerd (Framework Agnostic)

Source: https://geodro.github.io/lerd/usage/frameworks

Use 'lerd new' as a framework-agnostic command to scaffold a new project. Specify the framework if it's not the default (Laravel). Extra flags can be passed to the scaffold command using '--'.

```bash
lerd new myapp                          # create ./myapp using Laravel (default)
lerd new myapp --framework=symfony      # create using Symfony's create command
lerd new /path/to/myapp                 # create at an absolute path
lerd new myapp -- --no-interaction      # pass extra flags to the scaffold command
```

--------------------------------

### Create New Laravel Project with Lerd

Source: https://geodro.github.io/lerd/usage/frameworks

Use the 'laravel new' command to scaffold a new Laravel project and then link and set it up with Lerd.

```bash
laravel new myapp
cd myapp
lerd link
lerd setup
```