lint

Lint

The universal linter. One CLI to lint any language — with AI-powered code review.

---

What is Lint?

Lint wraps multiple language-specific linters into a single CLI. Instead of configuring ESLint, Rubocop, Ruff, Biome, and Stylelint separately, run one command:

lint

It auto-detects your languages, resolves linter conflicts, and lints everything — JavaScript, TypeScript, Python, Ruby, CSS, and more.

Quick Start

npm i -g lint
cd /path/to/your/repo
lint init
lint

lint init scans your project, detects languages, suggests linters, installs missing ones, creates .lintrc.yaml, and sets up git hooks — all interactively.

Features

• Smart init — Auto-detects languages, frameworks, and package managers
• 10 linters — Biome, oxlint, ESLint, Prettier, Ruff, Pylint, RuboCop, Stylelint, Brakeman, erb-lint
• Conflict resolution — Biome auto-replaces ESLint+Prettier, Ruff replaces Pylint
• Lint anything — Staged files, directories, or specific files
• AI-powered — Code review, auto-fix, commit messages, error explanations (Claude)
• JSON output — --format json for CI/CD pipelines
• Structured run metadata — JSON output includes run mode, file count, selected linters, and policy metadata
• Parallel execution — Different-language linters run simultaneously
• Managed hooks — Portable hook install/uninstall/status with timeout, skip env, Husky/Lefthook compatibility
• Zero config — Works out of the box, customize with .lintrc.yaml
• Doctor mode — Inspect branch, dirty state, linters, config, and hook health
• Project-aware defaults — Defers to repo-local linter configs unless cloud policy rules override them

Supported Linters

Language	Linters	Speed
JavaScript / TypeScript	Biome, oxlint, ESLint	Biome/oxlint: ~100x faster
Python	Ruff, Pylint	Ruff: ~100x faster
Ruby	RuboCop	—
CSS / SCSS	Stylelint	—
ERB Templates	erb-lint	—
Ruby on Rails	Brakeman (security)	—
Code Formatting	Prettier	—

When Biome is installed, ESLint/Prettier/oxlint are automatically disabled (configurable in .lintrc.yaml).

By default, Lint now respects the target repository's own linter configuration. Temporary configs are only generated when cloud policy rules need to override local behavior.

Commands

Linting

lint                      # Lint staged files (default)
lint .                    # Lint entire project
lint src/                 # Lint specific directory
lint src/index.ts         # Lint specific file
lint --fix                # Auto-fix issues
lint --fix --dry-run      # Preview fixes without applying
lint --format json        # JSON output for CI/CD
lint ci                   # Repo-local quality gate (JSON + fail on warnings by default)
lint -q                   # Quiet mode (summary only)
lint -t                   # Show execution time
lint --exit-on-warnings   # Exit code 2 on warnings

AI (powered by Claude)

lint ai setup             # Configure your Anthropic API key
lint ai review            # AI code review of staged changes
lint ai fix               # AI-powered auto-fix suggestions
lint ai commit            # Generate commit message from staged diff
lint ai explain           # Explain linting errors in plain language

Setup & Diagnostics

lint init           # Smart setup wizard with auto-detection
lint bootstrap      # Non-interactive repo-local bootstrap
lint setup fix            # Apply recommended repo-local setup in one pass
lint config recommend     # Print a recommended .lintrc.yaml
lint doctor         # Diagnose setup, linters, hooks health
lint doctor --json  # Machine-readable health report
lint explain run .        # Explain file/linter/policy decisions without linting
lint machine summary .    # Compact machine-readable summary for automation
lint install missing .    # Install suggested linters that are not installed yet
lint ci --allow-warnings  # Quality gate but keep warnings non-blocking
lint hooks status         # Inspect managed hook status
lint hooks install        # Install git hooks
lint hooks uninstall      # Remove git hooks
lint format write ts      # Run Prettier on all `*.ts` files

Account

lint auth signup
lint auth login
lint auth logout
lint auth status

Aliases like lint auth whoami, lint signup, lint login, lint logout, and lint whoami still work for backward compatibility, but lint auth <action> is now the canonical API and lint auth status is the preferred status command.

Internal hook entrypoints like lint pre-commit, lint prepare-commit-msg, and lint post-commit remain available for installed git hooks, but they are intentionally hidden from the main CLI help because they are not part of the primary user-facing surface.

Configuration

.lintrc.yaml

linters:
  enabled: [biome, ruff, rubocop]
  disabled: [eslint, prettier, oxlint]

ignore:
  - node_modules/**
  - dist/**
  - "**/*.test.ts"

fix:
  enabled: true
  strategy: formatter-first  # or: parallel, sequential

hooks:
  timeout: 60               # seconds
  skip_env: LINT_SKIP   # LINT_SKIP=1 git commit ...

Without .lintrc.yaml, Lint uses smart defaults with automatic conflict resolution.

Git Hooks

lint hooks install
lint hooks status

• Installs pre-commit, prepare-commit-msg, and post-commit hooks
• Auto-detects Husky/Lefthook and integrates instead of replacing
• Includes portable timeout protection and skip mechanism
• Uses explicit managed-hook markers for safer inspection and uninstall
• Skip: LINT_SKIP=1 git commit ... or git commit --no-verify

Doctor

lint doctor
lint doctor --json

lint doctor gives a quick local health check for:

• git root, branch, and dirty/clean state
• .lint/config and .lintrc.yaml
• auth status
• project detection: languages, frameworks, package managers, hook managers
• installed, enabled, and effectively selected linters
• managed vs unmanaged git hooks

Legacy aliases like lint setup:fix, lint config:recommend, lint install:missing, lint machine:summary, lint install:hooks, lint uninstall:hooks, and lint hooks:status still work for backward compatibility, but the canonical API now prefers grouped commands like lint setup fix, lint config recommend, lint install missing, lint machine summary, and lint hooks <action>.

lint init, lint bootstrap, and lint doctor are top-level canonical commands (matching npm init, git init, etc.). The grouped forms lint setup init, lint setup bootstrap, and lint setup doctor are kept as hidden legacy aliases for backward compatibility.

lint prettify <extension> also still works as a compatibility alias, but the canonical formatting helper is now lint format write <extension>.

lint explain-run also still works as a compatibility alias, but the canonical explain helper is now lint explain run.

Use lint doctor --json when you want to consume the report from another tool, CI step, or control plane.

Explain Run

lint explain run .
lint explain run src/
lint explain run --json .

lint explain run shows:

• which linters were selected or skipped, and why
• which conflicts were auto-resolved
• which fix strategy would be used
• which files were ignored
• which files are covered or uncovered
• whether policy rules are local or cloud-backed, and how many are applicable
• recommended next steps when coverage or tooling is incomplete

Install Missing

lint install missing .
lint install missing src/
lint install missing --dry-run .

lint install missing uses project detection to find suggested linters that are still missing, shows why they were suggested, and can install them with the linter-specific install command.

Bootstrap

lint bootstrap
lint bootstrap --dry-run
lint bootstrap --json
lint bootstrap --install-missing --install-hooks

lint bootstrap is the non-interactive counterpart to lint init. It detects the project, writes a repo-local .lintrc.yaml, creates a local .lint/config when needed, and can optionally install missing linters and hooks.

Setup Fix

lint setup fix
lint setup fix --dry-run
lint setup fix --json
lint setup fix --no-install-missing --no-install-hooks

lint setup fix is the one-shot setup repair flow. It writes the recommended .lintrc.yaml, creates a local .lint/config when missing, and by default also installs missing suggested linters and managed hooks.

Recommended Config

lint config recommend
lint config recommend --json
lint config recommend --write

lint config recommend builds a recommended .lintrc.yaml from project detection and current defaults. It preserves existing custom sections like rules, output, hook overrides, and custom ignore patterns.

JSON Output

lint --format json now returns a stable machine-readable payload with:

• schema_version and kind fields for consumer-side compatibility checks
• summary counts
• per-linter and per-file offenses
• run metadata such as cwd, mode, requested paths, file count, selected linters, and policy rule count
• a message field for empty or skipped runs
• explicit status and exit_code fields for CI and orchestration consumers
• a decisions block with ignored files, linter selection reasons, and cloud-vs-local policy summary
• file coverage details showing which selected linters handled which files, plus why uncovered files were skipped

For automation consumers that only need a compact health/result snapshot, use:

lint machine summary .
lint machine summary --strict .

The compact summary also includes structured actions with ready-to-run commands like lint install missing ., lint setup fix --dry-run, or lint explain run ., so a control plane can guide remediation without parsing prose. It also exposes explicit signals booleans like needs_setup, has_missing_selected_linters, and has_uncovered_files for lightweight consumers. For even simpler consumers, it now includes a top-level status, stable blocking_reasons / warning_reasons, and a primary_action. Use --strict when a shell script should fail fast on setup gaps or uncovered files without parsing JSON.

CI / Quality Gate

lint ci
lint ci --format text
lint ci src/
lint ci --allow-warnings

lint ci is the repo-local quality gate mode:

• defaults to linting the whole project (.)
• defaults to JSON output for machine consumers
• fails on warnings by default with exit code 2
• can be relaxed with --allow-warnings

Development

git clone https://github.com/osmove/lint.git
cd lint
npm install
npm run verify            # Full maintainer check: typecheck, lint, audit, build, package, gate, tests
npm run build             # Build TypeScript → dist/
npm run package:check     # Verify the published npm package contents
npm run quality-gate      # Run Lint against the whole repo
npm run security:audit    # Fail on moderate+ dependency vulnerabilities
npm test                  # Run the Vitest suite
npm run typecheck         # Type check
npm run lint              # Lint with Biome

npm publish now reuses the same npm run verify gate through prepublishOnly, so local publishes cannot skip the full maintainer validation pass. npm run verify also checks the npm package payload with npm pack --dry-run.

See CONTRIBUTING.md for the maintainer workflow, CLI conventions, and release hygiene checklist.

Tech Stack

• TypeScript (strict), ESM
• Build: tsup → Node 20+
• Tests: Vitest
• CI: GitHub Actions (Node 20 + 22)
• AI: Anthropic SDK (Claude)

License

Apache-2.0

Website

https://lint.to