CLI reference

VectorLint runs from the command line. This page is the complete reference for every command, flag, output format, and exit code.

Basic usage

The default command reviews one or more files and prints findings to standard output. You must pass at least one path; without one, VectorLint prints help.

vectorlint [flags] <file> [files...]

Review a single file:

vectorlint doc.md

Review multiple files or a glob pattern:

vectorlint content/docs/**/*.md

Commands

`vectorlint <paths>`

The default command. Reviews the given files against the rules that apply to them and prints findings. Accepts the flags below.

`vectorlint init`

Generates configuration files for a project. The flags control which files are created; a global config is always ensured.

Flag	Effect
(none)	Creates `.vectorlint.ini` (project) and ensures `~/.vectorlint/config.toml` (global)
`--quick`	Zero-config mode: creates only `VECTORLINT.md`. No `.vectorlint.ini`
`--full`	Creates both `.vectorlint.ini` and `VECTORLINT.md`, and ensures the global config
`--force`	Overwrite configuration files that already exist

vectorlint init          # project config + global config
vectorlint init --quick  # VECTORLINT.md only (zero-config)
vectorlint init --full   # project config + VECTORLINT.md + global config

If a target file already exists, init exits with an error unless you pass --force.

`vectorlint validate`

Validates rule and prompt files without running evaluations. Checks YAML frontmatter structure, schema compliance, and prompt completeness, then prints a per-file report and a summary line.

vectorlint validate

By default, validate uses RulesPath from your project configuration. Override the rules directory:

vectorlint validate --rules .github/rules

Exits with code 1 if any validation errors are found; 0 otherwise. Use this to catch malformed rules before they reach a review.

`vectorlint --help` and `vectorlint --version`

vectorlint --help     # list commands and flags
vectorlint --version  # print the installed version

Flags

The default command (vectorlint <paths>) accepts these flags:

Flag	Description
`-v`, `--verbose`	Enable verbose logging. Prints what VectorLint loads (directive, user instructions, rule packs) and extra detail during the review
`--show-prompt`	Print the full prompt and injected content that is sent to the LLM
`--show-prompt-trunc`	Print truncated prompt and content previews (first 500 characters). Useful for a quick check without the full payload
`--debug-json`	Write a debug JSON artifact per evaluation under `.vectorlint/runs/` (see below)
`--output <format>`	Output format. One of `line` (default), `json`, `vale-json`, `rdjson`. See Output formats
`--config <path>`	Path to a custom `.vectorlint.ini` instead of the one in the project root

`--debug-json` artifacts

With --debug-json, VectorLint writes one JSON artifact per evaluation to .vectorlint/runs/<model-tag>/<run-id>.json. Each artifact contains:

raw_model_output: exact JSON the model returned, including all evidence fields
filter_decisions: the deterministic surface/hide decision for each candidate, with reasons
surfaced_violations: the candidates that passed all confidence checks

Use these to compare how different models respond to the same rules and content, or to tune CONFIDENCE_THRESHOLD. The .vectorlint/runs/ directory is gitignored.

Output formats

Control the output shape with --output <format>. The default line format is for humans; the others are for tooling and CI integration.

`line` (default)

Human-readable terminal output. Each finding shows the rule, its location in the file, the violation, and a suggested fix. The run ends with a global summary and token usage. Findings are colored by severity.

`json`

Native VectorLint JSON. Use this when you process VectorLint output yourself. The top-level object is:

{
  "files": {
    "doc.md": {
      "issues": [
        {
          "line": 12,
          "column": 1,
          "severity": "error",
          "message": "Passive voice weakens the opening.",
          "rule": "Acme.PassiveVoice",
          "suggestion": "Rewrite in active voice."
        }
      ],
      "evaluationScores": []
    }
  },
  "summary": { "files": 1, "errors": 1, "warnings": 0 },
  "metadata": { "version": "2.5.0", "timestamp": "2026-03-04T15:14:49Z" }
}

Each issue includes message (the user-facing summary) and, when the model produced it, analysis (internal model reasoning). evaluationScores carries the per-rule score breakdown.

`vale-json`

Compatible with tools that consume Vale’s JSON output. The shape is:

{
  "files": { "doc.md": [ /* ValeIssue[] */ ] },
  "summary": { "files": 1, "errors": 1, "warnings": 0, "suggestions": 0 }
}

Use this to plug VectorLint into an existing Vale-based pipeline.

`rdjson`

reviewdog-compatible JSON (also used by GitHub Actions annotations). The shape is:

{
  "source": { "name": "vectorlint", "url": "..." },
  "diagnostics": [
    {
      "message": "Passive voice weakens the opening.",
      "location": { "path": "doc.md", "range": { "start": { "line": 12 } } },
      "severity": "ERROR",
      "code": { "value": "Acme.PassiveVoice" },
      "suggestions": []
    }
  ]
}

Use this when running VectorLint in reviewdog or a reviewdog-compatible CI setup.

Exit codes

The default command exits non-zero only when a finding surfaces at error severity, not for warning-severity findings. This lets warnings pass through CI while errors block a merge.

Code	Meaning
`0`	No `error`-severity findings. (`warning` findings may still be present)
`1`	One or more `error`-severity findings, or an operational error (for example, a provider request failure or invalid configuration)

A check rule surfaces at error severity when its density score is 1.0 or below, and at warning severity otherwise. A rule may also set severity: error in its frontmatter to force the error level. See CI Integration for gating examples.

Environment variables

VectorLint reads configuration from environment variables in addition to config files. Project-level .env values take precedence over the global config.toml.

Variable	Default	Description
`LLM_PROVIDER`	(none)	LLM provider to use: `openai`, `anthropic`, `azure-openai`, `gemini`, `amazon-bedrock`
`OPENAI_API_KEY`	(none)	API key for OpenAI
`ANTHROPIC_API_KEY`	(none)	API key for Anthropic
`GEMINI_API_KEY`	(none)	API key for Google Gemini
`AZURE_OPENAI_API_KEY`	(none)	API key for Azure OpenAI
`SEARCH_PROVIDER`	(none)	Search provider for the `technical-accuracy` evaluator: `perplexity`
`PERPLEXITY_API_KEY`	(none)	API key for Perplexity search
`CONFIDENCE_THRESHOLD`	`0.75`	Confidence gate. Lower surfaces more findings; higher surfaces fewer.

For the full environment variable reference, including Azure OpenAI and Amazon Bedrock variables, see Environment variables.

Installation: install VectorLint globally or run with npx
Configuration: configure VectorLint for your project
Handling false positives: adjust CONFIDENCE_THRESHOLD and strictness
CI Integration: use exit codes and output formats to gate merges

Overview

Get started

Configuration

Rules

Scoring

Guides

Reference

Basic usage

Commands

`vectorlint <paths>`

`vectorlint init`

`vectorlint validate`

`vectorlint --help` and `vectorlint --version`

Flags

`--debug-json` artifacts

Output formats

`line` (default)

`json`

`vale-json`

`rdjson`

Exit codes

Environment variables

​Basic usage

​Commands

​vectorlint <paths>

​vectorlint init

​vectorlint validate

​vectorlint --help and vectorlint --version

​Flags

​--debug-json artifacts

​Output formats

​line (default)

​json

​vale-json

​rdjson

​Exit codes

​Environment variables

​Related

Basic usage

Commands

`vectorlint <paths>`

`vectorlint init`

`vectorlint validate`

`vectorlint --help` and `vectorlint --version`

Flags

`--debug-json` artifacts

Output formats

`line` (default)

`json`

`vale-json`

`rdjson`

Exit codes

Environment variables

Related