GlanceVibe CLI

Security vulnerability scanner for JavaScript/TypeScript. Collects code patterns via AST analysis and sends them to the GlanceVibe Worker API for vulnerability detection.

Installation

npm install -g glancevibe

Updating CLI

# Both commands do the same thing
glancevibe update
glancevibe upgrade

Both commands run:

npm install -g glancevibe@latest

For safety, most commands are blocked unless you are on the latest CLI version. CLI checks latest version directly from the npm registry. If version verification cannot reach npm registry, commands fail closed.

Authentication

Before scanning, you need to authenticate with your API key:

glancevibe auth --login

You can also set the GLANCEVIBE_API_KEY environment variable.

Usage

Scan files

# Scan current directory
glancevibe scan

# Scan specific files or directories
glancevibe scan src/ lib/

# Scan with specific output format
glancevibe scan --format json
glancevibe scan --format sarif
glancevibe scan --format html

# Filter by severity
glancevibe scan --severity HIGH

# Filter by confidence
glancevibe scan --confidence high

# Exclude patterns
glancevibe scan --exclude "**/test/**" --exclude "**/*.spec.ts"

# Explicitly include dependency scan (2 credits total)
glancevibe scan --include-deps

# Explicitly skip dependency scan (1 credit total)
glancevibe scan --no-include-deps

Git-Aware Scanning

Scan only files that have changed, perfect for CI pipelines and pre-commit hooks:

# Scan uncommitted changes (staged + unstaged)
glancevibe scan --changed

# Scan only staged files (great for pre-commit hooks)
glancevibe scan --staged

# Scan files changed since a branch/tag/commit
glancevibe scan --since main
glancevibe scan --since HEAD~5
glancevibe scan --since v1.0.0

Baseline / Ignore Known Findings

Suppress known findings to focus on new issues:

# Generate a baseline from current findings
glancevibe scan --generate-baseline

# Apply baseline to suppress known findings
glancevibe scan --baseline

# Use a custom baseline file path
glancevibe scan --baseline ./custom-baseline.json
glancevibe scan --generate-baseline --baseline ./custom-baseline.json

The baseline file (.glancevibe-baseline.json) tracks findings by fingerprint, allowing for minor code changes without losing suppressions.

Dependency Scanning

Check your npm dependencies for known vulnerabilities:

# Standalone dependency scan
glancevibe deps

# Scan a specific directory
glancevibe deps ./my-project

# JSON output
glancevibe deps --format json

# Exclude devDependencies
glancevibe deps --no-dev

# Combined with code scan
glancevibe scan --include-deps

Credit behavior:

• glancevibe scan (code-only): consumes 1 credit
• glancevibe scan with dependency scan: consumes 2 credits total
• glancevibe deps: consumes 1 credit only when dependency scan succeeds

When you run glancevibe scan interactively, CLI asks whether to include dependency scanning. Use arrow keys and press Enter. Default selection is code-only.

In non-interactive environments (CI, pipes), prompt is skipped and scan defaults to code-only unless --include-deps is explicitly passed.

When --include-deps is enabled, dependency vulnerabilities are sent to the GlanceVibe API (GV-021) and included in the scan results. This runs even if no code files are found or changed. If the dependency scan fails, the CLI prints a warning and continues with code findings.

Scan History & Trends

Track your security posture over time:

# View scan history for current project
glancevibe history

# Limit number of entries
glancevibe history --limit 20

# View all projects with history
glancevibe history --all

# View security trends with ASCII visualization
glancevibe trends

# Analyze different time periods
glancevibe trends --days 7
glancevibe trends --days 90

# Export trend data as JSON
glancevibe trends --format json

Check account status

glancevibe status

List available rules

glancevibe list-rules

Explain a rule

glancevibe explain GV-001

Security & Integrity

GlanceVibe CLI includes built-in integrity verification to protect against tampering, MITM attacks, and supply chain attacks.

Self-Verification

On every run, the CLI verifies its own integrity by checking SHA256 checksums of critical files. If verification fails, the CLI will refuse to run and display:

SECURITY: CLI integrity check failed!
Your installation may be compromised.

To fix, reinstall: npm install -g glancevibe@latest

Request Signing

When GLANCEVIBE_SIGNING_SECRET is configured, all API requests are signed with HMAC-SHA256 to prevent modification in transit.

Skipping Integrity Checks (Development Only)

For development purposes, you can skip integrity checks:

GLANCEVIBE_SKIP_INTEGRITY=1 glancevibe scan
# or
NODE_ENV=development glancevibe scan

Configuration

Create a .glanceviberc file in your project root:

{
  "severity": "MEDIUM",
  "format": "pretty",
  "exclude": ["**/node_modules/**", "**/*.test.ts"],
  "apiUrl": "https://api.glancevibe.com"
}

Or add a glancevibe key in your package.json:

{
  "glancevibe": {
    "severity": "MEDIUM",
    "exclude": ["**/test/**"]
  }
}

You can also override the API endpoint via environment variable:

GLANCEVIBE_API_URL=https://api.glancevibe.com

Output Formats

• pretty (default): Colored terminal output with code snippets
• json: Full findings as JSON
• sarif: SARIF format for CI/CD integration (GitHub, GitLab)
• html: Interactive HTML report

Exit Codes

• 0: No critical or high severity findings
• 1: Critical or high severity findings detected, or scan error

CI/CD Integration

GitHub Actions

- name: Security Scan
  run: |
    npm install -g glancevibe
    glancevibe scan --format sarif > results.sarif
  env:
    GLANCEVIBE_API_KEY: ${{ secrets.GLANCEVIBE_API_KEY }}

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif

PR-Only Scanning

Scan only changed files in pull requests:

- name: Security Scan (Changed Files)
  run: |
    npm install -g glancevibe
    glancevibe scan --since origin/main
  env:
    GLANCEVIBE_API_KEY: ${{ secrets.GLANCEVIBE_API_KEY }}

With Baseline

Ignore known findings and fail only on new issues:

- name: Security Scan with Baseline
  run: |
    npm install -g glancevibe
    glancevibe scan --baseline
  env:
    GLANCEVIBE_API_KEY: ${{ secrets.GLANCEVIBE_API_KEY }}

Pre-commit Hook

Add to .husky/pre-commit:

#!/bin/sh
glancevibe scan --staged --severity HIGH

Commands Reference

| Command | Description | |---------|-------------| | update | Update CLI to the latest version | | upgrade | Alias for update | | scan [targets...] | Scan files for security vulnerabilities | | deps [target] | Scan dependencies for known vulnerabilities | | history | Show scan history for current project | | trends | Show security trend visualization | | auth | Manage API authentication | | status | Show account status and usage | | list-rules | List available security rules | | explain <rule> | Explain a security rule |

Scan Options

| Option | Description | |--------|-------------| | -f, --format <format> | Output format: pretty, json, sarif, html | | -o, --output <path> | Output file path | | -s, --severity <level> | Minimum severity: LOW, MEDIUM, HIGH, CRITICAL | | -c, --confidence <level> | Minimum confidence: low, medium, high | | -e, --exclude <patterns...> | Glob patterns to exclude | | -i, --include <patterns...> | Glob patterns to include | | --changed | Scan only uncommitted changes | | --staged | Scan only staged files | | --since <ref> | Scan files changed since ref | | --generate-baseline | Generate baseline file | | --baseline [path] | Apply baseline to suppress findings | | --include-deps | Include dependency vulnerability scan | | --no-include-deps | Skip dependency vulnerability scan | | -v, --verbose | Verbose output |

License

MIT