Skip to content

cli.md

Latest commit

 

History

History
122 lines (85 loc) · 4.55 KB

cli.md

File metadata and controls

122 lines (85 loc) · 4.55 KB
Raw

CLI

The konsistent CLI is the entry point for running checks, validating configs, and managing the tool itself.

Commands

Command Description
konsistent Shorthand for konsistent check
konsistent check Check structural conventions against your konsistent.json
konsistent validate Validate the konsistent.json configuration file
konsistent help Show a quick reference of all commands and options
konsistent version Print the version number
konsistent update Update konsistent to the latest version

konsistent invoked without a subcommand runs check. konsistent --help runs help. konsistent --version runs version.

check

Loads konsistent.json, runs every convention against the codebase, and reports violations.

konsistent check
konsistent check --config-package @acme/shared-conventions
konsistent check --format=json --max-diagnostics=1000
konsistent check --error-on-warnings --diagnostic-level error

Flags

Flag Type Default Description
--config-path <path> string konsistent.json (project root) Path to the config file
--config-package <pkg> string — NPM package name to load konsistent.json from. Resolved from the consuming project's node_modules. Mutually exclusive with --config-path
--format <format> default | json | github | markdown default (auto-detects github in CI) Output format
--verbose boolean false Show execution time and expanded details
--max-diagnostics <n> string (parsed as integer) 100 Maximum diagnostics to print before truncating
--colors / --no-colors boolean auto Force-enable or disable terminal colors (default format only)
--error-on-warnings boolean false Treat warnings as errors for the exit code
--diagnostic-level <level> warning | error warning Minimum severity to evaluate. error skips warning-severity conventions entirely
--placeholder <name:value> string (repeatable) — Inject a placeholder into every convention's placeholders map, overriding any entry already there. May be passed multiple times. See Static placeholder values

Exit codes

  • 0 — no errors (warnings allowed unless --error-on-warnings is set).
  • 1 — errors found, or config could not be loaded.

validate

Parses and validates konsistent.json against the schema without running any checks against the filesystem.

konsistent validate
konsistent validate --config-path=path/to/konsistent.json
konsistent validate --config-package @acme/shared-conventions

Exits 0 and prints Configuration is valid. on success. Exits 1 with a Zod validation error on failure.

validate accepts the same --config-path, --config-package, and --placeholder flags as check (see the table above).

Output formats

default

Colored terminal output. Files are grouped, diagnostics sorted by line.

packages/anthropic/src/index.ts
  -  error  Missing export type "AnthropicProvider"  [must-export-and-more]

packages/openai/src/index.ts
  -  error  Missing export "openai"  [must-export-and-more]
  -  error  Missing export type "OpenAIProviderSettings"  [must-export-and-more]

Checked 6 files in 10ms. Found 3 errors.

When everything passes:

Checked 6 files in 8ms. No violations found.

github

GitHub Actions annotations (::error file=...,line=...::message). Auto-selected when GITHUB_ACTIONS=true is set in the environment, so konsistent check in a GitHub workflow needs no extra flags.

json

Machine-readable JSON array. Each entry has the shape:

[
  {
    "severity": "error",
    "conventionName": "must-export-and-more",
    "filePath": "packages/openai/src/index.ts",
    "predicateName": "export",
    "message": "Missing export \"openai\"",
    "line": 1
  }
]

severity is "error" or "warning". line is omitted when the diagnostic isn't tied to a specific line (e.g., a missing-file diagnostic).

Use json when scripting around the CLI (CI gating, custom reports, or driving an agent).

markdown

Markdown table format suitable for posting as a PR comment.

Truncation

When the number of diagnostics exceeds --max-diagnostics, only the first n are printed and a truncation summary is appended:

… and 437 more diagnostics omitted. Increase --max-diagnostics to see all.

The exit code still reflects all violations — only the printed output is truncated.