CLI reference

Invoked as jaxlint (see [project.scripts] in pyproject.toml) or python -m jaxlint.

If no subcommand is given, Typer shows help (no_args_is_help).

Global behavior

• Paths: Most commands accept zero or more file or directory paths. If omitted, the default is the current directory (.).

• --config PATH: Config discovery anchor (see configuration). May be a directory (walk upward for jaxlint.toml then pyproject.toml) or a file path to jaxlint.toml or pyproject.toml (parse that file only; relative paths inside the file resolve against its directory). Defaults to the current working directory when omitted.

jaxlint check

Run performance (AST) sensors and, unless disabled, docstring sections + MathJax checks.

Option	Description
PATHS...	Files or directories (*.py discovered under directories).
--no-doc	Skip docstring sections and MathJax.
--no-perf	Skip AST performance sensors.
--format, -f	text (default), compact (one line per diagnostic: path:line:col: severity: message (rule_id)), json, github, sarif (SARIF 2.1.0, alias sarif-2.1.0 — best-effort; not validated for GitHub Advanced Security), or rich (table layout via Rich; uses plain box drawing when stdout is not a TTY).
--config	Config file (jaxlint.toml / pyproject.toml) or directory to search from.
--select	Comma-separated rule ID prefixes; overrides config select.
--ignore	Comma-separated prefixes to ignore; overrides config ignore.
--jobs, -j	Number of parallel workers over files (thread pool). Default: min(32, usable CPU count) (os.process_cpu_count() on Python 3.13+, else os.cpu_count()). Use -j 1 for a fully serial run (no pool).
--cache-dir	Optional directory for an on-disk cache of per-file diagnostics (JSON). Speeds up repeated check runs when sources are unchanged. Overrides the config file’s cache-dir when passed (see configuration). Invalid or corrupt cache entries are ignored (fail-open).

Exit code: 1 if any diagnostic has severity error; otherwise 0. Invalid --format exits 2 (same as jaxlint hlo when the HLO extra is missing).

jaxlint doc

Docstring sections + MathJax only (no AST performance sensors).

Option	Description
PATHS...	As in check.
--format, -f	text, compact, json, github, sarif, or rich. Same semantics as check.
--config	As in check (directory walk or explicit config file).
--select, --ignore	As in check.

Exit code: 1 if any error; else 0. Invalid --format exits 2.

jaxlint score

Rubric scoring for docstrings (see RubricScorer in jaxlint.core.doc.rubric_impl).

Option	Description
PATHS...	Python files to walk; default ..
--jsonl PATH	Score entries from a JSONL file (see implementation for expected keys).
--baseline PATH	With --jsonl, print mean/pass-rate comparison when the file exists.
--threshold FLOAT	Override config rubric-threshold (default from lint config in jaxlint.toml / pyproject.toml).
--config	As in check.

Exit code: 1 if any scored item is below the threshold (file mode or JSONL mode); 0 otherwise. Syntax errors in a scanned .py print a message and count as failure for the file-walk path.

jaxlint rules

Print TSV-style lines: rule id, severity, description. Always exits 0.

jaxlint init

Print a starter [jaxlint] TOML snippet (for jaxlint.toml) to stdout. Exits 0.

jaxlint version

Print package version. Exits 0.

jaxlint hlo

If jaxlint[hlo] is installed, prints a short hint for using jaxlint.hlo from Python. Exits 0.

If the optional HLO stack cannot be imported (missing extra or JAX), prints an error to stderr and exits 2.

JSON output shape

For check and doc with --format json, output is a JSON array of objects with keys: rule_id, severity, message, path, line, col, end_line, end_col (see format_json in jaxlint.core.runner).

With --format github, output is a JSON object with an annotations array. Each element uses GitHub check run field names (start_line, end_line, annotation_level, message, title, path) suitable for tooling that posts check run annotations. Severity maps to annotation_level: error → failure, warning → warning, info → notice. Single-line diagnostics may include start_column / end_column (1-based, per GitHub); start_line ≠ end_line omits columns, matching the API restriction on multiline annotations.

With --format sarif (alias sarif-2.1.0), output is a minimal SARIF 2.1.0 log: top-level $schema, version: "2.1.0", and runs[0] with tool.driver for jaxlint and results. tool.driver.rules lists one reportingDescriptor per distinct ruleId in results (canonical text and default severity for known rules; synthetic text for unknown ids). Each result includes ruleId, ruleIndex into rules, SARIF level (error / warning / note — info diagnostics map to note; this is the effective severity after config overrides), message.text, and locations[].physicalLocation with artifactLocation.uri as an absolute file: URI and region (startLine, endLine; startColumn / endColumn only when the span is one line — same convention as GitHub annotations above). Optional per-rule helpUri is emitted when sarif-rule-docs-base is set in configuration (HTTPS base; helpUri = base + / + rule_id). This is best-effort for generic SARIF tooling and is not guaranteed for GitHub Advanced Security upload requirements.

With --format rich, output is a UTF-8 Rich panel titled jaxlint containing a table (Severity, Rule, Location, Message) and a subtitle line error=N warning=M info=K counting diagnostics by severity (zeros included). Location uses path:line:col. When stdout is a TTY and NO_COLOR is unset, severity cells use color and Location cells may embed OSC 8 terminal hyperlinks to the resolved file: URI (clickable in supporting terminals); piped or CI output stays free of hyperlink escapes. Console width uses COLUMNS when set to a positive integer (capped), else the terminal width when interactive, else 120 columns for non-TTY output. When there are no diagnostics, a single dim line reads No diagnostics. Non-interactive sessions use ASCII-safe table borders (see format_rich in jaxlint.core.runner).