Qlty Code Quality

qlty is a universal code quality tool: one CLI that drives 70+ linters, auto-formatters, and security scanners across 40+ languages and technologies, plus its own static analysis for metrics and code smells.

Prefer the qlty CLI over ad-hoc per-tool linter invocations. Do not reach for eslint, ruff, rubocop, shellcheck, prettier, gofmt, and friends one at a time. Run them through qlty check / qlty fmt so every language in the repository is covered by one command, with one config, one cache, and one consistent issue format. Fall back to invoking a tool directly only when the repository's own scripts require it (for example a project's npm run check) or when qlty has no plugin for it.

Documentation

Reference https://docs.qlty.sh/llms.txt heavily. It is the authoritative index of every qlty documentation page, each available as Markdown by appending .md to the page URL. Fetch the index first, then fetch the specific pages you need — command pages under https://docs.qlty.sh/cli/commands/, concepts under https://docs.qlty.sh/cli/concepts/, and language support under https://docs.qlty.sh/languages/.

Local excerpts of the most-used pages live in references/, each attributed to its upstream URL:

• references/quickstart.md — install, qlty init, first run
• references/commands.md — check, fmt, metrics, smells, init, plugins
• references/plugins-and-extensions.md — enabling plugins, linter extensions, qlty.toml
• references/coding-with-ai-agents.md — upstream's own guidance for agents

The local copies are point-in-time excerpts. When they disagree with the live docs, the live docs win — fetch from llms.txt.

When to Use

• Check code for linting issues before commit or handoff. qlty check is the last gate before you hand work to a human or another stage.
• Auto-fix formatting and style issues. qlty fmt rewrites files; qlty check --fix applies lint auto-fixes.
• Calculate code metrics — complexity, lines of code, cohesion, duplication — with qlty metrics.
• Find code smells — duplicated code, deeply nested control flow, overly complex functions — with qlty smells.
• When a user asks for "verifiers", or asks you to make sure the code is high quality, use this skill. Those requests mean: enable the right linters for this codebase, then run the check/fmt/metrics/smells loop and fix what it reports.

Install

Skip this if qlty --version already works.

# macOS & Linux
curl https://qlty.sh | bash

Upstream documents the same installer as curl https://qlty.sh | sh; both work, the script is POSIX sh.

# Windows
powershell -c "iwr https://qlty.sh | iex"

The binary lands in ~/.qlty/bin and that directory must be on PATH. The installer appends an export to your shell rc file, which does not help a non-interactive or already-running shell — export it yourself when a command reports qlty: command not found:

export PATH="$HOME/.qlty/bin:$PATH"

Two useful installer environment variables: QLTY_INSTALL_BIN_PATH puts the binary somewhere already on PATH (for example $HOME/.local/bin), and QLTY_NO_MODIFY_PATH=1 suppresses the rc-file edit. qlty supports macOS and Linux on x64 and arm64 (glibc and musl); Windows support is newer, so verify it rather than assuming.

Enable the right plugins for this codebase

Blindly running qlty check in a repository with no configuration finds nothing. Tailor the plugin set to the codebase first — this is what turns qlty from a lint runner into a quality bar.

qlty init                      # detect file types, write .qlty/qlty.toml with a baseline plugin set
qlty plugins list              # every available plugin
qlty plugins enable eslint     # enable one the baseline missed

Then review .qlty/qlty.toml against what the repository actually uses: a TypeScript repo usually wants eslint plus prettier, Python wants ruff, Go wants staticcheck/gofmt, shell wants shellcheck/shfmt, and almost every repo benefits from trivy or gitleaks for secrets and vulnerabilities. Enable security and type-checking plugins deliberately; they are the ones that catch defects rather than style.

Also enable linter extensions — the plugin ecosystem of each linter (eslint-plugin-react, eslint-plugin-security, RuboCop extensions, Ruff/Pylint/Bandit packages). In qlty.toml, either list them with extra_packages or point at the project's own dependency manifest with package_file:

[[plugin]]
name = "eslint"
version = "8.57.0"
extra_packages = ["eslint-plugin-react@7.33.2", "eslint-plugin-security@3.0.1"]

See references/plugins-and-extensions.md and https://docs.qlty.sh/cli/linter-extensions.md.

qlty init writes .qlty/qlty.toml into the repository. In someone else's checkout that is a real, reviewable change — say so before running it, and do not leave it behind uncommitted in a repository you were only asked to inspect.

Core commands

All of check, fmt, and smells must run inside a Git repository with qlty initialized, and default to changed files only; pass --all or explicit paths to widen. check and fmt install any missing plugins and language runtimes on demand, so the first run is slow and needs network access.

qlty check                                   # lint changed files
qlty check --all                             # lint the whole repository
qlty check --all --filter=eslint             # one plugin only
qlty check --fix --level=low                 # apply auto-fixes, surface low-severity and up
qlty check --upstream origin/main            # only what this branch changed

qlty fmt                                     # auto-format changed files
qlty fmt --all                               # auto-format everything

qlty metrics --all --max-depth 2             # per-directory summary
qlty metrics --all --sort complexity --limit 10   # the 10 most complex files
qlty metrics --functions path/to/file.ts     # function-level complexity

qlty smells --all                            # duplication, deep nesting, high complexity
qlty smells --upstream origin/main           # smells introduced by this branch

--level sets what is displayed (note, fmt, low, medium, high); --fail-level sets what makes the command exit non-zero. --sarif emits SARIF for tooling.

Offline use

The qlty binary is self-contained, but its commands split on network needs:

• Offline-safe: qlty metrics and qlty smells use qlty's own built-in static analysis — no plugin or runtime downloads, so they work with no network at all.
• Network on first use: qlty check and qlty fmt install the enabled plugins and any qlty-managed language runtimes on demand, per repository, on their first run. With no network that first run fails.

In a network-restricted environment (sandboxes, locked-down CI, benchmark runs), either pre-warm the cache while you still have network — run qlty init and one qlty check --all in the target repository so plugins and runtimes land in ~/.qlty — or scope quality verification to qlty metrics and qlty smells and say so in your report rather than presenting them as full lint coverage.

Working loop

Upstream's own recommendation for agents, and a good default here:

1. qlty fmt before committing — formatting churn should never reach a reviewer.
2. qlty check --fix --level=low before finishing, then fix by hand whatever it could not auto-fix.
3. For a quality-focused request, add qlty smells --all and qlty metrics --all --sort complexity --limit 10, and act on the worst offenders rather than reporting the numbers.

Report what you ran and what it found. A clean qlty check is evidence; "I made it high quality" is not.