vexboy

Analyze Convex function and schema usage across your codebase

vexboy is a CLI tool that tells you which Convex functions are actually used in your application, finds unused functions, and detects unused tables and fields in your schema — so you can keep your Convex codebase clean.

Installs the vexboy command (and a cint alias for backwards compatibility — both run the same tool).

Features

• Function Usage Analysis — detect which Convex functions are used / unused (public and internal)
• Schema Analysis — find unused tables and columns in your schema
• Reports — JSON and CSV output, plus timestamped report history
• Beautiful Console Output — colored, formatted output with usage statistics
• Smart Caching — fast subsequent runs with automatic cache invalidation
• Watch Mode — auto re-analyze on file changes
• Flexible Configuration — global and per-project config files, environment variables, and CLI flags
• Easy Setup — interactive (or one-shot) configuration wizard

Installation

Global Installation

npm install -g vexboy

Use with npx

npx vexboy

Local Development

npm install
npm run build
npm link

Quick Start

1. Navigate to your Convex project:

   cd your-convex-project

2. Run the analysis:

   vexboy

3. (Optional) Create a configuration file:

   vexboy init          # interactive wizard
   vexboy init --yes    # write defaults, no prompts

Commands

vexboy (or vexboy analyze)

Analyze Convex function usage. This is the default command.

vexboy                         # Analyze with defaults
vexboy --no-cache              # Force fresh analysis
vexboy --output report.json    # Save JSON report to a path
vexboy --csv                   # Also save a CSV report
vexboy --json                  # Output JSON to stdout
vexboy --watch                 # Watch for changes
vexboy --convex-dir ./api      # Point at a non-standard Convex directory
vexboy --search-dirs src,app   # Override the directories to search
vexboy --ignore seed,wipe      # Ignore specific functions
vexboy --dry-run               # Show configuration without running

vexboy schema

Analyze Convex schema usage — find unused tables and columns.

vexboy schema                       # Analyze schema
vexboy schema --json                # Output JSON to stdout
vexboy schema --output report.json  # Save to a path

It parses schema.ts to extract table and field definitions, scans your .ts files for usage, and reports unused tables and columns with statistics.

vexboy all

Run all analyses (functions + schema).

vexboy init

Create a configuration file.

vexboy init            # interactive wizard (global or local)
vexboy init --yes      # write ./vexboy.config.js with defaults
vexboy init --force    # overwrite an existing config

vexboy clean

Clear cache and old reports.

Configuration

vexboy supports global and per-project config files.

• Global: ~/.vexboy/config.js (applies to all projects)
• Local: ./vexboy.config.js (project-specific, overrides global)

Legacy cint.config.js / ~/.cint/config.js files are still read for backwards compatibility.

Example Configuration

/**
 * @type {import('vexboy').VexboyConfig}
 */
export default {
  // Functions to ignore. Names ('signIn'), full identifiers
  // ('auth.js:signIn'), or wildcards ('migrations/*') are all supported.
  ignore: ['isAuthenticated', 'signIn', 'signOut', 'seed', 'wipe'],

  // Directories to search for function usage
  searchPaths: ['./src', './app'],

  cache: {
    enabled: true,
    location: '~/.cache/vexboy',
  },

  reports: {
    location: '~/.vexboy/reports',
    maxSize: 100, // MB
  },

  output: {
    colors: true,
    verbose: true,
  },
};

TypeScript config

import type {VexboyConfig} from 'vexboy';

const config: VexboyConfig = {
  ignore: ['myFunction'],
  searchPaths: ['./src', './app'],
};

export default config;

Environment Variables

Handy for CI. Both VEXBOY_ and legacy CINT_ prefixes are supported.

VEXBOY_CONVEX_DIR=./api     # override Convex directory detection
VEXBOY_CACHE_DIR=/tmp/cache # override cache location
VEXBOY_NO_CACHE=true        # disable caching
VEXBOY_NO_COLOR=true        # disable colored output

Precedence (highest first): CLI flags → environment variables → config file → defaults.

CLI Options

Global options (work with any command):

• --no-cache, --fresh — disable cache, force fresh analysis
• -o, --output <path> — save JSON report to a specific path
• --convex-dir <path> — Convex directory location (auto-detected)
• --search-dirs <paths> — comma-separated directories to search
• --ignore <functions> — comma-separated functions to ignore
• --json — output JSON to stdout (for scripting)
• --csv — also save a CSV report
• --watch — watch for changes and re-run analysis
• -v, --verbose / -q, --quiet — output verbosity
• --debug — show stack traces
• --dry-run — show configuration without running
• --no-color — disable colored output
• -V, --version / -h, --help

How It Works

1. Detection — locates your Convex directory (./convex, ./src/convex, …) or the one you pass via --convex-dir
2. Spec Loading — fetches function specifications via convex function-spec (cached)
3. Search — uses ripgrep to find api.* and internal.* references (dot and bracket notation, multiline-aware)
4. Analysis — categorizes functions as used, unused, or ignored
5. Reporting — prints to console and saves JSON (and optionally CSV)

Output

CSV Reports

With --csv, a spreadsheet-friendly report is written alongside the JSON report:

Function,Module Path,Type,Visibility,Status,Usage Count,Locations
"listUsers","users","Query","public","Used",3,"src/app.ts:6; ..."

Requirements

• Node.js >= 18
• ripgrep (rg) — fast text search
• Convex CLI — for fetching function specs (auto-installed if missing)

Installing ripgrep

• macOS: brew install ripgrep
• Debian/Ubuntu: sudo apt-get install ripgrep
• Fedora: sudo dnf install ripgrep
• Windows: choco install ripgrep or scoop install ripgrep

Caching

vexboy caches Convex function specs to speed up subsequent runs. The cache is invalidated automatically when Convex files change (by mtime and content hash). Cache location: ~/.cache/vexboy/. Bypass with vexboy --no-cache.

CI/CD Integration

vexboy exits with code 0 (informational rather than a CI blocker). For scripting, use JSON output:

# Count unused functions
UNUSED=$(vexboy --json --quiet | jq '.summary.unused')

# Generate a report artifact
vexboy --output ./reports/convex-usage.json --csv --quiet

Development

npm install
npm run build     # tsup build
npm run dev       # watch build
npm test          # vitest
npm link          # link for local testing

Project Structure

source/
├── cli.tsx                # CLI entry point
├── index.ts               # Public type/config exports
├── commands/              # analyze, schema, all, init, clean, color-test
├── config/                # defaults, loader, paths, schema (zod)
├── core/                  # analyzer, function-finder, spec-loader,
│                          #   convex-detector, schema-parser, schema-analyzer,
│                          #   cache-manager
├── output/                # console, json-reporter, csv-reporter, schema output
├── utils/                 # dependencies, errors, file-hash, history
└── types/                 # TypeScript types

License

MIT