CLI Reference

The supported operator CLI is the native system-level pmdocs binary. Install it through Homebrew or the Valkyrian Labs Debian repository.

The npm package @valkyrianlabs/payload-markdown-docs installs the Payload plugin and runtime helpers only. It does not provide the supported CLI surface.

Examples use main-docs as a sample docs set slug. Replace it with the Payload docs set slug for your upstream docs package.

install

Debian/Ubuntu:

1sudo install -d -m 0755 /etc/apt/keyrings2sudo curl -fsSL https://apt.valkyrianlabs.com/pubkey.gpg \3  -o /etc/apt/keyrings/valkyrianlabs.gpg4sudo chmod 0644 /etc/apt/keyrings/valkyrianlabs.gpg5 6echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/valkyrianlabs.gpg] https://apt.valkyrianlabs.com stable main" | \7  sudo tee /etc/apt/sources.list.d/valkyrianlabs.list > /dev/null8 9sudo apt-get update10sudo apt-get install -y pmdocs11 12pmdocs --version13pmdocs --help

Homebrew:

1brew tap valkyrianlabs/tap2brew install pmdocs3 4pmdocs --version5pmdocs --help

doctor

1pmdocs doctor

Prints local native CLI diagnostics. It does not check networking, Payload server configuration, auth, OIDC, or signing.

validate

1pmdocs validate --source main-docs2pmdocs validate ./docs --source main-docs

Validates the conventional docs package by building and validating an in-memory manifest. By default this includes Markdown docs from ./docs, skill artifacts from ./skills/<source> when that directory exists, and optional custom llms.txt / llms-full.txt fallback assets when present. The default ./skills directory is optional; only an explicitly supplied missing --skills <path> fails validation.

manifest

1pmdocs manifest --source main-docs --pretty2pmdocs manifest ./docs --source main-docs --pretty

Prints manifest JSON. Docs records remain under files; skill artifacts and optional custom static fallback files are emitted under assets.

plan

1pmdocs plan --source main-docs2pmdocs plan ./docs --source main-docs

Plans against an optional local existing-records JSON file. Without --existing, all valid docs are planned as creates.

keygen

1pmdocs keygen --out .docs-sync

Generates Ed25519 PEM keys for signed sync. Add the public key to an Ed25519 record in Docs Globals > Access. push also accepts unencrypted OpenSSH Ed25519 private keys when the matching ssh-ed25519 ... public key is stored in Access.

push

push uploads the conventional docs package by default:

• docs from ./docs as manifest files
• skills from ./skills/<source> as manifest assets when that directory exists
• ./llms.txt and ./llms-full.txt as optional custom static fallback assets when present

Projects do not need to ship native skills. A missing default ./skills directory is skipped during push; pass --no-skills to opt out explicitly or --skills <path> when skills live somewhere else.

Ed25519:

1pmdocs push \2  --endpoint "$DOCS_SYNC_ENDPOINT" \3  --source main-docs \4  --key-id local-docs \5  --private-key-env DOCS_SYNC_PRIVATE_KEY

Explicit dry-run:

1pmdocs push \2  --endpoint "$DOCS_SYNC_ENDPOINT" \3  --source main-docs \4  --key-id local-docs \5  --private-key-env DOCS_SYNC_PRIVATE_KEY \6  --dry-run

GitHub OIDC:

1pmdocs push \2  --endpoint "$DOCS_SYNC_ENDPOINT" \3  --source <docs-set-slug> \4  --github-oidc

push defaults to sync mode. --dry-run submits a validation-only request. --publish is separate from sync mode and requests published output. Publishing and writes remain server-owned.

If assets are included and public Next asset route files are missing from the current working tree, push prints a warning. Add --strict-routes in CI to turn that warning into a failure.

Common push flags:

• --endpoint <url>
• --source <id>
• --docs <path>
• --skills <path>
• --llms <path>
• --llms-full <path>
• --no-docs
• --no-skills
• --no-llms
• --no-llms-full
• --dry-run
• --strict-routes
• --publish
• --delete-behavior <archive|delete|draft|ignore>

OIDC-specific flags:

• --github-oidc
• --oidc-token-env <env-name>

Pass --source explicitly in CI. The CLI can derive it from GITHUB_REPOSITORY only when the docs set slug matches the repository name, but copied workflow templates should not rely on that fallback.

--repository, --branch, and --commit are optional source metadata flags. They are not required for GitHub OIDC authentication because Payload verifies repository, ref, and SHA from the OIDC token claims.

install skill

1pmdocs install skill --agent codex2pmdocs install skill --agent claude

Installs the bundled payload-markdown-docs AI-agent guidance plus the companion payload-markdown authoring skill for Codex or Claude. Codex defaults to .agents/skills/payload-markdown-docs/ and .agents/skills/payload-markdown/; Claude defaults to .claude/skills/payload-markdown-docs/ and .claude/skills/payload-markdown/. pmdocs skill install remains as a Codex compatibility alias.

Useful flags:

• --out <path>
• --docs-root <path>
• --package-manager <pnpm|npm|yarn|bun>
• --agent <codex|claude>
• --codex
• --claude
• --force
• --dry-run

The installer writes Markdown guidance files only. It does not sync docs or run package manager commands.

install routes

1pmdocs install routes --payload-app "src/app/(payload)"

Installs public Next App Router files that delegate raw AI asset requests to the plugin-owned asset handlers. Commit and deploy these files when a site should serve canonical public routes outside /api:

1/llms.txt2/llms-full.txt3/plugins/<docs-set>/llms.txt4/plugins/<docs-set>/llms-full.txt5/plugins/<docs-set>/skills/<agent>6/plugins/<docs-set>/skills/<agent>/SKILL.md7/plugins/<docs-set>/skills/<agent>.zip8/plugins/<docs-set>/skills/<agent>/<path...>

Useful flags:

• --payload-app <path>
• --force
• --dry-run

install routes does not publish assets. It only creates Next route files. install skill does not publish assets either; it only installs local agent guidance.