Quickstart

The shortest useful .alint.yml adopts a bundled ruleset and nothing else.

# yaml-language-server: $schema=https://raw.githubusercontent.com/asamarts/alint/main/schemas/v1/config.json
version: 1
extends:
  - alint://bundled/oss-baseline@v1

Drop that at the root of your repo, then:

alint check           # run all rules against the current directory
alint fix --dry-run   # preview the auto-fixes that would be applied
alint fix             # apply every fixable violation in place
alint list            # list effective rules (after extends + overrides)
alint explain <id>    # show a rule's full, resolved definition
alint explain <id> --trace  # run only that rule and explain its outcome
alint facts           # evaluate facts against the repo — debug `when:` clauses

Run alint --help for a one-line summary of every command, or alint <cmd> --help for a command's full options.

Inspecting your rules

alint list shows the effective rules (after extends: and overrides), each with its kind and a marker for a conditional ([when]) or auto-fixable ([fix]) rule:

error    needs-readme  file_exists [fix]
warning  no-bak  file_absent

alint explain <id> resolves a single rule to its full definition — its kind and categories, a one-line summary: of what the kind checks plus a docs: link to the reference, the kind's host capabilities:, kind-specific selectors:, accepted fix_ops:, the level, the paths: scope, any kind-specific options:, the author message:, the when: clause as authored, and a one-line description of the configured auto-fix:

id:         needs-readme
kind:       file_exists
categories: existence
summary:    Every glob match in paths must correspond to a real file.
capabilities: git(tracked_set) [when git_tracked_only is set]
selectors:   none
fix_ops:     file_create
docs:       https://alint.org/docs/rules/existence/file_exists/
level:      error
paths:      README.md
message:    README.md must exist.
fix:        create README.md (8 bytes)

A rule whose kind takes options shows them under an options: block — here a file_max_size rule:

id:         readme-size-cap
kind:       file_max_size
categories: content, structure
summary:    File must be at most max_bytes in size.
capabilities: git(diff) [when scope_filter.changed_since is set]
selectors:   none
fix_ops:     none
docs:       https://alint.org/docs/rules/content/file_max_size/
level:      warning
paths:      **/*.md
options:    max_bytes: 10240

Pass --no-docs to drop the docs: line (handy for narrow terminals and screen recordings). Add --format json to either for the machine shape: explain <id> --format json carries rule_kind, categories, summary, docs, capabilities, selectors, fix_ops, paths, options, message, when, conditional, fixable, and fix.

Add --trace when the static definition is not enough: alint walks the repository, evaluates only that effective rule through the production engine, and reports why it passed, violated, skipped, or failed analysis. --preview adds bounded, redacted structured-extraction and nested-child evidence. A selected command rule and configured custom facts may execute subprocesses; unrelated command rules never run. See alint explain for changed-path tracing, exit semantics, and the experimental JSON contract.

Discovering rule kinds

alint list and alint explain describe the rules configured in this repo. To browse the whole catalog of rule kinds alint ships — independent of any config, so it works in any directory — use alint rules:

alint rules list                     # every kind, with its categories and a one-line summary
alint rules list --search "at most"  # match the kind name, its aliases, AND the summary text
alint rules show file_header         # one kind in detail (accepts an alias, e.g. `header`)

--search matches summary text now, so a concept surfaces its kinds even when their names don't contain the word:

Rule catalog (2 kinds)

  file_max_lines  Content, Structure  (alias: max_lines)
                  File must have at most max_lines lines, using the same accounting as file_min_lines.
  file_max_size   Content, Structure  (alias: max_size)
                  File must be at most max_bytes in size.

alint rules show <kind> prints one kind's summary, categories, aliases, host capabilities, kind-specific selectors, accepted fix operations, and docs link (and accepts an alias, resolving to the canonical kind):

file_header
  The first N lines must match a regex (line-oriented).
  categories: Content
  aliases:    header
  capabilities: git(diff) [when scope_filter.changed_since is set]
  selectors:    none
  fix_ops:      file_prepend, insert_header
  docs:       https://alint.org/docs/rules/content/file_header/

Output formats

alint check --format human    # default; colorized; grouped by file
alint check --format json     # stable, versioned JSON schema
alint check --format sarif    # SARIF 2.1.0 (for GitHub Code Scanning)
alint check --format github   # GitHub Actions workflow commands
alint check --format markdown # PR-comment-friendly tables
alint check --format junit    # CI test-report shape
alint check --format gitlab   # GitLab Code Quality
alint check --format agent    # LLM-shaped JSON with per-violation `agent_instruction`

The agent format has a dedicated reference covering its full report shape.

Exit codes: 0 no errors; 1 one or more errors; 2 config error; 3 internal error. Warnings do not fail by default — use --fail-on-warning to flip that.

Where to next

Bundled Rulesets — one-line baselines covering Rust, Python, Go, Node, Java, .NET, PHP, monorepos, GitHub Actions hardening, version consistency, toolchain pins, agent hygiene, license compliance, and more.
Cookbook — copy-pasteable patterns for real-world repo-maintenance tasks.
Configuration — full .alint.yml field reference.
Concepts — the rule model, scopes, when-expressions, composition.