Documentation

Learn how to use VibeCodeXray to audit your codebase.

CLI Reference

Install

terminal

$ npm install -g vibecodexray

Or skip the install and use npx:

$ npx vibecodexray scan

Authenticate

terminal

$ vcx login

Paste your API key when prompted. Get one at Settings → API Keys.

Commands

vcx scan <repo> [options]

Start a new audit. If no repo is specified, auto-detects from the current git directory.

# Auto-detect from current git repo
$ vcx scan

# Scan a specific repo
$ vcx scan https://github.com/user/repo

# Shorthand
$ vcx scan user/repo

# Scan a specific branch and directory
$ vcx scan user/repo -b develop -d src

# Enable AI fix suggestions (slower, more detailed)
$ vcx scan --ai

# Submit without waiting for results
$ vcx scan --no-wait

vcx list

List your 10 most recent audits with scores and status.

vcx help

Show all commands and options.

Scan Options

Flag	Description
-b, --branch <name>	Branch to scan (default: current branch or main)
-d, --dir <path>	Root directory to scope the scan to a subfolder
--ai	Enable AI fix suggestions — plain-language explanations and suggested fixes for each finding
--no-wait	Submit the scan and exit without waiting for results

Environment Variables

Variable	Description
VCX_API_KEY	API key (alternative to `vcx login`)
VCX_API_URL	API base URL (default: https://vibecodexray.com)

Authentication

Get your API key

Go to Settings → API Keys to generate a key. Keys start with vcx_ and are shown only once — save it somewhere safe.

Using your key

terminal

# Interactive login (saves key to ~/.vcx/config.json)
$ vcx login

# Or use an environment variable
$ VCX_API_KEY=vcx_... vcx scan

CI/CD Integration

Add VCX to your CI pipeline to automatically scan every pull request. Catch security, performance, and quality issues before they reach production.

GitHub Actions

Add this workflow to .github/workflows/vcx.yml to run VCX on every pull request.

.github/workflows/vcx.yml

name: VCX Audit

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  audit:
    name: Code Audit
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Run VCX Audit
        env:
          VCX_API_KEY: ${{ secrets.VCX_API_KEY }}
        run: npx vibecodexray scan --no-wait

      - name: Check Audit Results
        env:
          VCX_API_KEY: ${{ secrets.VCX_API_KEY }}
        run: |
          # Wait for results and fail on critical findings
          npx vibecodexray scan --fail-on critical

Setup steps:

Go to Settings → API Keys and generate a CI key
In your GitHub repo, go to Settings → Secrets and variables → Actions
Add a new secret named VCX_API_KEY with your key
Commit the workflow file to your repo

Quality Gates

Use the --fail-on flag to block merges when findings exceed your threshold.

terminal

# Fail only on critical severity findings
$ npx vibecodexray scan --fail-on critical

# Fail on high and critical findings
$ npx vibecodexray scan --fail-on high

# Fail on any finding (strictest)
$ npx vibecodexray scan --fail-on low

Level	Blocks on	Use case
critical	Critical only	Production deploys
high	High + Critical	Recommended for PRs
medium	Medium + High + Critical	Strict teams
low	All findings	Zero-tolerance policy

GitLab CI

Add this to your .gitlab-ci.yml:

.gitlab-ci.yml

vcx-audit:
  stage: test
  image: node:20-alpine
  variables:
    VCX_API_KEY: $VCX_API_KEY
  script:
    - npx vibecodexray scan --fail-on high
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Add VCX_API_KEY in GitLab → Settings → CI/CD → Variables (masked + protected).

CircleCI

Add this job to your .circleci/config.yml:

.circleci/config.yml

version: 2.1

jobs:
  vcx-audit:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Run VCX Audit
          command: npx vibecodexray scan --fail-on high

workflows:
  pr-checks:
    jobs:
      - vcx-audit

Add VCX_API_KEY in CircleCI → Project Settings → Environment Variables.

Best Practices

When to run audits

Pull requests: Catch issues before merge. Use --fail-on high to block risky PRs.
Main branch pushes: Track overall project health over time.
Scheduled (nightly): Full deep scans for dependency CVE monitoring.

Performance tips

Use -d src to scope scans to your source directory if your repo is large.
Skip --ai in CI for faster results — deterministic rules are enough for gate checks.
Use --no-wait for non-blocking runs that report results asynchronously.

Handling failures

Start with --fail-on critical and tighten over time as your team addresses existing debt.
Review findings in the VCX dashboard for full details, evidence, and fix suggestions.
Use the audit export feature to attach findings to PR comments or Slack notifications.

Notifications

VCX results appear in your dashboard immediately after the scan completes.
Configure webhook notifications in Settings to send results to Slack or other tools.

Pre-commit Hook (Optional)

Run a quick scan before each commit for immediate feedback:

.husky/pre-commit

#!/bin/sh
npx vibecodexray scan --fail-on critical

This is optional — CI integration catches everything, but a pre-commit hook gives you instant feedback before pushing.