CLI reference

poly lint [PATHS]...
poly fmt  [PATHS]...

Shared flags

Both poly lint and poly fmt accept every flag below unless the description says otherwise.

Writing changes

Flag	Effect
--fix	Apply lint fixes or formatting in place.
--check	poly fmt only. Explicit dry run — this is the default.

Generated files

Flag	Effect
--fix-generated	Also rewrite files whose header stamps a content hash over the body (<project>:hash:<digest>).
--skip-generated	Do not lint or format machine-generated files at all (banner or stamp). Overrides [discovery] generated for this run. Conflicts with --include-generated.
--include-generated	Lint and format machine-generated files. The default, so it only matters in a repo that set [discovery] generated = false. Conflicts with --skip-generated.

Hash-stamped files are the only generated files poly withholds a write from — poly fmt skips them and poly lint --fix reports without rewriting — because reformatting invalidates the hash and the generator’s verify step then reports drift on a file nobody edited. A plain DO NOT EDIT or @generated banner does not hold poly back: those files are linted, formatted and fixed like any other, so --fix-generated has no effect on them.

Under --skip-generated the files are reported as skipped, so they count against --deny-skips and --max-skips.

Discovery

Flag	Effect
--config <PATH>	Use an explicit config file. Bypasses nested config resolution.
--exclude <GLOB>	Exclude paths from discovery. Repeatable; merged with [discovery] exclude. An unanchored glob matches at any depth — lead with / to anchor it to the config directory.
--force-exclude	Apply [discovery] exclude to explicitly named files too. The default, so it only matters in a repo that set [discovery] force_exclude = false.
--include-excluded	Check explicitly named files or directory roots even when excluded. Overrides [discovery] force_exclude. Exclusions below an included directory remain active.

Selecting engines

Flag	Effect
--only <ENGINE>	Run only the named engines. Repeatable and comma-separated (--only ruff,typos). Conflicts with --skip.
--skip <ENGINE>	Run every routed engine except the named ones.

Engines are named by the id you configure them under — ruff, oxc, typos, rumdl, quality, astgrep. poly config show lists the ones your config touches.

Three things worth knowing before you reach for it:

• It narrows, it never widens. An engine your config leaves off stays off when you name it. --only uncomment on a repo without [lint.uncomment] enabled = true selects nothing rather than switching the backend on, so the flag can never become a second, invisible way to enable a tool.
• Engine ids are unique per language, not globally. --only biome selects every engine answering to that name — the CSS one and the GraphQL one both.
• A name no engine answers to fails the run with exit 2 and a list of what is recognized. A typo’d --only ruffs would otherwise empty every plan, check nothing, and exit 0.

Naming engines also skips the whole-project phase, which is built from tools (cargo clippy, cargo-deny) rather than engines; poly lint prints a note saying so. That is usually the point — running one cheap engine without paying for a cargo build is half of what the flag is for.

Files left with no selected engine are reported as skipped with their own reason, and are not charged to --deny-skips / --max-skips:

skipped main.rs: no engine selected by --only/--skip for this file

To turn an engine off for every run rather than one invocation, use enabled in poly.toml instead.

The whole-project phase (poly lint only)

Flag	Effect
--workspace	Run the whole-project phase even though explicit paths were given (a path-scoped run normally skips it). Conflicts with --no-workspace.
--no-workspace	Skip the whole-project phase — cargo clippy / sort / machete / deny and any other configured whole-workspace tools. Equivalent to [lint] workspace = false.

The phase is never path-scoped: under --workspace the tools cover the whole repository regardless of the named paths and of [discovery] exclude, and the run says so on stderr.

`--no-workspace` is what makes a run read-only

Without it, plain poly lint executes those tools against the live worktree, and their own side effects are not poly’s to control.

Output

Flag	Effect
--format <pretty|json|toon>	Output format. Default: pretty.
--no-color	Disable colored output.
-q, --quiet	Trim pretty output to the findings and the summary. Conflicts with --verbose and --debug.
--verbose	Pretty output includes descriptions, URLs and metadata, and names every skipped file rather than the first 3 per skip reason. Conflicts with --quiet.
--debug	Include cache hit/miss and timing data. Implies --verbose. Conflicts with --quiet.

The levels are a ladder — quiet < normal < verbose < debug — each a superset of the one below. --quiet drops the per-file discovery and skip detail printed beneath the findings; every count and reason stays in the summary, so nothing is hidden, only un-itemised. Findings still print and exit codes are unchanged. It has no effect on --format json / toon.

The json / toon document

poly lint and poly fmt emit one object, not a bare array of per-file records:

{
  "results": [{ "path": "src/main.py", "diagnostics": [], "config": 0 }],
  "errors": [],
  "skipped": [{ "path": "main.zig", "reason": "no lint rules for Zig" }],
  "summary": { "checked": 1, "skipped": 1, "errored": 0 },
  "configs": [{ "hash": "1/9f2c4a1b7e3d05f8" }]
}

Gate on summary.checked, not on an empty results. A run that skipped every file reports no diagnostics and is not an error, so without the summary it is indistinguishable from a clean pass.

The three counts are not a partition of results, and cannot be derived from it:

• a file that was checked and found clean produces no record at all — results holds only files with something to report;
• a file whose language poly has no lint rules for can be both a skip and a result, because the cross-cutting backends (typos, ast-grep, the quality tier) still run over it.

errors and skipped repeat what the corresponding records already carry, deliberately: the defect they exist to close is a consumer reading a clean-looking list and concluding the files are fine.

configs is the fingerprint of every configuration that governed the run — root, the nearest governing poly.toml directory relative to the run root (omitted entirely at the root, and under --config, which bypasses the cascade), and hash, a version-framed blake3 digest of the fully merged table. Each result’s config field indexes into configs (omitted when 0), so two clean reports are only comparable when their configs entries match: a poly.toml, a poly.local.toml, a nested config or an extends base can move underneath an otherwise-identical run.

The MCP server returns this same document, so both surfaces answer the coverage question identically.

Changed in 0.24.0

This was previously a bare JSON array. A consumer that read the top level as a list should read results instead.

Coverage gates

Flag	Effect
--deny-skips	Exit 2 if any charged file was skipped (see below). Equivalent to --max-skips 0.
--max-skips <N>	Exit 2 if more than N charged files were skipped.

Execution

Flag	Effect
--no-cache	Bypass the result cache.
-j, --jobs <N>	Parallel jobs. Default: logical cores.

Skips and coverage

Skipped files — a language poly has no lint rules for, no matching engine, a generated file, a binary file, an engine every backend disabled by config, or an engine --only/--skip deselected — are always counted and their reasons summarized, so a run that checked nothing cannot look like a clean pass.

Only some of those reasons count against --deny-skips / --max-skips: a reason that names a limit of poly is charged, a reason that names an instruction the caller gave (--only/--skip, enabled = false) is not. See Coverage and withdrawal for the full split.

poly lint reports a file whose language nothing in the run lints as:

skipped main.zig: no lint rules for Zig

and keeps it out of the linted count. This covers the tier-2 languages the code-quality tier cannot model — Zig, Swift, Dart, Gleam, Elixir, Nix, Scala, Lua, R — and any language whose linter is opt-in or missing from PATH; a shell script with no shellcheck installed is reported rather than counted.

Note

A skip is coverage information, not a failure. The run still exits 0 unless you ask for --deny-skips / --max-skips. Cross-cutting checks — typos, ast-grep rules, comment removal — still run on these files, and their findings are still reported.

A file a directory walk could not identify as any language is counted separately — N file(s) of unrecognized type not checked, with the first few named — rather than itemised as a skip, since every repository is full of images, lock files and snapshots no linter was ever going to read. A path you name on the command line is different: naming it is a request to check it, so it is reported as a skip.

Exit codes

Code	Meaning
0	Clean: no lint findings, no formatting drift, or all writes succeeded.
1	Error-severity lint findings remain, a whole-project tool failed, or (for poly fmt) files would change. Warning-severity findings alone never trigger this — typos and the quality tier don’t redden CI.
2	The run verified less than it claims: a file an engine failed on, a formatter that did not converge within its pass cap, a skip budget exceeded (--deny-skips / --max-skips), a config or pipeline error, or a machine-readable report that failed to serialize.

Changed in 0.24.0: non-convergence is now an error

poly fmt runs each formatter to a fixed point, capped at five passes. A file still changing after five passes is now a per-file error, exiting 2. Previously it was silent success, with every following poly fmt --check reporting drift on that file forever — this is the one change in this release that turns a previously-green file red.

Read the exit code, not just the payload

A --format json / toon consumer must check the exit code: the whole-project phase’s own pass/fail is written to stderr, not the stdout document, so that stdout stays a single valid document.

poly doctor — which poly am I actually running?

poly doctor                  # human report; exits 1 when something is actively wrong
poly doctor --format json    # the same report, for a bug report or a CI check

Run this before filing a bug. It prints the resolved path of the running executable with its version and build identifier, every poly on PATH in order with the version each one reports, the config files in effect, and the cache directory — then exits non-zero on a real defect: a competing install on PATH, a poly that cannot report its own version, or a config that fails to load. Each finding carries the concrete remedy, including the fact that a cargo-installed ~/.cargo/bin/poly needs rm, not cargo uninstall poly.

poly --version reports the build identifier too:

$ poly --version
0.23.1 (release build v0.23.1, release)

versus 0.23.1 (dev build v0.23.1-8-g18aa5e8, debug) — so a development build carrying unreleased changes cannot be quoted as a release. The identifier comes from git describe at build time; outside a git checkout it reads unknown rather than guessing, and packagers can set POLY_BUILD_ID.

When another poly on PATH differs from the running one, every command warns once on stderr and points at poly doctor. A correctly-installed poly finds a single entry and prints nothing; POLY_NO_SHADOW_WARN=1 silences it regardless.

poly config — what did poly actually parse?

poly config show   [--config <PATH>] [--format <toml|json|toon>]
poly config update [--config <PATH>]

poly config show prints the effective, fully-merged configuration — every section and key poly resolved after extends bases, the nested poly.toml cascade and poly.local.toml have all been applied:

/repo/poly.toml

# poly effective configuration
#
# merged from: /repo/poly.toml
#              /repo/poly.local.toml
# extends:     path ../baseline/poly.toml
# hooks:       present

[defaults]
line_length = 120
...

[lint.python.ruff]
mccabe_max_complexity = 3

The default output is a valid TOML document, so diff against your own poly.toml shows exactly what poly kept — including keys poly does not recognize, which are printed as written rather than dropped. [defaults], [discovery], [rules] and [workspace] are shown fully resolved, so a setting nobody wrote (line_length = 120) is still visible; every other section is shown exactly as merged.

--format json / --format toon emit the same document as { "config": …, "resolution": … }, where resolution carries the config path, the files that were merged, the resolved extends bases, and whether [hooks] is present — the facts the TOML form carries as comments.

Note

The merged from list is file-level attribution: it names the files that could have contributed a value, not which file each key came from.

poly config update resolves symbolic extends git refs to pinned object IDs and writes poly-config.lock. Config validation reports unknown top-level sections, unknown keys within a recognized section, and wrongly-typed values as warnings — a misspelled key no longer parses silently and does nothing.

poly commit, poly hooks, poly cache, poly mcp

poly commit --message "feat: add backend"   # or a path: poly commit .git/COMMIT_EDITMSG
poly hooks install
poly cache stats
poly cache size
poly cache gc
poly cache clean
poly mcp --config /path/to/poly.toml

See Git hooks for the full [hooks] surface, and Agents and MCP for the MCP tool reference. In short: the MCP server is stdio-only; lint, format_check, cache_stats, rules, config_show and version are read-only; lint_fix, format_write and cache_clean are mutating; workspace_lint and workspace_lint_fix run the whole-project phase as async Tasks — the call returns a task handle and the client polls tasks/get, while a client without the tasks capability gets a synchronous result instead.

poly migrate

poly migrate               # dry-run: report what would move into poly.toml
poly migrate --write       # absorb tool configs into poly.toml, remove redundant files

poly migrate folds settings from ruff, taplo, markdownlint and typos config files — and from pyproject.toml’s [tool.ruff] / [tool.typos] / [tool.codespell] — into poly.toml, then deletes or strips only the sources poly can fully honor. Files it delegates to (rustfmt.toml, .golangci.yml, clippy.toml, …) and anything not fully representable are kept.

Flag	Effect
--report	Say explicitly that this is a dry run. This is the default behaviour.
--write	Apply the migration.
--recurse	Walk nested projects.
--verify	Re-run lint and format after writing.
--strip-superseded	Additionally strip pyproject.toml [tool.*] sections for the Python tools ruff supersedes — black, isort, flake8, …
--allow-dirty	Let it write into a repository with uncommitted changes.

It takes an optional path, defaulting to the current directory.

poly rules — custom rules

poly rules test [DIR]...          # verify rules against their *-test.yml snippets
poly rules list [DIR]...          # list every resolved rule (built-in pack + user rules)
poly rules list --format json     # same rows as JSON (also: --format toon)

poly rules list prints one row per rule — id, language, builtin or user, the severity it reports at under the current config, and the rule’s own declared default (off for an opt-in rule) — so a warning you did not recognise can be traced to the rule that raised it, and turned off. --format json / --format toon carry the same fields.

With no DIR, both read [rules] dirs from the nearest poly.toml. poly rules test exits non-zero on any failed snippet: a valid snippet that matched, an invalid one that didn’t, a fixed: autofix that differed, or a test naming an unknown rule id.