Diagnostic CLI

The jetls check command runs JETLS diagnostics on Julia files from the command line, without requiring an editor or LSP client. This is useful for CI pipelines, pre-commit hooks, and workflows where editor integration is not available.

For details on what each diagnostic code means, see the Diagnostic reference.

Basic usage

# Check the package in the current directory
jetls check

# Check a package in another directory
jetls check /path/to/SomePkg

# Check a package source file
jetls check src/SomePkg.jl

# Check multiple files
jetls check src/SomePkg.jl test/runtests.jl

# Check code read from stdin
jetls check - <<< 'f(x) = undefined_name + x'

# Check multiple files with multi threads
jetls --threads=4,2 -- check src/SomePkg.jl test/runtests.jl

Command reference

jetls check --help

jetls check - Run diagnostics on Julia files

Analyzes Julia source files and reports errors, warnings, and suggestions.
Useful for CI pipelines and command-line workflows.

Usage: jetls check [OPTIONS] [<path>...]

Arguments:
  <path>...                Julia files or package directories to check;
                           a package directory is checked via its src/<name>.jl
                           (default: the package at the root path)

Options:
  --help, -h               Show this help message
  --quiet, -q              Suppress info and warning log messages
  --stdin-filename=<path>  Check the source read from stdin as if it were the
                           file at <path>, which does not need to exist
                           (default: an unsaved buffer shown as <stdin>)
  --exit-severity=<level>  Minimum severity to exit with error code 1
                           (error, warn, info, hint; default: warn)
  --show-severity=<level>  Minimum severity to display in output
                           (error, warn, info, hint; default: info)
  --root=<path>            Set the root path for configuration and relative paths
                           (default: the package directory if exactly one is
                           given, otherwise the current working directory)
  --context-lines=<n>      Number of context lines to show (default: 2)
  --progress=<mode>        Progress display mode (default: auto)
                           auto   - spinner if TTY, simple otherwise
                           full   - always show spinner
                           simple - one line per file
                           none   - no progress output

Exit codes:
  0  No diagnostics at or above the exit severity level
  1  One or more diagnostics found, or invalid arguments

Examples:
  jetls check
  jetls check /path/to/SomePkg
  jetls check src/SomePkg.jl
  jetls check . test/runtests.jl
  jetls check --root=/path/to/project src/SomePkg.jl
  jetls check --context-lines=0 src/SomePkg.jl
  jetls check --exit-severity=error src/SomePkg.jl
  jetls check --show-severity=warn src/SomePkg.jl
  jetls check --progress=none src/SomePkg.jl
  jetls check - <<< 'f(x) = undefined_name + x'
  sed 's/helper/helper2/g' src/utils.jl | jetls check --stdin-filename=src/utils.jl -

Input paths and analysis mode

jetls check accepts Julia files and package directories as input.

A package directory is a directory whose Project.toml has a name entry. It is analyzed through its package entry file src/<name>.jl. Test files are not included; pass test/runtests.jl as well to analyze them. Other directories, including subdirectories of a package such as src/, are rejected.

When no path is given, the package at the root path (the current working directory by default) is analyzed.

Files are analyzed in the same way as in the language server, as described in How each file is analyzed: the analysis mode is determined by the nearest Project.toml above each file and the file's location relative to it, regardless of the working directory. Unlike the language server, jetls check also analyzes files outside the root path. The root path only determines where .JETLSConfig.toml is loaded from and how paths are displayed (see --root).

Reading source from stdin

Passing - as a path reads Julia source from stdin, which is useful for checking code that is not saved to a file:

jetls check - <<'EOF'
function f(x)
    return undefined_name + x
end
EOF

By default, the source is analyzed like an unsaved buffer in the language server (see Unsaved buffers and notebooks) and is displayed as <stdin>. With --stdin-filename, it is analyzed as the file at the given path instead.

Options

--root=<path>

Sets the root path for configuration file lookup and relative path display. By default, the package directory is used when exactly one package directory is given, and the current working directory otherwise.

When specified, JETLS will:

• Look for .JETLSConfig.toml in the specified root directory
• Resolve relative input paths against this root
• Display file paths relative to this root in diagnostic output

# Use project root for configuration
jetls check --root=/path/to/project src/SomePkg.jl

# Useful when running from a different directory
cd /tmp && jetls check --root=/path/to/project /path/to/project/src/SomePkg.jl

--stdin-filename=<path>

Analyzes the source read from stdin as if it were the file at <path>, which is resolved like other input paths. The file does not need to exist; if it does, its contents on disk are ignored.

The path determines how the source is analyzed, in the same way as for the file at that path: the analysis mode, path-specific configuration, and the files it includes. For a package source file, the package is analyzed with the source substituted for the file on disk. This allows checking changes to a package file before writing them:

# Check src/utils.jl, which src/SomePkg.jl includes, with `helper` renamed
# to `helper2`, without modifying the file
sed 's/helper/helper2/g' src/utils.jl | jetls check --stdin-filename=src/utils.jl -

Without --stdin-filename, the source is analyzed as a standalone script, so names defined in the other files of the package would be reported as undefined.

Unlike a package directory input, --stdin-filename does not set the root path, so run the command in the package directory as above, or specify --root, to load the package's .JETLSConfig.toml.

--context-lines=<n>

Controls how many lines of source code context are shown around each diagnostic. Default is 2.

# Show more context
jetls check --context-lines=5 src/SomePkg.jl

# Show no context (just the diagnostic line)
jetls check --context-lines=0 src/SomePkg.jl

--exit-severity=<level>

Sets the minimum severity level that causes a non-zero exit code. This is useful for CI pipelines where you want to fail only on certain severity levels.

After analysis completes, the final line reports whether the check passed or failed and the exit severity used.

Available levels (from most to least severe):

• error - Only errors cause exit code 1
• warn (default) - Warnings and errors cause exit code 1
• info - Information, warnings, and errors cause exit code 1
• hint - All diagnostics cause exit code 1

# Only fail CI on errors
jetls check --exit-severity=error src/SomePkg.jl

# Fail CI on any diagnostic
jetls check --exit-severity=hint src/SomePkg.jl

--show-severity=<level>

Sets the minimum severity level to display in the output. The default is info, independently of --exit-severity. Diagnostics below the display threshold are hidden but may still affect the exit code. The summary includes counts of hidden diagnostics by severity and indicates how to display them.

Available levels (from most to least severe):

• error - Only show errors
• warn - Show warnings and errors
• info (default) - Show information, warnings, and errors
• hint - Show all diagnostics

# Only display warnings and errors (hide info and hints)
jetls check --show-severity=warn src/SomePkg.jl

# Show all diagnostics but only fail on errors
jetls check --show-severity=hint --exit-severity=error src/SomePkg.jl

--progress=<mode>

Controls how progress is displayed during analysis.

Available modes:

• auto (default) - Uses spinner for interactive terminals, simple output otherwise
• full - Always show animated spinner with detailed progress
• simple - One line per file (e.g., Analyzing [1/5] src/foo.jl...)
• none - No progress output

# Suppress progress for cleaner CI logs
jetls check --progress=none src/SomePkg.jl

# Force simple output even in terminal
jetls check --progress=simple src/SomePkg.jl

Julia runtime flags

Since jetls is an executable Julia app, you can pass Julia runtime flags before -- to configure the Julia runtime. This is especially useful for controlling threading behavior. JETLS's signature analysis phase is parallelized, so increasing thread count may improve analysis performance.

# Run with 4 default threads and 2 interactive threads
jetls --threads=4,2 -- check src/SomePkg.jl

For more details on available runtime flags, see the Pkg documentation on runtime flags.

Configuration

jetls check loads .JETLSConfig.toml from the root path (see --root for its default). This is the same configuration file used by the language server, and includes:

• Diagnostic severity overrides
• Pattern-based diagnostic filtering
• Path-specific rules

Example configuration to suppress certain diagnostics in CI:

.JETLSConfig.toml

# Ignore unused arguments in test files
[[diagnostic.patterns]]
pattern = "lowering/unused-argument"
match_by = "code"
match_type = "literal"
severity = "off"
path = "test/**/*.jl"

Package environments that are not instantiated yet (e.g. a fresh clone in CI) are resolved and instantiated before analysis. jetls check has no client to confirm with, so the default auto_instantiate = "prompt" behaves like "always" here. Set it to "never" in .JETLSConfig.toml to analyze against the environment as is.

For complete configuration options, see the JETLS configuration page.

GitHub Actions

A composite action is available for running jetls check in CI pipelines. This handles Julia setup, caching, and JETLS installation automatically.

Basic usage

steps:
  - uses: actions/checkout@v6
  - uses: aviatesk/JETLS.jl/.github/actions/check@release

Without files, this checks the package at the repository root.

With options

steps:
  - uses: actions/checkout@v6
  - uses: aviatesk/JETLS.jl/.github/actions/check@release
    with:
      files: src/SomePkg.jl test/runtests.jl
      exit-severity: error
      show-severity: warn

Action inputs

All jetls check command-line options are available as action inputs:

See .github/actions/check/action.yml for the full action definition.