PDD CLI

Find missing connections and old assumptions before they pass a review.

The CLI installs catalog principles and checks the current repository. It connects principle definitions, agent indexes, comments, and versioned citations.

Installation

Install the CLI in your repository. Its lock file pins the package version.

npm install --save-dev @principle-driven/cli
npx pdd check

For a one-time check, run the scoped package directly.

npx --yes @principle-driven/cli check

Commands

Repository commands accept a path and --json. Without a path, the CLI uses the current directory as the repository root.

npx pdd check ../other-repository
npx pdd check --json

The path selects the configuration file and the scan root. Run the command from a repository root, or supply that root explicitly.

Add a principle

CLI version 0.2.0 adds catalog installation. Run the command after approval under your repository's admission protocol.

Use pdd --version to read the installed version.

npx --yes @principle-driven/[email protected] catalog
npx --yes @principle-driven/[email protected] add validate-at-use

CLI version 0.2.1 downloads the catalog from the PDD GitHub repository. add selects a principle by its slug, such as validate-at-use.

The CLI uses prefix, principlesDir, and agentFiles from your project configuration. The same defaults apply without a configuration file.

For example, a project whose highest token is SITE-08 receives SITE-09@v1 in docs/principles/site-09-validate-at-use.md.

Existing numbers stay unchanged. The command preserves gaps and reserves numbers from configured indexes and committed principle filenames in Git history.

The installed rule starts at local v1. A Source header identifies the catalog page, and History records the adoption date and catalog version.

The CLI adds a pinned entry to every configured agent index. It preserves existing instructions and creates missing indexes with a short reading instruction.

A repeated installation preserves the existing file and its local version. The command also recognizes manual adoptions by their filename or exact title.

npx pdd add validate-at-use --dry-run
npx pdd add validate-at-use ../other-repository --json

--dry-run previews the exact files without writing them. With --json, the preview includes each file's path and content.

After installation, adapt the Rule, exceptions, and Rationale to your repository. Cite its local pin where a real decision depends on it.

Run pdd check before committing. Your repository owns later edits and version changes.

Installation needs network access to raw.githubusercontent.com. Local checks and repeated installations with a recorded source work offline.

Configuration

Place pdd.config.json at the repository root. The defaults use the prefix PDD, docs/principles, and one root agent index.

{
  "prefix": "PDD",
  "principlesDir": "docs/principles",
  "agentFiles": ["AGENTS.md"],
  "acceptedRiskPrinciple": null,
  "ignore": []
}

Project configuration is available in CLI version 0.1.0. A repository without this file uses the defaults, including an empty ignore list.

Set acceptedRiskPrinciple to your accepted-risk rule's identifier or current pinned token. If your repository has no such rule, set this field to null.

Download the starter configuration.

Token prefix

Each project chooses its own prefix. The prefix must start with an uppercase letter. The remaining characters can be uppercase letters or digits.

For example, SITE uses uppercase tokens and lowercase filenames that start with site-. The heading, token header, filename, and citations must agree.

{
  "prefix": "SITE",
  "principlesDir": "docs/principles",
  "agentFiles": ["AGENTS.md"],
  "acceptedRiskPrinciple": null,
  "ignore": ["examples/**", "fixtures/**"]
}

After a prefix change, rename the principle files and update their headings, token headers, index entries, and citations together.

A prefix change keeps the rule’s version if its meaning stays the same.

Ignored paths

All configured paths are relative to the target repository root. Ignore patterns match complete relative paths.

Use * within one directory and ** across directories. To exclude a directory’s contents, end the pattern with /**.

Ignored files contribute no citation, title-reference, or accepted-risk checks. Principle file validation and required agent index entries still receive their own checks.

The CLI validates pdd.config.json as configuration. It does not scan this file for citations.

Content scans also skip Cargo.lock, composer.lock, Gemfile.lock, package-lock.json, poetry.lock, pnpm-lock.yaml, uv.lock, and yarn.lock.

The toolkit repository

The PDD toolkit repository uses PDD for its own rules. Its catalog, starter files, and fixtures contain example tokens for other projects.

{
  "prefix": "PDD",
  "principlesDir": "docs/principles",
  "agentFiles": [
    "AGENTS.md"
  ],
  "acceptedRiskPrinciple": null,
  "ignore": [
    "catalog/principles/**",
    "catalog/downloads/**",
    "catalog/catalog.json",
    "starter/**",
    "apps/site/public/starter/**",
    "apps/site/src/content/principles/**",
    "apps/site/src/lib/examples.ts",
    "packages/cli/test/**",
    "SETUP.md",
    "skills/pdd-principles/SKILL.md"
  ]
}

Tutorial pages import sample text from one excluded module. Their governing citations stay in the scanned page files.

The toolkit agent index records the setup guide’s dependencies. The website catalog loader records the catalog’s language dependency.

Read the project configuration and the agent index for a working example.

What the CLI checks

• Principle filenames, headings, tokens, versions, and history entries agree.
• Configured agent indexes contain every current principle.
• Citations use known tokens and current versions.
• Principle names in prose have a nearby pinned token.
• Accepted-risk markers cite the configured rule within four lines.

Old citations

A meaning change increments the principle’s version. The checker reports each citation that still uses an earlier version.

$ pdd check

src/jobs/reconcile.ts:48 [PDD106]
PDD-02@v1 is stale; review this site against PDD-02@v2

src/models/restore.ts:91 [PDD202]
ACCEPTED-RISK marker needs PDD-06@v1 within four lines

pdd check: FAILED (2 problems)

Read the current rule and review the code at each reported site. Update its token after that review.

The checker does not rewrite the implementation or approve the decision.

Accepted risks

An accepted-risk marker states a known risk, its reason, and the condition for a new decision.

CLI version 0.1.1 accepts an identifier or a pinned token in acceptedRiskPrinciple. A pinned value requires a new review after the rule changes.

Add this field to your configuration to select the risk rule:

{
  "acceptedRiskPrinciple": "PDD-06@v1"
}

The value must use the configured prefix and a number. The optional version must use @v followed by digits.

Malformed values stop the command with exit code 2. Unknown rules and old pins fail check with exit code 1.

An old configuration pin does not stop checks for markers that lack the current token.

// ACCEPTED-RISK: A restore can reveal one bit about a
// hidden unique field. Integrity has priority. Revisit when
// restore quarantine can make the outcome actor-neutral. PDD-06@v1

The pinned token connects the local risk to the governing rule. Read Make accepted risks explicit for the rule.

Continuous integration

Run the check on every pull request.

- name: Check decision system
  run: npx pdd check

Do not add a path filter. A principle-only change must still expose old code citations.

Exit codes

The --json option preserves these exit codes. A CI job can use the exit code while another tool reads the JSON report.