LPD CLI

Accurate contributor guide and command reference for the repository lpd CLI.

lpd is the repository CLI for setup, local docs development, governed page moves, testing, hooks, and managed script execution.

Use bash lpd ... until you have run bash lpd setup --yes and confirmed lpd is on your PATH. After that, plain lpd ... is the normal form.

lpd dev defaults to port 3333 when no port is provided. Agent sessions may not use port 3333 via lpd dev, and direct Mint launcher sessions may not use port 3000.

What lpd does

lpd standardizes the main contributor workflows for this repo:

• bootstrap local dependencies
• sync the repo planning skill into the local Codex skills directory
• verify your environment
• run Mint locally
• launch scoped docs previews for large navs
• load alternate docs config files through scoped dev or the custom loader alias
• run tests and CI-like checks
• manage hooks
• move pages with governed docs-path sync
• discover and run repo-managed scripts

Most common workflows

Start local docs

bash lpd setup --yes
lpd dev -- --port 3333

bash lpd setup --yes installs tools/tests dependencies, refreshes hooks, optionally installs lpd on PATH, and syncs agentic-project-management-orchestrator into $CODEX_HOME/skills (fallback: ~/.codex/skills).

Start a scoped Mint session

bash lpd dev --scoped --scope-version v2 --scope-language en --scope-prefix v2/orchestrators

Load an alternate docs config

bash lpd dev --scoped --docs-config docs-orch-work.json
bash lpd dev --scoped --docs-config docs-gate-work.json

Use the custom Mint loader helper

bash tools/dev/preview/mint-custom-loader.sh docs-orch-work.json

Run pre-PR checks

lpd doctor --strict
lpd test --staged
lpd ci --skip-browser

Move a page with governed rewrites

bash lpd move-page v2/orchestrators/setup/old.mdx v2/orchestrators/get-started/new.mdx --check

Command quick index

Command guide

Getting Started

bash lpd setup · command

Bootstrap the local repo environment.

Usage

bash lpd setup [--yes] [--no-tools] [--no-tests] [--no-hooks] [--with-mintlify] [--no-cli] [--no-codex-skills] [--json]

What it does

• installs tools dependencies
• installs tests dependencies
• installs or refreshes git hooks
• optionally installs Mintlify globally
• optionally installs lpd on your PATH
• syncs agentic-project-management-orchestrator into $CODEX_HOME/skills (fallback: ~/.codex/skills)

Examples

bash lpd setup --yes
bash lpd setup --no-tests --no-cli
bash lpd setup --yes --no-codex-skills
bash lpd setup --with-mintlify

Flags

--yes · boolean · default: "false"

Run setup non-interactively with default choices.

--no-tools · boolean · default: "false"

Skip cd tools && npm install.

--no-tests · boolean · default: "false"

Skip cd operations/tests && npm install.

--no-hooks · boolean · default: "false"

Skip .githooks/install.sh.

--with-mintlify · boolean · default: "false"

Run npm i -g mintlify.

--no-cli · boolean · default: "false"

Skip PATH installation for lpd.

--no-codex-skills · boolean · default: "false"

Skip syncing agentic-project-management-orchestrator into the local Codex skills directory.

--json · boolean · default: "false"

Emit the standard JSON status envelope.

lpd doctor · command

Check whether your repo and local environment are ready.

Usage

lpd doctor [--strict] [--json]

Checks

• git repository context
• Node availability
• Mint availability
• tools/node_modules
• operations/tests/node_modules
• hook sync state

Examples

lpd doctor
lpd doctor --strict
lpd --json doctor

Flags

--strict · boolean · default: "false"

Fail with a non-zero exit code if any issue is found.

--json · boolean · default: "false"

Emit the standard JSON status envelope.

lpd help | lpd info | lpd version · command

Use these as the fast discovery commands.

Examples

lpd help
lpd info
lpd version
lpd --json version

Local Dev And Scoped Docs

lpd dev · command

Run the local docs dev launcher.

Usage

lpd dev [--test] [--test-mode fast|staged|full] [--script [path]] [--dry-run] [--scoped] [--docs-config [path]] [--scope-interactive] [--scope-list] [--scope-file [path]] [--scope-version [csv]] [--scope-language [csv]] [--scope-tab [csv]] [--scope-prefix [csv]] [--skip-external-fetch] [--disable-openapi] [-- ...mint args]

What --scoped does Generates a reduced dev-only Mint profile so large docs nav trees start faster and route changes are lighter when you are filtering the main docs navigation. Scope inputs are validated before any setup work runs (hooks, patches, fetches) so bad tab names fail immediately.

Tab name matching Tab names are case-insensitive and support fuzzy matching. You do not need to quote multi-word tab names. The matcher resolves partial names using prefix, substring, and stem matching:

• Resources resolves to Resource HUB
• Orch resolves to Orchestrators
• LP resolves to LP Token
• Internal resolves to Internal Hub

If a partial name matches more than one tab, the command fails with a list of ambiguous matches.

Examples

lpd dev
lpd dev -- --port 3333
lpd dev --test --test-mode staged
lpd dev --scoped --scope-version v2 --scope-language en --scope-tab Developers
lpd dev --scoped --scope-tab Resources
lpd dev --scoped --scope-tab About, Solutions
lpd dev --scoped --scope-tab About --scope-tab Solutions
lpd dev --scoped --scope-prefix v2/orchestrators
lpd dev --scoped --scope-interactive
lpd dev --scoped --scope-list
lpd dev --dry-run --scoped --scope-prefix v2/orchestrators

Recommended use Use lpd dev --scoped for filtered previews of the main docs navigation and for alternate scoped navigation files such as docs-orch-work.json or docs-gate-work.json.

Advanced distinction

--docs-config [path] · string · default: ""

Use an alternate docs config as the scoped navigation source. Scoped dev keeps Mint on a projected workspace and rewrites the active workspace-root docs.json when this source file changes.

--scope-file [path] · string · default: ""

Load scoped selection settings from JSON. This is for filters such as versions, languages, tabs, prefixes, and optional disableOpenapi.

Flags

--test · boolean · default: "false"

Run advisory tests before starting the dev server.

--test-mode fast|staged|full · enum · default: "fast"

Choose which advisory test mode to run with --test.

--script [path] · string · default: "tools/dev/preview/mint-dev.sh"

Override the launcher script path.

--dry-run · boolean · default: "false"

Print the resolved launcher command and scoped settings, then exit.

--scoped · boolean · default: "false"

Enable scoped Mint profile generation.

--scope-interactive · boolean · default: "false"

Prompt for scoped filters interactively.

--scope-list · boolean · default: "false"

Print available versions, languages, and tab names from docs.json, then exit. Use this to discover valid scope values before running a scoped session.

--scope-version [csv] · string · default: "all"

Limit included versions.

--scope-language [csv] · string · default: "all"

Limit included languages.

--scope-tab [csv] · string · default: "all"

Limit included tabs. Supports fuzzy matching: partial names, prefix matches, and stem matches resolve automatically. Multi-word tab names do not require quotes. Multiple tabs can be comma-separated or passed as repeated flags.

--scope-prefix [csv] · string · default: "all"

Limit included routes by prefix such as v2/orchestrators.

--skip-external-fetch · boolean · default: "false"

Set MINT_SKIP_EXTERNAL_FETCH=1 for this run.

--disable-openapi · boolean · default: "false"

Exclude OpenAPI routes from the scoped profile.

-- · separator

Pass the remaining arguments to the Mint launcher.

lpd mint dev · command

Compatibility alias to lpd dev.

Usage

lpd mint dev [--scoped] [--scope-...] [-- ...mint args]

Examples

lpd mint dev
lpd mint dev -- --port 3333
lpd mint dev --scoped --scope-prefix v2/orchestrators

mint-custom-loader helper · command

Thin alias for lpd dev --scoped --docs-config.

Usage

bash tools/dev/preview/mint-custom-loader.sh <custom-docs-json> [-- ...mint args]

Examples

bash tools/dev/preview/mint-custom-loader.sh docs-orch-work.json
bash tools/dev/preview/mint-custom-loader.sh docs-gate-work.json -- --port 3333

Use this when

• you want a shorter alias for lpd dev --scoped --docs-config ...
• you want alternate navigation from docs-gate-work.json
• you want a custom docs config, not just a filtered view of the main docs nav

Validation And CI

lpd test · command

Run the main test suite with optional integration checks.

Usage

lpd test [--staged|--full] [--browser] [--domain v1|v2|both] [--wcag] [--wcag-no-fix] [--link-audit-external] [--base-url URL] [--json]

Examples

lpd test --staged
lpd test --staged --wcag
lpd test --full --link-audit-external
lpd test --browser
lpd test --domain both --base-url http://localhost:3000

lpd ci · command

Run the local CI-like validation flow.

Usage

lpd ci [--skip-browser] [--base-url URL] [--json]

Examples

lpd ci
lpd ci --skip-browser
lpd ci --base-url http://localhost:3000

lpd ai-sitemap · command

Generate or validate sitemap-ai.xml.

Usage

lpd ai-sitemap [--write|--check] [--json]

Examples

lpd ai-sitemap --check
lpd ai-sitemap --write
lpd --json ai-sitemap --check

Page Operations

lpd move-page · command

Move a docs page with governed rewrites.

Usage

bash lpd move-page <old> <new> [--yes] [--check] [--no-stage] [--json]

What it does

• runs git mv
• runs governed docs-path sync
• stages related rewrites unless you opt out

Examples

bash lpd move-page v2/orchestrators/setup/old.mdx v2/orchestrators/get-started/new.mdx --check
bash lpd move-page v2/orchestrators/setup/old.mdx v2/orchestrators/get-started/new.mdx --yes

Flags

--yes · boolean · default: "false"

Auto-confirm the move.

--check · boolean · default: "false"

Dry-run the move path sync flow.

--no-stage · boolean · default: "false"

Do not stage rewritten files after the move.

--json · boolean · default: "false"

Emit the standard JSON status envelope.

Hooks And Script Runner

lpd hooks · command

Manage hooks or run .githooks scripts.

Usage

lpd hooks <install|status|verify|info|<hook-script tokens...>> [-- script args]

Examples

lpd hooks install
lpd hooks status
lpd hooks verify
lpd hooks info
lpd hooks verify-browser --dry-run

Built-in subcommands

install · subcommand

Install or update .git/hooks/pre-commit from .githooks/pre-commit.

status · subcommand

Check whether the installed hook exists, is executable, and matches source.

verify · subcommand

Run .githooks/verify.sh.

info · subcommand

Print hook scripts, bypass flags, and human-only override trailers.

<hook-script tokens...> · subcommand

Fallback resolution into managed scripts under .githooks/.

lpd scripts list · command

List managed scripts across tools, tasks, tests, v2, and hooks.

Usage

lpd scripts list [--group tools|tasks|tests|v2|hooks] [--show-ignored] [--json]

Examples

lpd scripts list
lpd scripts list --group tools
lpd scripts list --group hooks --show-ignored
lpd --json scripts list --group tests

lpd scripts run · command

Resolve and run a managed script.

Usage

lpd scripts run <group> <script-path tokens...> [--dry-run] [--yes] [--json] [-- script args]

Examples

lpd scripts run tools dev authoring add-callouts -- --help
lpd scripts run tasks run-audit --dry-run
lpd scripts run tasks run-audit --yes

Inputs

GROUP · enum · required

One of tools, tasks, tests, v2, or hooks.

<script-path tokens...> · string · required

Space-delimited command path that resolves to a discovered script.

Flags

--dry-run · boolean · default: "false"

Prints the resolved executable command and exits.

--yes · boolean · default: "false"

Auto-confirms high-risk script groups.

--json · boolean · default: "false"

Enables JSON status envelope output.

-- · separator

Passes remaining args to the resolved script target. Example: lpd scripts run tools dev authoring add-callouts -- --help

lpd <tools|tasks|tests|v2> · command

Group shorthand alias for lpd scripts run <group> ....

Usage

lpd tools <script-path tokens...> [-- script args]
lpd tasks <script-path tokens...> [-- script args]
lpd tests <script-path tokens...> [-- script args]
lpd v2 <script-path tokens...> [-- script args]

Examples

lpd tools dev authoring add-callouts -- --help
lpd tests unit lpd-scoped-mint-dev.test -- --help
lpd v2 wcag-repair-common -- --staged --stage

Script risk model · command

Scripts are assigned risk by group and may require confirmation.

Usage

low: tests
medium: tools, hooks
high: tasks, v2

Examples

lpd scripts run tasks run-audit
lpd scripts run tasks run-audit --yes

High-risk groups prompt for confirmation unless --yes is supplied. In non-interactive mode, high-risk commands fail without --yes.

Human-only override trailers: git commit -m "msg" --trailer "allowlist-edit=true" and git commit -m "msg" --trailer "allow-deletions=true".

Troubleshooting And JSON Output

`lpd` not found · troubleshooting

Run:

bash lpd setup --yes

Then open a new shell or source your shell rc file. Until PATH is updated, use bash lpd ....

Hook mismatch · troubleshooting

Run:

lpd hooks status
lpd hooks install
lpd hooks verify

Slow Mint startup on large navs · troubleshooting

Prefer scoped mode:

lpd dev --scoped --scope-prefix v2/orchestrators

For alternate docs configs, use the helper:

bash tools/dev/preview/mint-custom-loader.sh docs-orch-work.json
bash tools/dev/preview/mint-custom-loader.sh docs-gate-work.json

JSON output · response

Many commands support the standard finish-envelope JSON output.

Examples

lpd --json version
lpd doctor --json
lpd ci --json
lpd scripts list --group tools --json

The envelope typically includes:

• command label
• status
• message
• command-specific payload where supported

Script Catalog

For generated full script metadata (script path, summary, usage, domain), see scripts-catalog.

Troubleshooting

lpd not found

Use the repo-local fallback and verify setup:

bash lpd setup --yes
bash lpd version

If needed, reload your shell rc file (source ~/.zshrc or equivalent).

Hooks mismatch

Check and reinstall hooks:

lpd hooks status
lpd hooks install
lpd hooks verify

--json expectations

Global JSON mode is prefix form: lpd --json <command> .... Some commands also accept local --json. lpd info --json is invalid because info only accepts --help|-h.

Port collision on lpd dev

Pass a port through the launcher:

lpd dev -- --port 3334

Slow startup or slow route changes on very large docs.json

Use scoped dev mode so Mint loads only the version, language, tab, or prefix you are actively editing:

lpd dev --scoped --scope-version v2 --scope-language en --scope-tab Developers

Interactive picker:

lpd dev --scoped --scope-interactive

JSON Output

When JSON mode is active on finish-based commands, output uses this status envelope:

JSON Output Envelope

ok · boolean

true for success and false for failure.

command · string

Normalised command label (for example: test, scripts list, hooks status).

message · string

Human-readable summary of the command result.

exit_code · number

Exit code returned by the command path.

repo_root · string

Absolute repo root used during command execution.

Example:

{
  "ok": true,
  "command": "version",
  "message": "lpd 0.2.0",
  "exit_code": 0,
  "repo_root": "/path/to/livepeer-docs-repo"
}

lpd info does not emit a structured JSON envelope. Use JSON mode with commands that complete via finish().