Commands

clover <command>

run

Resolve every annotation and rewrite its target line.

clover run [options] [<path>…]

With no paths, Clover scans the current directory. Pass files or directories to narrow the run. --no-ignore is also accepted by lint and format.

--infer is the zero-annotation mode: every line auto-detection recognizes is updated as if it carried a bare provider=auto directive, without writing any comments. Written directives keep priority on their own lines (their constraint and other rules apply as usual), a clover:ignore control still opts a line out, and a recognized line that would not resolve is skipped rather than failing the run. Use annotate instead when you want the directives in the file, where they can carry selection rules and document intent.

--enable and --disable narrow the run to a subset of providers, matched against the provider each marker resolves to (a provider=auto marker after inference, a follower after the producer it follows). --enable is authoritative, so --enable=github,docker resolves only GitHub and Docker markers and leaves every other line untouched. --disable is subtractive, so --disable=node resolves everything except Node markers. Both accept a comma-separated list or repeated flags, name any provider except manual (which owns its line and always runs), and cannot be combined. A skipped marker drops out of the run rather than reporting, exactly as an unmatched --tag would.

--offline answers every lookup from the HTTP cache without touching the network. Cached responses are served even when their freshness has lapsed, since revalidating would need the origin, and a marker whose lookup is not cached fails with an offline error. It implies --cache, so the cross-run disk tier is read even where a config disables it, and a recent online run against the same tree is what makes an offline run useful.

--to rewrites every matched marker to one explicit version instead of the newest allowed, which makes it the rollback tool. The version is picked from the upstream listing, so digests and checksums still resolve for a release that really exists, and a version the upstream does not publish fails the marker. The pin bypasses each directive’s own selection rules (constraint, include/exclude, prerelease, cooldown, behind) and implies --downgrade and --force, though an explicit flag such as --no-force still wins. Every matched marker receives the same version, so combine it with paths, -t, or --enable to scope the pin. Markers that follow a floating ref (track=) or own their line (manual) resolve as usual.

lint

Validate that every directive parses, resolves, and has a find pattern that matches the target line, without touching any files or making network calls. Useful in CI.

clover lint [options] [<path>…]

lint accepts the same -t/--tag selection and -o, --output options as run.

format

Rewrite directive comments into canonical form and key order, migrating deprecated spellings. No version changes.

clover format [options] [<path>…]

--check is the CI gate, while --dry-run previews the same rewrites but exits zero.

annotate

Add @clover directives to lines Clover can already track but that carry none. For example, GitHub Actions uses: pins and container image references can be annotated automatically. It is the inverse of auto-detection. Rather than resolving an existing auto marker, it finds the lines such a marker would resolve and writes one above each.

clover annotate [options] [<path>…]

Unlike run and format, annotate previews by default and writes only with --write, since it inserts new lines. Set annotate.write to opt in to writing by default, or annotate.check to make annotate a default CI gate. --dry-run, --write, and --check override the configured mode for one invocation. Every annotation is verified offline first, and unresolved lines are left alone.

Pass global --verbose with annotate to show recognized candidates Clover deliberately skipped, including the reason they failed validation or were opted out.

Existing annotations are never touched without --force. With it, an annotation Clover itself would produce (provider=auto, or an explicit provider the line infers) is collapsed back to @clover, dropping the provider/repository/registry keys that inference supplies (and host, when the line itself names one) while preserving every selection rule (constraint, include, cooldown, …). A deliberately explicit directive Clover cannot infer (provider=http, a find/replace, a tracked ref) is left untouched. A clover:ignore control opts a line out of annotation just as it opts it out of resolution.

login

Authenticate with a provider (for higher rate limits or private sources). GitHub and GitLab use an OAuth device flow, while Gitea uses a browser-based loopback flow.

Pass --host to authenticate against a GitHub Enterprise Server, self-managed GitLab, or a non-default Gitea flavor such as gitea.com. A self-managed GitHub or GitLab instance runs its own OAuth application, so --host there requires a matching --client-id, while the public hosts use their built-in app.

clover login                                              # GitHub (default)
clover login gitlab
clover login gitea --host gitea.com
clover login github --host ghe.example.com --client-id <id>

update

Update Clover to the latest release through Homebrew, the sanctioned update path.

clover update [options]

Clover will periodically check for updates and hint when a newer release is available. Set CLOVER_NO_UPDATE_CHECK=1 to disable it.