CLI Reference

The Vreko CLI (vreko, or vr for short) provides command-line access to protection features, workspace management, and automation capabilities.

The CLI is included with the VS Code extension. For standalone use, install via npm: npm install -g @vreko/cli

Note: You can use vr as a shorthand for vreko in all commands below. For example: vr init, vr status, vr check.

Quick Start

vreko init

Creates a .vreko/ directory with default configuration.

vreko status

Shows protection status, recent snapshots, and workspace health.

vreko watch

Starts continuous file watching for automatic snapshots.

Command Reference

Authentication Commands

# OAuth login flow
vreko login

# Clear credentials
vreko logout

# Show current user
vreko whoami

Login initiates the OAuth flow in your browser. Credentials are stored securely in your system keychain.

Workspace Management

# Initialize .vreko/ directory
vreko init

# Show workspace status
vreko status

# Fix common issues
vreko fix

# Run diagnostics
vreko doctor

# Interactive first-time setup
vreko wizard

Status shows:

Protection state (active/inactive)
Recent snapshot count
Storage usage
Any warnings or issues

Protection Commands

# Configure file protection
vreko protect

# Manage coding sessions
vreko session

# Continuous file watching
vreko watch

# Create a snapshot
vreko snapshot -m "Before refactoring"

# List snapshots
vreko snapshot list

Session management:

# Start a named session
vreko session start "Implement auth"

# End current session
vreko session end

# List all sessions
vreko session list

Intelligence Commands

These commands bring Vreko’s learning capabilities to the CLI.

# Get context before starting work
vreko context "add authentication" --keywords auth session

# Run validation pipeline
vreko validate src/auth.ts

# Validate all staged files
vreko validate --all

# Show learning statistics
vreko stats

Context returns:

Related patterns from your codebase
Recent violations to avoid
Risk assessment for the task

Utility Commands

# Manage configuration
vreko config list
vreko config get apiUrl
vreko config set apiUrl https://api.vreko.dev

# Create command aliases
vreko alias set st status
vreko alias list

# Undo last destructive operation
vreko undo

# Self-update CLI
vreko upgrade
vreko upgrade --check

Core Commands

`vreko analyze`

Analyze a file for AI-generated code risks.

vreko analyze src/auth.ts

Output includes:

Risk score (0-10)
Risk level (low/medium/high)
Detected signals (bulk changes, unusual patterns, etc.)

`vreko check`

Pre-commit hook to check for risky AI changes.

# Check staged files (default - quick mode)
vreko check

# Run build verification
vreko check --mode build

# Create snapshot if risky changes detected
vreko check --snapshot

# Suppress output unless issues found
vreko check --quiet

# Check all files (legacy mode)
vreko check --all

CLI Modes:

quick (default): Fast risk analysis of staged files
build: Run pnpm build verification

Additional validation modes (architecture, circular, docs, learnings, security, etc.) are available via the MCP check tool for AI assistants. See MCP Tools →

Add vreko check to your pre-commit hook to catch risky AI changes before committing.

`vreko interactive`

Launch interactive mode with guided workflow.

vreko interactive

Provides a menu-driven interface for:

Analyzing files
Creating snapshots
Listing snapshots

`vreko workspaces`

Manage workspaces for multi-project support.

# List all workspaces
vreko workspaces list

# Switch to a workspace
vreko workspaces use <workspace-id>

`vreko fix`

Automatically fix common configuration and setup issues.

vreko fix

Detects and resolves:

Missing .vreko/ directory
Invalid configuration
Service connectivity issues
Stale session state

`vreko sync` & `vreko metrics`

Collect signals and identify critical files.

# Sync workspace signals
vreko sync

# Show critical files by momentum score
vreko metrics

Metrics identifies files that:

Change frequently (high velocity)
Have recent AI-generated code
Are central to your architecture

`vreko service`

Manage the Vreko background service.

# Start service
vreko service start

# Check service status
vreko service status

# View service logs
vreko service logs

# Stop service
vreko service stop

# Install as system service
vreko service install

# Uninstall system service
vreko service uninstall

`vreko completion`

Generate shell completion scripts.

# Bash
vreko completion bash > ~/.local/share/bash-completion/completions/vreko

# Zsh
vreko completion zsh > "\${fpath[1]}/_vreko"

# Fish
vreko completion fish > ~/.config/fish/completions/vreko.fish

MCP Integration

Local MCP Server

Start the MCP server for AI assistant integration:

# Start MCP server (stdio transport)
vreko mcp --stdio

# Configure MCP tools
vreko tools

Claude Code Integration

Generate Claude Code integration files with a single command:

# Generate .mcp.json, .claude/agents/, and .claude/commands/
vreko claude-sync

# Overwrite existing files
vreko claude-sync --force

# Include channel server config (research preview)
vreko claude-sync --channel

What it creates:

.mcp.json - MCP server auto-discovery
.claude/agents/vreko-preflight.md - Intelligence-enriched preflight agent
.claude/agents/vreko-session.md - Session lifecycle agent
.claude/commands/vreko-check.md - /vreko-check slash command

If the Vreko service is running, claude-sync enriches generated files with your workspace’s fragile files and co-change patterns.

MCP Configuration

For Cursor, Claude Code, or other MCP-compatible tools:

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "vreko": {
      "command": "vreko",
      "args": ["mcp", "--stdio"],
      "type": "stdio"
    }
  }
}

Service Management

The Vreko service provides background services for CLI/extension communication.

# Start service in background
vreko service start --detach

# Check service status
vreko service status

# Stop service
vreko service stop

# Restart service
vreko service restart

# Test service connectivity
vreko service ping

Configuration

Configuration File

Create a .vrekorc in your project root:

{
  "autoDecisionEngine": {
    "enabled": true,
    "riskThreshold": 60,
    "notifyThreshold": 40
  },
  "snapshot": {
    "maxPerFile": 100,
    "retentionDays": 30
  },
  "exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/.next/**"
  ]
}

Environment Variables

# API key for authenticated features
export VREKO_API_KEY=your_api_key

# Custom storage path
export VREKO_STORAGE_PATH=/custom/path

# Log level (debug | info | warn | error)
export VREKO_LOG_LEVEL=info

# SSE transport server port
export VREKO_SSE_PORT=8765

# API URL for SSE auth validation
export VREKO_API_URL=https://api.vreko.dev

Git Integration

Pre-commit Hook

Add Vreko checking to your pre-commit workflow:

#!/bin/bash
# .git/hooks/pre-commit

# Check staged files for risky AI changes
vreko check

if [ $? -ne 0 ]; then
  echo "Vreko detected potential risks. Review before committing."
  echo "To bypass: git commit --no-verify"
  exit 1
fi

Learning System

Record learnings and manage patterns:

# Record a learning
vreko learn "Always validate user input before processing"

# List patterns
vreko patterns list

# Show learning stats
vreko stats

Troubleshooting

Common Issues

Command not found

Ensure the CLI is installed globally: npm install -g @vreko/cli

Authentication errors

Run vreko login to re-authenticate. Check network connectivity.

Debug Mode

Enable verbose logging for troubleshooting:

VREKO_LOG_LEVEL=debug vreko status

Getting Help

# Get help for any command
vreko --help
vreko status --help
vreko session --help

Quick Start Guide - Get started with Vreko
How It Works - Understand how Vreko learns
MCP Integration - AI assistant integration
CLI Troubleshooting - Common issues and fixes