CLI Reference

This page is generated from the repository README and CLI command source so the published reference stays aligned with the shipped package.

Install

npm install -g optymd

Or use directly:

npx optymd scan .
npx optymd scan CLAUDE.md

Command overview

Command	Description
opty diff [path]	Show before/after diff for auto-fixable changes
opty fix [path]	Auto-fix safe issues and interactively review suggestions
opty init [platform]	Scaffold agent config files for a platform
opty restore [path]	Restore agent config files from a backup
opty scan [path]	Scan agent config files and report quality
opty score [path]	Output project quality grade
opty verify [path]	Compare repo behavior with rule intent using local git, repo config, and GitHub evidence when available
opty watch [path]	Watch config files and re-scan on change

opty diff [path]

Show before/after diff for auto-fixable changes

Examples

opty diff .

Options

• No command-specific options.

opty fix [path]

Auto-fix safe issues and interactively review suggestions

Examples

opty fix --dry-run
opty fix .
opty fix . --auto-only

Options

• --dry-run - show fix plan without applying
• --auto-only - only apply AUTO fixes, skip interactive suggestions

opty init [platform]

Scaffold agent config files for a platform

Examples

opty init claude
opty init openclaw

Options

• No command-specific options.

opty restore [path]

Restore agent config files from a backup

Examples

opty restore
opty restore --id 20260416-120301

Options

• --id <id> - specific backup ID to restore

opty scan [path]

Scan agent config files and report quality

Examples

opty scan .
opty scan CLAUDE.md
opty scan . --verbose

Options

• --verbose - include per-file dimension breakdown for the worst 10 files

opty score [path]

Output project quality grade

Examples

opty score .
opty score . --badge

Options

• --badge - output shields.io badge JSON to .opty/badge.json

opty verify [path]

Compare repo behavior with rule intent using local git, repo config, and GitHub evidence when available

Examples

opty verify .
opty verify . --json
opty verify . --fail-on-violations

Options

• --json - output the verify report as JSON
• --fail-on-violations - exit with code 2 when any verify rule is violated

opty watch [path]

Watch config files and re-scan on change

Examples

opty watch .

Options

• No command-specific options.

CI and PR integration

Add opty to your PR workflow for automatic config quality checks or verify-based rule enforcement.

Score mode stays backward compatible and lets you gate on the numeric score:

name: opty
on: [pull_request]
jobs:
  score:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: AytuncYildizli/opty/action@v1
        with:
          path: .
          fail-below: 50

Verify mode runs opty verify --json --fail-on-violations, exposes machine-readable outputs, and fails CI when rule violations are found:

name: opty-verify
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - id: opty
        uses: AytuncYildizli/opty/action@v1
        with:
          mode: verify
          path: .
      - name: Read verify outputs
        run: |
          echo "Spec status: ${{ steps.opty.outputs.spec_status }}"
          echo "Spec adherence: ${{ steps.opty.outputs.spec_adherence }}"
          echo "Violation count: ${{ steps.opty.outputs.violation_count }}"
          echo "Default branch: ${{ steps.opty.outputs.default_branch }}"

Input	Default	Description
mode	score	Action mode: score or verify
path	.	Project root to scan
fail-below	0	Fail CI if score is below this threshold (score mode only, 0-100)
comment	true	Post a score or verify summary as a PR comment (pull_request events only)

Output	Available in	Description
mode	score, verify	Executed action mode
score	score	Parsed score value
grade	score	Parsed score grade
spec_adherence	verify	Verify adherence percentage, blank when unknown
spec_status	verify	Verify status: STABLE, DRIFTING, or UNKNOWN
violation_count	verify	Total counted rule violations
default_branch	verify	Detected default branch
analyzed_ref	verify	Git ref used for local git evidence