CLI Commands Reference

Complete reference for all VDK CLI commands, options, and usage patterns.

Command Overview

vdk [command] [options]

Available Commands

init - Initialize VDK and generate project blueprints
update - Update blueprints from VDK-Blueprints repository
status - Check VDK setup and integration status
validate - Validate generated rules and configurations
scan - Re-analyze project and update rules
integrations - Manage AI platform integrations

`vdk init`

Initialize VDK in your project by analyzing your codebase and generating AI assistant configurations using curated blueprints from the VDK-Blueprints repository.

vdk init [options]

Options

Option	Description	Default
`-p, --project-path <path>`	Path to project directory	`process.cwd()`
`-o, --output-path <path>`	Output directory for configurations	Platform-specific defaults
`--interactive`	Interactive setup with guided choices	`false`
`--categories <list>`	Specific blueprint categories to include	All relevant
`--preset <name>`	Use preset collection (minimal, full, development)	`auto`
`--deep`	Enable deep project analysis	`false`
`--watch`	Enable continuous monitoring	`false`
`-v, --verbose`	Detailed operation logging	`false`

Examples

# Basic initialization with auto-detection
vdk init

# Interactive mode with guided setup
vdk init --interactive

# Deep analysis with verbose output
vdk init --deep --verbose

# Specific categories and preset
vdk init --categories core,languages,technologies --preset development

# Watch mode for continuous updates
vdk init --watch

# Analyze specific project path
vdk init --project-path /path/to/project

Output

🔍 Analyzing project at: /Users/dev/my-project
📁 Project structure analysis...
🔧 Technology Detection:
   - Languages: TypeScript, JavaScript
   - Framework: Next.js 15 (App Router)
   - Styling: Tailwind CSS 4
   - Database: Supabase
   - Tools: ESLint, Prettier

📋 Blueprint Matching:
   - Core: 4 blueprints
   - Technologies: 8 blueprints  
   - Languages: 2 blueprints
   - Total: 23 blueprints selected

🤖 Platform Integration:
   ✅ Claude Code (.claude/)
   ✅ Cursor (.cursor/rules/)
   ⚠️  Windsurf (not detected)
   ⚠️  GitHub Copilot (not detected)

📝 Generated configurations deployed
✅ VDK setup complete

`vdk update`

Synchronize local blueprints with the latest from VDK-Blueprints repository and refresh AI platform configurations.

vdk update [options]

Options

Option	Description	Default
`--force`	Force update even if local changes exist	`false`
`-v, --verbose`	Show detailed update information	`false`

Examples

# Update blueprints and refresh configurations
vdk update

# Force update with detailed output
vdk update --force --verbose

Output

📡 Fetching latest blueprints from repository...
🔍 Comparing with local cache...
📋 Found updates:
   - 3 new blueprints available
   - 2 existing blueprints updated
   - 1 blueprint deprecated

🤖 Refreshing AI platform configurations...
✅ Update complete!
   - Blueprint cache: Updated
   - AI platforms: 2 refreshed

`vdk status`

Check the status of your VDK setup and AI platform integrations.

vdk status [options]

Options

Option	Description	Default
`--check-integrations`	Verify AI platform integration status	`false`
`-v, --verbose`	Show detailed status information	`false`

Examples

# Check basic status
vdk status

# Check with integration verification
vdk status --check-integrations

# Detailed status report
vdk status --verbose

Output

🔍 VDK Status Check...

✅ Configuration: vdk.config.json valid
   - Project: my-nextjs-app
   - Version: 2.0.1
   - Blueprint Cache: 109 blueprints

🤖 AI Platform Integrations:
   ✅ Claude Code (high confidence)
      📁 .claude/ directory with 12 files
   ✅ Cursor (medium confidence)
      📁 .cursor/rules/ with 15 .mdc files
   ⚠️  Windsurf (not detected)
   ⚠️  GitHub Copilot (not detected)

📊 Blueprint Repository Status:
   - Remote: 109 blueprints available
   - Local cache: Up to date
   - Last sync: 2 hours ago

`vdk validate`

Validate generated configurations and verify blueprint compliance.

vdk validate [options]

Options

Option	Description	Default
`--schema-version <version>`	Blueprint schema version to validate against	`2.1.0`
`--platforms <list>`	Specific platforms to validate	All detected
`-v, --verbose`	Show detailed validation results	`false`

Examples

# Validate all configurations
vdk validate

# Validate specific platforms
vdk validate --platforms claude-code,cursor

# Verbose validation output
vdk validate --verbose

Output

🔍 Validating VDK configurations...

✅ Schema Validation (v2.1.0):
   - All blueprints: Valid
   - YAML frontmatter: Valid
   - Content structure: Valid

🤖 Platform Configuration:
   ✅ Claude Code: 12 files validated
   ✅ Cursor: 15 .mdc files validated  
   ⚠️  2 warnings found (non-critical)

📋 Validation Summary:
   - Total files: 27
   - Errors: 0
   - Warnings: 2
   - Schema compliance: 100%

`vdk scan`

Re-analyze project and update blueprint configurations without full reinitialization.

vdk scan [options]

Options

Option	Description	Default
`--incremental`	Only update changed files	`false`
`--dry-run`	Show what would be updated	`false`
`-v, --verbose`	Show detailed scan information	`false`

Examples

# Full project re-scan
vdk scan

# Incremental scan (faster)
vdk scan --incremental

# Preview scan changes
vdk scan --dry-run

Output

🔄 Re-analyzing project...

📁 Changes detected:
   + 2 new dependencies (react-hook-form, zod)
   ~ 1 technology updated (Next.js 15 → 15)
   - 1 tool removed (Webpack → Vite)

📋 Blueprint updates:
   + 3 new blueprints applicable
   ~ 2 existing blueprints updated
   - 1 blueprint no longer relevant

🤖 Refreshing AI platform configurations...
✅ Scan complete - configurations updated

`vdk integrations`

Detect and manage AI platform integrations with confidence scoring.

vdk integrations [options]

Options

Option	Description	Default
`-p, --project-path <path>`	Project directory path	`process.cwd()`
`--scan`	Scan for active AI platforms	`false`
`--setup <platform>`	Setup specific AI platform	-
`--list`	List all available platforms	`false`
`--confidence-threshold <level>`	Minimum confidence level (low/medium/high)	`low`

AI Platform Options for `--setup`

claude-code - Claude Code (.claude/ directory)
cursor - Cursor AI (.cursor/rules/ directory)
windsurf - Windsurf (.windsurf/rules/ directory)
github-copilot - GitHub Copilot (.github/copilot/ directory)

Examples

# List all available integrations
vdk integrations --list

# Scan for active IDEs
vdk integrations --scan

# Setup Cursor integration
vdk integrations --setup cursor

# Setup Windsurf integration
vdk integrations --setup windsurf

# Setup GitHub Copilot integration
vdk integrations --setup github-copilot

Output for `--list`

📋 Available IDE Integrations:

• Claude Code
  Status: high confidence
  Format: Markdown memory files
  Path: CLAUDE.md + .claude/

• Cursor AI
  Status: medium confidence
  Format: MDC (YAML + Markdown)
  Path: .cursor/rules/

• Windsurf
  Status: low confidence
  Format: Markdown with XML tags
  Path: .windsurf/rules/

• GitHub Copilot
  Status: low confidence
  Format: JSON guidelines
  Path: .github/copilot/

Output for `--scan`

🔍 Scanning for IDE integrations...

✅ Detected IDE Integrations:
   • Claude Code (high)
     Format: Markdown memory files, Path: CLAUDE.md + .claude/
   • Cursor AI (medium)
     Format: MDC (YAML + Markdown), Path: .cursor/rules/

💤 Available IDEs (not detected):
   • Windsurf
   • GitHub Copilot

Global Options

These options work with all commands:

Option	Description
`--version`	Show version number
`--help`	Show help information

Environment Variables

Control VDK behavior with environment variables:

# GitHub token for blueprint repository access
export VDK_GITHUB_TOKEN=ghp_your_token_here

# Enable debug mode for detailed logging
export VDK_DEBUG=true

# Custom blueprint repository
export VDK_BLUEPRINTS_REPO=your-org/your-blueprints

# Disable telemetry
export VDK_TELEMETRY=false

# Blueprint cache directory
export VDK_CACHE_DIR=~/.vdk/cache

Exit Codes

VDK CLI uses standard exit codes:

0 - Success
1 - General error
2 - Configuration error
3 - Network error
4 - File system error

Examples by Use Case

Initial Project Setup

# Complete project setup workflow
vdk init --interactive
vdk status --check-integrations
vdk validate

Blueprint Management

# Update to latest blueprints
vdk update --verbose

# Re-analyze after major changes
vdk scan --incremental

Continuous Development

# Enable watch mode for active development
vdk init --watch

# Quick project rescan
vdk scan --incremental

Debugging and Troubleshooting

# Debug mode with verbose output
VDK_DEBUG=true vdk init --verbose

# Check all platform statuses
vdk integrations --scan --confidence-threshold medium
vdk status --verbose
vdk validate --verbose

For more detailed information about specific features, see:

CLI Commands

On this page