ProvenanceCode CLI (prvc)

ProvenanceCode CLI is the reference implementation for bootstrapping and validating ProvenanceCode G2 (v2.0) in developer repositories.

🎯 Purpose

The CLI enables developers to:

• ✅ Install and configure ProvenanceCode G2 (v2.0)
• ✅ Scaffold required folder structure
• ✅ Install schemas
• ✅ Generate decision and risk templates
• ✅ Validate records locally
• ✅ Add AI starter packs (Cursor, Claude Code, Antigravity)
• ✅ Optionally add non-blocking CI validation
• ✅ NEW: Quick decision journal for instant capture
• ✅ NEW: Beautiful visualizations (graphs, timelines, stats)
• ✅ NEW: Smart templates for common decision types
• ✅ NEW: Powerful search and discovery
• ✅ NEW: Export to HTML, Markdown, Confluence, Notion, PDF
• ✅ NEW: Quality scoring and impact analysis

✨ What's New in v1.0

We've added 8 powerful features that make ProvenanceCode irresistible for developers:

1. 📝 Decision Journal - Capture decisions instantly like a developer diary
2. 📊 Visualizations - Generate beautiful interactive graphs, timelines, and stats
3. 📋 Smart Templates - 7 opinionated templates for common decisions
4. 🔍 Search & Discovery - Find decisions fast with fuzzy search
5. 📤 Export Anywhere - HTML, Markdown, Confluence, Notion, JSON, PDF
6. 📈 Quality Scoring - Gamified metrics for decision documentation
7. 🎯 Impact Analysis - Understand the blast radius of decisions
8. 🚀 Upgrade Info - Learn about team features in the GitHub App

See FEATURES.md for detailed documentation.

Quick examples:

# Quick journal entry
npx prvc journal add "Use Redis for caching"

# Create from template
npx prvc template use architecture

# Visualize your decisions
npx prvc visualize graph

# Check your quality score
prvc quality

# Export to share
npx prvc export --format=html --theme=dark

Note: All examples use npx prvc (no installation required). If you install globally with npm install -g provenancecode-cli, you can use prvc directly. See USAGE.md for details.

🚫 What the CLI Does NOT Do

The CLI does NOT:

• ❌ Enforce governance workflows
• ❌ Block PR merges
• ❌ Manage approval state
• ❌ Provide dashboards
• ❌ Track decision velocity

The CLI enables adoption. The ProvenanceCode GitHub App governs.

📦 Installation

# Run directly with npx (recommended - no installation needed)
npx prvc init

# Or install globally (then use 'prvc' instead of 'npx prvc')
npm install -g provenancecode-cli
prvc init

See USAGE.md for detailed installation and usage instructions.

🚀 Quick Start

# Simple install (just the structure)
npx prvc install

# Configure your project
npx prvc config set --app-code=MYAPP --area=CORE

# Add Cursor IDE integration
npx prvc starterpack add cursor

# Start documenting
npx prvc journal add "Your first decision"

# OR use full init (with AI and CI)
npx prvc init --app-code=MYAPP --ai=cursor,claude --ci=github

📖 Core Commands

prvc install ⭐ NEW

Install ProvenanceCode structure in your project root (simplest way to get started).

npx prvc install

If provenance/ already exists, install now runs a safe in-place v1 → v2 migration/repair instead of failing.

Creates:

• provenance/ folder structure
• Schema files
• Config file
• Templates

prvc migrate

Migrate an existing v1 repository to v2 format and ensure required folders/files exist.

npx prvc migrate

prvc config ⭐ NEW

Configure ProvenanceCode settings.

# Set app code and area
npx prvc config set --app-code=MYAPP --area=BACKEND

# List current config
npx prvc config list

# Configure for monorepo
npx prvc config monorepo --roots="packages/frontend,packages/backend"

# Add/remove monorepo roots
npx prvc config monorepo --add-root="packages/new-service"
npx prvc config monorepo --remove-root="packages/old-service"

prvc starterpack ⭐ NEW

Install AI starter packs to proper IDE locations.

# Install Cursor rules (goes to .cursor/rules/)
npx prvc starterpack add cursor

# Install Claude Code rules (goes to .claude/)
npx prvc starterpack add claude

# Install Antigravity rules (goes to .antigravity/)
npx prvc starterpack add antigravity

What it does:

• Creates IDE-specific configuration files
• Tells your AI assistant how to create ProvenanceCode records
• Uses your project's app code and area settings
• Installs in the proper location for each IDE

📖 Commands

prvc init

Initialize ProvenanceCode G2 in your repository.

Options:

• --standard=g2 - Standard version (default: g2)
• --app-code=MYAPP - Application code for ID generation (default: MYAPP)
• --area=CORE - Default area for records (default: CORE)
• --ai=cursor,claude,antigravity - AI starter packs to install
• --ci=github - CI provider to configure
• --ci-mode=warn|fail - CI validation mode (default: warn)
• --force - Force reinitialize if already exists

Example:

npx prvc init \
  --app-code=MYAPP \
  --area=CORE \
  --ai=cursor,claude \
  --ci=github \
  --ci-mode=warn

Creates:

/provenance/
  /decisions/
    TEMPLATE.json
  /risks/
    TEMPLATE.json
  /schemas/
    decision.g2.schema.json
    risk.g2.schema.json
  /ai/
    /cursor/
    /claude/
    /antigravity/
  provenance.config.json
  README.md

prvc validate

Validate all ProvenanceCode records in the current repository.

Options:

• --mode=warn|fail - Validation mode (overrides config)

Example:

# Warn on errors but don't fail
npx prvc validate --mode=warn

# Fail on errors (useful for CI)
npx prvc validate --mode=fail

prvc starter

Manage AI starter packs.

Usage:

npx prvc starter add <tool>

Supported tools:

• cursor - Cursor IDE rules and prompts
• claude - Claude Code assistant guidelines
• antigravity - Antigravity integration guide

Example:

npx prvc starter add cursor

🆔 ID Scheme (G2)

Decision IDs

Format: DEC-{APP}-{AREA}-{000001}

Example: DEC-MYAPP-CORE-000001

Risk IDs

Format: RSK-{APP}-{AREA}-{000001}

Example: RSK-MYAPP-SECURITY-000003

The CLI auto-increments SEQ6 per area.

📝 Templates

Decision Template

{
  "schema": "https://provenancecode.org/schemas/decision.g2.schema.json",
  "decision_id": "",
  "title": "",
  "status": "draft",
  "context": "",
  "decision": "",
  "consequences": "",
  "risk": "",
  "links": []
}

Risk Template

{
  "schema": "https://provenancecode.org/schemas/risk.g2.schema.json",
  "risk_id": "",
  "title": "",
  "description": "",
  "severity": "medium",
  "status": "open",
  "linked_decisions": []
}

✅ Validation

The CLI validates:

• ✅ JSON syntax
• ✅ Schema compliance
• ✅ Required fields
• ✅ Enum values
• ✅ ID format
• ✅ Schema URL matches G2

The CLI does NOT enforce:

• ❌ Status transition rules
• ❌ Approval requirements
• ❌ Multi-party validation

Validation Modes

warn (default): Print errors but exit with code 0

npx prvc validate --mode=warn

fail: Exit with code 1 on errors (useful for CI)

npx prvc validate --mode=fail

🤖 AI Starter Packs

The CLI can install pre-configured AI assistant guides for:

Cursor

Creates rules and prompts for Cursor IDE:

• provenance/ai/cursor/rules.md - Cursor rules
• provenance/ai/cursor/prompts/create-decision.md
• provenance/ai/cursor/prompts/create-risk.md
• provenance/ai/cursor/prompts/pr-review.md

Claude Code

Creates guidelines for Claude Code assistant:

• provenance/ai/claude/README.md

Antigravity

Creates integration guide for Antigravity:

• provenance/ai/antigravity/GUIDE.md

All starter packs:

• ✅ Instruct AI to create G2-compliant records
• ✅ Default status to "draft"
• ✅ Encourage linking PRs and issues
• ❌ Never claim to approve or enforce governance

🔄 Optional GitHub CI

If you enable CI with --ci=github, the CLI creates:

.github/workflows/provenancecode.yml

Default behavior:

• Runs npx prvc validate
• Prints warnings
• Does NOT block merges unless you configure --ci-mode=fail

The CLI does not configure branch protection.

⚙️ Configuration

provenance.config.json

{
  "standard": "g2",
  "version": "2.0",
  "idScheme": "DEC-{APP}-{AREA}-{SEQ6}",
  "riskIdScheme": "RSK-{APP}-{AREA}-{SEQ6}",
  "defaultAppCode": "MYAPP",
  "defaultArea": "CORE",
  "paths": {
    "root": "provenance",
    "decisions": "provenance/decisions",
    "risks": "provenance/risks",
    "schemas": "provenance/schemas"
  },
  "validation": {
    "mode": "warn"
  }
}

🏗️ Architecture

Stack:

• Node.js
• TypeScript
• Commander (CLI framework)
• AJV (JSON schema validation)
• Chalk (terminal colors)

Constraints:

• ✅ No remote database
• ✅ No telemetry by default
• ✅ No SaaS calls
• ✅ < 1000 LOC target

🎯 Strategic Boundary

Open Layer (CLI)

The CLI handles:

• Record creation
• Schema compliance
• AI guidance
• Local validation

Paid Layer (GitHub App)

The GitHub App handles:

• Enforcement
• PR blocking
• Approval workflow
• Org dashboards
• Cross-repo analytics
• Escalation workflows
• Decision velocity metrics

The CLI must remain governance-free.

🔮 Future Extensions (Non-Governance)

Allowed future CLI additions:

• ✅ Mermaid diagram generation from decisions
• ✅ Markdown export
• ✅ Static decision index generation
• ✅ Decision graph visualization (local)

Not allowed:

• ❌ Centralized policy packs
• ❌ Enforcement presets
• ❌ Approval management
• ❌ Compliance mode

📚 Resources

• ProvenanceCode Website
• ProvenanceCode v2.0 Standard
• GitHub

📖 Documentation

• USAGE.md - Installation and usage guide (npx vs global vs development)
• QUICK_REFERENCE.md - Command cheat sheet
• FEATURES.md - Detailed feature documentation
• QUICKSTART.md - Get started in 5 minutes
• V2_COMPLIANCE.md - ProvenanceCode v2.0 standard compliance
• PROJECT_SUMMARY.md - Implementation overview
• CONTRIBUTING.md - Contribution guidelines
• CHANGELOG.md - Version history

📄 License

Apache-2.0

Built with ❤️ by the ProvenanceCode team

Quick Start: npx prvc install • Full Documentation • Commands