CLI Reference

The Vreko CLI (vr) is the primary command-line interface for initializing a workspace, controlling the Vreko service, and inspecting intelligence state.

Install the CLI globally:

npm install -g @vreko/cli

pnpm add -g @vreko/cli

yarn global add @vreko/cli

Quick Start

vr init

vr start

vr status

Commands

vr init

Initialize a workspace for Vreko observation.

vr init

What it does:

• Creates a .vreko/ directory with default configuration
• Scans the project structure (file count, detected stack)
• Seeds the knowledge base from the global template
• Writes an initial agents.workspace.json and wires your agent’s rules file

Run from the root of the project you want to observe. Each project root is a separate workspace with independent intelligence state.

vr start

Start the Vreko service.

vr start

The Vreko service runs in the background. It observes file events, classifies sessions, and updates agents.workspace.json on a debounced schedule. It also serves the local MCP endpoint that AI tools connect to.

vr stop

Stop the running service.

vr stop

Gracefully shuts the service down. Sessions in progress are flushed first.

vr status

Show the current service and intelligence state.

vr status

Output includes:

• service: running | stopped
• intelligenceState - the current observation state
• observationCount - sessions observed since init
• confidence - current model confidence score (0.0–1.0)

vr session

Inspect the sessions Vreko has observed.

# Show the current session
vr session

# List recent sessions
vr session list

A session is a window of related activity Vreko groups together to attribute changes and update intelligence.

vr snapshot

Work with workspace snapshots.

# List snapshots
vr snapshot list

# Show details for a snapshot
vr snapshot show <id>

vr service

Manage the background service directly.

vr service status
vr service logs

Most users never need this - vr start and vr stop cover the common cases. vr service is for inspecting the service process and reading its logs.

Configuration

.vrekorc

Create at your project root to configure workspace-level behavior:

{
  "exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/.next/**"
  ]
}

Environment variables

export VREKO_API_KEY=your_api_key       # API key for authenticated features
export VREKO_STORAGE_PATH=/custom/path   # Custom storage path
export VREKO_LOG_LEVEL=info              # debug | info | warn | error
export VREKO_API_URL=https://api.vreko.dev

Troubleshooting

npm install -g @vreko/cli
vr --version

Enable debug logging for any command:

VREKO_LOG_LEVEL=debug vr status

Get help for any command:

vr --help
vr <command> --help

See Troubleshooting for more issues.