🔍 Zsh Lint

zsh-lint is a standalone semantic analyzer for Zsh. Give it one or more source-file paths and it reports parser errors, correctness problems, and advisory findings in a greppable format.

Try it in five minutes

Install the current published release with an exact version:

go install github.com/z-shell/zsh-lint/cmd/zsh-lint@v1.3.0

Then check a file:

zsh-lint path/to/script.zsh

If Go's binary directory is not already on your PATH, run the installed binary as "$(go env GOPATH)/bin/zsh-lint".

:::important File recognition The published CLI does not inspect a shebang, require a .zsh extension, scan directories, or discover source files. Every explicit path is treated as Zsh source. Only the zsh-lint.json project configuration is discovered automatically; see Project configuration. An extensionless autoloaded function works when you name it directly, while a Bash file is still parsed as Zsh if you pass its path. :::

For parser-only corpus evaluation without lint rules, use the advanced zsh-lint-survey command.

Choose a guide

Getting started

Install a pinned release, lint a small script, and understand the result.

Run the first check →

Choosing files

Learn how explicit paths, shebangs, extensions, directories, and mixed shell repositories behave.

Select inputs →

Project configuration

Describe plugins and multi-profile projects in a zsh-lint.json that the CLI discovers automatically.

Configure a project →

Rules and suppressions

Read diagnostics and document intentional exceptions without hiding other rules.

Handle findings →

CI and JSON

Add a reproducible GitHub Actions check and consume structured output.

Automate checks →

Troubleshooting

Resolve install, input, parser, exit-code, and configuration surprises.

Fix common problems →

Parser survey

Use the advanced parser-coverage command without running lint rules.

Survey a corpus →

Published rule reference

See the readable rule set generated from the latest published release.

Browse rules →

Published behavior

The guides describe v1.3.0, which includes project configuration and automatic zsh-lint.json discovery. Automatic source-file discovery and shebang-based classification are not implemented; that design is tracked in zsh-lint issue 183.

Source code and development status live in z-shell/zsh-lint.