Tool catalog

The catalog tier is poly’s breadth mechanism. Opt in per tool with [tools.<name>] enabled = true; each command is probed on PATH and skipped with a warning when absent, so listing one never makes a run fail.

[tools.prettier]
enabled = true
files = "**/*.{js,ts}"

Findings from a catalog tool are file-level: a lint failure maps to one diagnostic with no span and no rule code. Where fidelity matters, prefer the native backends — poly runs those first and a catalog tool alongside them, not instead of them.

A tool whose lint command rewrites files (sqruff fix, rubocop --autocorrect, pyupgrade) is not run by poly lint; enabling one for linting logs a warning naming the command it refused, while poly fmt still runs it as a formatter.

Tools with a recipe

Fifteen tools carry a recipe (crates/poly-catalog/data/overlay.json): how poly runs them beyond one spawn per file with an exit-code verdict. They are what a repository’s lefthook or pre-commit gate typically runs, and poly migrate maps those jobs onto them.

Tool	Role	Unit of work	Report
`checkstyle`	lint	all files, one JVM per shard	XML (rule, line, column)
`palantir-java-format`	format	all files, in place on a scratch copy	–
`buildifier`	format, lint, fix	all files	JSON (category, URL, fixable)
`buf`	format, lint	one run per `buf.yaml` module	JSON lines
`actionlint`	lint	all workflow files	JSON
`gau`	lint	all workflow files and `action.yml` manifests	JSON (kind)
`hadolint`	lint	all Dockerfiles	JSON
`golangci-lint`	format, lint	one run per `go.mod`, over the packages of the files	JSON
`helm`, `helm-template`	lint	one run per `Chart.yaml` chart	text
`tflint`	lint	one run per directory	JSON
`tofu`, `terraform`	format	all files	–
`pyproject-fmt`	format	`pyproject.toml` only	–
`npm-groovy-lint`	format, lint	all files	JSON

[tools.checkstyle]
enabled = true
extra_args = ["-c", "checkstyle.xml", "-p", "checkstyle.properties"]
version = "12.3.1"   # "latest" (the default) or any upstream version
install = "auto"     # download it when it is missing

[tools.actionlint]
enabled = true
extra_args = ["-ignore", "SC2129", "-ignore", "SC2016"]

[tools.gau]
enabled = true       # flag uses: refs that are not a bare @vN major tag

[tools.buildifier]
enabled = true
format_extra_args = ["-lint=fix"]
extra_args = ["--warnings=-native-build"]

How they differ from the breadth tier above:

Batched. The run’s files go to the tool in one invocation, sharded to stay under the command-line limit and spread across cores. When the tool rejects one file, only that file is reported as failed; the rest keep their results.
Units. helm runs once per chart, golangci-lint once per Go module, buf once per module, however many of their files changed. Independent units run in parallel. Findings the tool reports in a file that is not part of the run (a values.yaml change that breaks a template) are shown once, on the first file of the unit.
Reports. Findings carry file, line, column, rule and URL, and are cached per file. A tool that judges a file in context (buf, golangci-lint) is cached against a digest of that context, so editing a neighbouring file invalidates the verdict.
actionlint severities. actionlint has none, so poly assigns one per finding kind (from 0.31.1): runner-label is a warning, since label validity depends on runners poly cannot see — declare self-hosted labels under self-hosted-runner.labels in .github/actionlint.yaml; shellcheck takes the level shellcheck printed (error, warning, info, style as hint); every other kind is an error. Override one kind with [engines.actionlint.rules.<kind>] level = "error".
gau (action pins). gau --lint-pins from gh-actions-updater 0.4.0 or later flags every remote uses: ref that is not a bare major tag (@vN): a commit SHA (sha), a full version tag (full_tag), or a branch or other ref (branch_or_other), each on its line with the kind as the rule. It runs offline over .github/workflows/*.y*ml and action.y*ml, reads .gh-actions-updater.toml ([update] allow_full permits a full tag for an action with no major tag), and honours # gau: ignore on a uses: line. A file it cannot parse is reported as scan_failure. It is off until [tools.gau] enabled = true; no release is pinned yet, so install it yourself or point bin at it.
Fixes. buildifier’s auto-fixable warnings are applied by poly lint --fix; the tool’s own rewrite is attached as the fix. golangci-lint findings that carry a suggested fix are fixed by golangci-lint run --fix on a scratch copy of the Go module, and only the run’s files are read back, so your tree is untouched until poly writes the result.
Takes over its language. An enabled formatter with a recipe replaces the language’s built-in formatter (tofu for HCL, golangci-lint for Go): the project’s gate runs that tool, so its opinions win. pyproject-fmt is confined to pyproject.toml and the TOML formatter leaves those files to it. If the tool is missing, its files are reported as skipped rather than formatted by something else.
Provisioning. bin names an executable. With install = "auto" poly downloads the tool once into its cache and verifies the SHA-256 (of the archive, for a tool shipped in a .tar.gz / .zip, before extracting only the binary). version is "latest" (the default) or any exact upstream version, such as "2.14.1"; poly does not need to know it in advance. Downloads are available for checkstyle, palantir-java-format, buildifier, buf, actionlint, hadolint, golangci-lint, helm, helm-template, tflint and tofu, on macOS and Linux (arm64 and x86_64; checkstyle is a platform-independent jar). A version poly cannot provision makes the tool unavailable with a message naming the cause — poly never runs a different version from PATH. Without install = "auto" a missing tool produces a warning naming the command that installs it.
Releases and poly.lock. latest is the newest upstream release, from the GitHub releases API (set GITHUB_TOKEN to avoid the anonymous rate limit) or, for get.helm.sh and Maven Central, the host’s own listing. The digest comes from the publisher: the API’s per-asset digest, or its checksum file. poly lock writes the resolved version and every platform’s URL and SHA-256 into poly.lock; poly lock --upgrade moves to the newest release and poly lock --check reports drift. With a lock entry a run does no lookup at all, and a re-published asset with a different digest is refused. Without one, a resolved latest is cached for resolve_ttl (default 24h, 0 always revalidates), revalidated with If-None-Match, and kept if a refresh fails. Fetches retry transient failures (connection errors, timeouts, 429, 5xx) with backoff and honour Retry-After (seconds or an HTTP date, up to 30 s). If version is not set and latest cannot be looked up, poly warns once and uses the newest release the catalog bundles, else the tool on PATH; an explicit version never falls back. With --offline / POLY_OFFLINE only the lock, the cache and installed binaries are used; a tool with none is reported as skipped.
helm. prepare runs helm dependency build once per chart (skipped when charts/ already satisfies Chart.lock, or when POLY_OFFLINE is set), retried prepare_attempts (5) times with a doubling prepare_backoff_secs (4) plus up to prepare_jitter_secs (4) of jitter. values_files and chart_values pass values files; skip_charts names library charts. A skipped chart is still run once, and the run fails if the tool now passes on it, so the list cannot outlive its reason (verify_skip_charts = false turns that off). .tpl files and NOTES.txt under templates/ are helm’s inputs and no other engine’s.
golangci-lint. new_from_rev reports only findings introduced since a git revision, and goos = ["linux", "darwin"] runs once per target OS and merges the findings.

Palantir’s pipeline as armis runs it (AOSP layout, then Palantir import fixing) is the named command aosp: [tools.palantir-java-format] command = "aosp".

Formatters with a recipe that cover a whole language displace the built-in one, so disable nothing by hand; to keep the built-in, leave the tool disabled.

Embedded tool catalog (348 tools across 175 languages)

Opt in per tool with [tools.<name>] enabled = true. Each command is probed on PATH and skipped when absent, so listing one never makes a run fail.

Tool	Type	Languages
action-validator	linter	yaml
actionlint	linter	yaml
air	formatter	r
alejandra	formatter	nix
alex	spell-check	markdown
ameba	linter	crystal
ansible-lint	linter	ansible
api-linter	linter	protobuf
asmfmt	formatter	go
astyle	formatter	c, c#, c++, java, objective-c
atlas	formatter	hcl
auto-optional	formatter	python
autocorrect	spell-check
autoflake	linter	python
autopep8	formatter	python
bashate	linter	bash
beancount-black	formatter	beancount
beautysh	formatter	bash, shell
bibtex-tidy	formatter	bibtex
bicep	formatter	bicep
biome	formatter, linter	javascript, json, typescript, vue
black	formatter	python
blade-formatter	formatter	blade, laravel, php
blue	formatter	python
bpfmt	formatter	blueprint
brighterscript-formatter	formatter	brighterscript, brightscript
brittany	formatter	haskell
brunette	formatter	python
bslint	linter	brightscript, brightscripter
buf	formatter	protobuf
buildifier	formatter	bazel
c3fmt	formatter	c3
cabal	formatter	cabal
cabal-fmt	formatter	cabal
cabal-gild	formatter	cabal, haskell
cabal-prettify	formatter	cabal
caddy	formatter	caddy
caramel	formatter	caramel
cedar	formatter	cedar
cfn-lint	linter	cloudformation, json, yaml
checkmake	linter	makefile
clang-format	formatter	c, c#, c++, java, javascript, json, objective-c, protobuf
clang-tidy	linter	c++
clj-kondo	linter	clojure, clojurescript
cljfmt	formatter	clojure
cljstyle	formatter	clojure
cmake-format	formatter	cmake
cmake-lint	linter	cmake
codeql	formatter	codeql
codespell	spell-check
coffeelint	linter	coffeescript
cppcheck	linter	c, c++
cpplint	linter	c++
crlfmt	formatter	go
crystal	formatter	crystal
csharpier	formatter	c#
css-beautify	formatter	css
csscomb	formatter	css
csslint	linter	css
cue	formatter	cue
cueimports	formatter	cue
curlylint	linter	django, html, jinja, liquid, nunjucks, twig
d2	formatter	d2
dart	formatter, linter	dart, flutter
dcm	formatter, linter	dart, flutter
deadnix	linter	nix
deno	formatter, linter	javascript, json, typescript
dfmt	formatter	d
dhall	formatter	dhall
djade	formatter	django, python
djangofmt	formatter	django, html, python
djlint	formatter, linter	handlebars, html, jinja, mustache, nunjucks, twig
docformatter	formatter	python
dockerfmt	formatter	docker
dockfmt	formatter	docker
docstrfmt	formatter	python, restructuredtext, sphinx
doctoc	formatter	markdown
dotenv-linter	linter	env
dprint	formatter
dscanner	linter	d
dune	formatter	dune, ocaml, reasonml
duster	formatter, linter	php
dx	formatter	rsx, rust
easy-coding-standard	formatter, linter	php
efmt	formatter	erlang
elm-format	formatter	elm
eradicate	linter	python
erb-formatter	formatter	erb, ruby
erg	linter	erg
erlfmt	formatter	erlang
eslint	linter	javascript, typescript
fantomas	formatter	f#
fish_indent	formatter	fish
fixjson	formatter, linter	json, json5
floskell	formatter	haskell
flynt	formatter	python
fnlfmt	formatter	fennel
forge	formatter	solidity
fortitude	linter	fortran
fortran-linter	formatter, linter	fortran
fourmolu	formatter	haskell
fprettify	formatter	fortran
futhark	formatter	futhark
fvm	formatter, linter	dart, flutter
gci	formatter	go
gdformat	formatter	gdscript
gdlint	linter	gdscript
gersemi	formatter	cmake
ghokin	formatter	behat, cucumber, gherkin
gleam	formatter	gleam
gluon	formatter	gluon
gofmt	formatter	go
gofumpt	formatter	go
goimports	formatter	go
goimports-reviser	formatter	go
golangci-lint	formatter, linter	go
golines	formatter	go
google-java-format	formatter	java
gospel	spell-check	go
grafbase	linter	graphql
grain	formatter	grain
hadolint	linter	dockerfile
haml-lint	linter	haml
hclfmt	formatter	hcl
hfmt	formatter	haskell
hindent	formatter	haskell
hledger-fmt	formatter	hledger
hlint	linter	haskell
hongdown	formatter	markdown
html-beautify	formatter	html
htmlbeautifier	formatter	erb, html, ruby
htmlhint	linter	html
hurlfmt	formatter	hurl
imba	formatter	imba
inko	formatter	inko
isort	formatter	python
janet-format	formatter	janet
joker	formatter, linter	clojure
jq	formatter	json
jqfmt	formatter	jq
js-beautify	formatter	javascript
json5format	formatter	json, json5
json_repair	linter	json
jsona	formatter, linter	jsona
jsonlint	formatter, linter	json
jsonnet-lint	linter	jsonnet
jsonnetfmt	formatter	jsonnet
jsonpp	formatter	json
juliaformatter_jl	formatter	julia
just	formatter	just
kcl	formatter	kcl
kdlfmt	formatter	kdl
kdoc-formatter	formatter	kotlin
keep-sorted	formatter
ktfmt	formatter	kotlin
ktlint	linter	kotlin
kube-linter	linter	kubernetes, yaml
kulala-fmt	formatter	http
leptosfmt	formatter	rust
liquidsoap-prettier	formatter	liquidsoap
luacheck	linter	lua
luaformatter	formatter	lua
luau-analyze	linter	luau
mado	linter	markdown
mago	formatter, linter	php
markdownfmt	formatter	markdown
markdownlint	linter	markdown
markdownlint-cli2	linter	markdown
markuplint	linter	html
mbake	formatter, linter	make
md-padding	formatter	markdown
mdformat	formatter	markdwon
mdsf	formatter	markdown
mdslw	formatter	markdown
meson	formatter	meson
mh_lint	linter	matlab
mh_style	linter	matlab
mise	tool
misspell	spell-check
mix	formatter	elixir
mojo	formatter	mojo
muon	formatter, linter	meson
mypy	linter	python
nasmfmt	formatter	assembly
nginxbeautifier	formatter	nginx
nginxfmt	formatter	nginx
nickel	formatter	nickel
nimpretty	formatter	nim
nixfmt	formatter	nix
nixpkgs-fmt	formatter	nix
nomad	formatter	hcl
nph	formatter	nim
npm-groovy-lint	formatter, linter	groovy
nufmt	formatter	nushell
ocamlformat	formatter	ocaml
ocp-indent	formatter	ocaml
odinfmt	formatter	odin
oelint-adv	linter	bitbake
opa	formatter	rego
openapi-format	formatter	json, openapi, yaml
ormolu	formatter	haskell
oxfmt	formatter	javascript, typescript
oxlint	linter	javascript, typescript
packer	formatter	hcl
panache	formatter	markdown, pandoc, quarto, rmarkdown
pasfmt	formatter	delphi, pascal
perflint	linter	python
perltidy	formatter	perl
pg_format	formatter	sql
php-cs-fixer	formatter, linter	php
phpcbf	formatter	php
phpinsights	linter	php
pint	formatter, linter	php
pkl	formatter	pkl
prettier	formatter	angular, css, ember, graphql, handlebars, html, javascript, json, less, markdown, scss, typescript, vue
prettierd	formatter	angular, css, ember, graphql, handlebars, html, javascript, json, less, markdown, scss, typescript, vue
pretty-php	formatter	php
prettypst	formatter	typst
prisma	formatter	prisma
proselint	spell-check
protolint	linter	protobuf
ptop	formatter	pascal
pug-lint	linter	pug
puppet-lint	linter	puppet
purs-tidy	formatter	purescript
purty	formatter	purescript
pycln	formatter	python
pycodestyle	linter	python
pydoclint	linter	python
pydocstringformatter	formatter	python
pydocstyle	linter	python
pyflakes	linter	python
pyink	formatter	python
pylint	linter	python
pymarkdownlnt	formatter, linter	markdown
pyment	formatter	python
pyrefly	linter	python
pyupgrade	linter	python
qmlfmt	formatter	qml
qmlformat	formatter	qml
qmllint	linter	qml
quick-lint-js	linter	javascript
raco	formatter	racket
reek	linter	ruby
refmt	formatter	reason
reformat-gherkin	formatter	gherkin
refurb	linter	python
regal	linter	rego
reorder-python-imports	formatter	python
rescript	formatter	rescript
revive	linter	go
roc	formatter	roc
rstfmt	formatter	restructuredtext
rubocop	formatter, linter	ruby
rubyfmt	formatter	ruby
ruff	formatter, linter	python
rufo	formatter	ruby
rumdl	formatter, linter	markdown
rune	formatter	rune
runic	formatter	julia
rustfmt	formatter	rust
rustywind	formatter	html
salt-lint	linter	salt
scala	formatter	scala
scalafmt	formatter	scala
scalariform	formatter	scala
selene	linter	lua
semistandard	formatter, linter	javascript
shellcheck	linter	bash, shell
shellharden	linter	bash, shell
shfmt	formatter	shell
sleek	formatter	sql
slim-lint	linter	slim
smlfmt	formatter	standard-ml
snakefmt	formatter	snakemake
solhint	linter	solidity
sphinx-lint	linter	python, restructredtext
sql-formatter	formatter	sql
sqlfluff	formatter, linter	sql
sqlfmt	formatter	sql
sqlint	linter	sql
sqruff	formatter, linter	sql
squawk	linter	postgresql, sql
standardjs	formatter, linter	javascript
standardrb	formatter, linter	ruby
statix	linter	nix
stylefmt	formatter	css, scss
stylelint	linter	css, scss
stylish-haskell	formatter	haskell
stylua	formatter	lua
superhtml	formatter	html
svlint	linter	systemverilog
swift-format	formatter	swift
swiftformat	formatter	swift
swiftlint	linter	swift
taplo	formatter	toml
tclfmt	linter	tcl
tclint	linter	tcl
templ	formatter	go, templ
terraform	formatter	terraform
terragrunt	formatter	hcl
tex-fmt	formatter	latex
textlint	spell-check
tlint	linter	php
tofu	formatter	terraform, tofu
tombi	formatter, linter	toml
toml-sort	formatter	toml
topiary	formatter
tryceratops	linter	python
ts-standard	formatter, linter	typescript
tsp	formatter	typespec
tsqllint	linter	sql
twig-cs-fixer	formatter, linter	twig
twigcs	linter	php, twig
txtpbfmt	formatter	protobuf
ty	linter	python
typos	spell-check
typstfmt	formatter	typst
typstyle	formatter	typst
ufmt	formatter	python
uiua	formatter	uiua
unimport	formatter	python
usort	formatter	python
v	formatter	v
vacuum	linter	json, openapi, yaml
verusfmt	formatter	rust, verus
veryl	formatter	veryl
vhdl-style-guide	formatter	vhdl
vint	linter	vimscript
wa	formatter	wa
wfindent	formatter	fortran
write-good	linter
xmlformat	formatter	xml
xmllint	linter	xml
xo	linter	javascript, typescript
xq	formatter	html, xml
yamlfix	formatter	yaml
yamlfmt	formatter	yaml
yamllint	linter	yaml
yapf	formatter	python
yard-lint	linter	ruby
yew-fmt	formatter	rust
yq	formatter	yaml
zig	formatter	zig
ziggy	formatter	ziggy
zprint	formatter	clojure, clojurescript
zsweep	linter	zsh
zuban	linter	python