CLI Reference

The package exposes the payload-markdown-docs binary.

validate

1payload-markdown-docs validate --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

1payload-markdown-docs manifest --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

1payload-markdown-docs plan --source main-docs

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

keygen

1payload-markdown-docs 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:

1payload-markdown-docs 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:

1payload-markdown-docs 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:

1payload-markdown-docs push \2  --endpoint "$DOCS_SYNC_ENDPOINT" \3  --source main-docs \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>

When --source is omitted in GitHub Actions, the CLI derives it from GITHUB_REPOSITORY.

install skill

1payload-markdown-docs install skill --agent codex2payload-markdown-docs install skill --agent claude

Installs native AI-agent guidance from the package skills/ tree and installs the companion @valkyrianlabs/payload-markdown authoring skill beside it. Codex defaults to .agents/skills/payload-markdown-docs/ plus .agents/skills/payload-markdown/ and creates or updates AGENTS.md. Claude defaults to .claude/skills/payload-markdown-docs/ plus .claude/skills/payload-markdown/ and does not update AGENTS.md by default.

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

1payload-markdown-docs 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.