CLI Reference

All VGuard CLI commands.

Running Commands

VGuard is typically installed as a local devDependency. Use npx to run commands:

npx vguard <command>

During vguard init, convenience scripts can be added to your package.json:

{
  "scripts": {
    "vguard": "vguard",
    "vguard:lint": "vguard lint",
    "vguard:doctor": "vguard doctor",
    "vguard:sync": "vguard sync"
  }
}

Then run: npm run vguard:lint

For global access without npx:

npm install -g @solanticai/vguard
vguard lint

Commands

`vguard init`

Interactive setup wizard. Detects framework, configures presets and agents, optionally connects to VGuard Cloud.

`vguard add <id>`

Add a rule or preset: vguard add security/branch-protection or vguard add preset:react-19.

`vguard remove <id>`

Remove a rule or preset: vguard remove preset:tailwind.

`vguard generate`

Regenerate all hook scripts and agent configs from current config.

`vguard doctor`

Validate config and hook health. Reports issues with config, missing hooks, broken rules.

`vguard lint`

Static analysis mode. Scans project files and reports violations.

vguard lint                         # Text output
vguard lint --format json           # JSON output
vguard lint --format github-actions # GitHub annotations

Exits with code 1 if blocking violations found (CI-friendly).

`vguard fix`

Auto-fix issues that have machine-applicable fixes.

vguard fix             # Apply all available fixes
vguard fix --dry-run   # Show fixes without applying

`vguard learn`

Scan codebase for conventions. Discovers import patterns, naming conventions, directory structure.

`vguard report`

Generate quality dashboard from rule hit data. Outputs markdown to .vguard/reports/.

`vguard eject`

Export standalone hooks that work without VGuard installed. Removes dependency requirement.

`vguard upgrade`

Check for and apply updates to VGuard and installed plugins.

vguard upgrade --check  # Check only
vguard upgrade          # Apply updates

`vguard sync`

Upload rule-hits data to VGuard Cloud. Reads .vguard/data/rule-hits.jsonl, filters records newer than the sync cursor, and uploads in batches.

vguard sync             # Sync new records since last sync
vguard sync --force     # Re-upload all data (ignores cursor)
vguard sync --dry-run   # Show what would be uploaded without sending

Requires a Cloud connection (vguard cloud connect) or VGUARD_API_KEY environment variable.

Note: When autoSync is enabled in your config, syncing happens automatically during development. Use vguard sync for manual uploads or to force a full re-sync.

Cloud Commands

Cloud commands manage the connection between your local project and VGuard Cloud.

`vguard cloud login`

Authenticate with VGuard Cloud. Opens your browser for OAuth 2.1 PKCE login by default.

vguard cloud login                          # Interactive browser login
vguard cloud login --token <jwt>            # Manual token login (CI/headless)
vguard cloud login --no-interactive         # Print login URL only

Flags:

--token <token> — Use an access token directly (skip browser)
--refresh-token <token> — Supabase refresh token (with --token)
--url <url> — Cloud API URL override
--supabase-url <url> — Supabase project URL override
--supabase-anon-key <key> — Supabase anon key override
--no-interactive — Print the login URL instead of opening the browser

Credentials are stored at ~/.vguard/credentials.json.

`vguard cloud logout`

Remove stored Cloud credentials.

vguard cloud logout

`vguard cloud connect`

Register the current repository with VGuard Cloud. Creates a Cloud project, generates an API key, and updates your vguard.config.ts with Cloud settings.

vguard cloud connect                        # Auto-detect project name
vguard cloud connect --name my-app          # Specify project name
vguard cloud connect --key vc_xxx --project-id <uuid>  # Use existing API key

Flags:

--name <name> — Project name (defaults to directory name)
--key <key> — Use an existing project API key (skip project creation)
--project-id <id> — Project ID (required with --key)

After connecting, your config is updated with:

cloud: { enabled: true, projectId: '...', autoSync: true }

The API key is saved to .env.local as VGUARD_API_KEY.

`vguard cloud status`

Show current Cloud connection status, including auth state, project ID, and last sync time.

vguard cloud status

See also: Cloud Integration Guide for a complete walkthrough of setting up VGuard Cloud.