Vale CLI

Canonical version: Vale CLI.

Vale is a command-line linter for prose, written in Go by Joseph Kato (@jdkato), under the MIT License. Its tagline: "Vale: Your style, our editor."

Vale does not check whether your writing is correct. It checks whether your writing follows your rules. Grammarly and its cousins have opinions and impose them; Vale has none until you give it some. That makes an interesting tool when several people write in one voice and the voice is written down somewhere.

What makes it different

• Markup-aware. It parses Markdown, AsciiDoc, reStructuredText, HTML, XML and Org rather than treating them as plain text, so syntax stops producing false positives and code blocks are excluded from prose rules.
• Code-aware. It reads comments and docstrings through tree-sitter grammars for 20+ languages, so your API docs get linted where they actually live.
• Fully offline. Nothing gets sent anywhere. For anyone drafting unpublished work, that alone rules out most of the alternatives.
• A single binary. Go, no runtime to install, no pip or npm prerequisite. Runs on macOS, Windows and Linux.
• Extensible in YAML. New rules need no compilation and no plugin API. You write a YAML file.

A style guide nobody enforces is a document. A style guide with a linter is a system.

How rules work

A style is a folder of YAML rules. Each rule picks one of twelve extension points:

existence · substitution · occurrence · repetition · consistency · capitalization · readability · spelling · conditional · metric · script · sequence

Every rule carries a message, a level (suggestion, warning, error) and its pattern. Scope selectors narrow a rule to headings, or to links, or to anything but code, so "no exclamation marks in headings" is a rule you can actually express.

Configuration lives in .vale.ini at the repo root, naming which styles are active and at what severity. vale sync pulls the packages you declared.

Ready-made packages exist for the Microsoft and Google style guides, plus community sets like write-good, proselint, alex and Joblint, browsable in the Package Explorer.

The surrounding pieces

Vale is more than the CLI now:

• Vale CMS (cms.vale.sh), a hosted browser authoring layer for building a style guide with the real engine linting live before changes ship back to your repo
• Vale Studio, a web playground
• Config Generator, for producing a starting .vale.ini
• vale-ls, a Language Server Protocol implementation in Rust, which is what gets you in-editor squiggles in VS Code, Neovim and anything else that speaks LSP
• vale-action, the official GitHub Actions integration

Install via Homebrew, Chocolatey, Docker, or a downloaded binary.

References

Main

• vale.sh — home
• Documentation
• Installation guide
• Styles and extension points
• Supported markup formats

Tools

• Vale CMS — hosted authoring layer
• Vale Studio — web playground
• Config Generator
• Package Explorer
• Library

Source

• vale-cli/vale — the CLI (Go)
• vale-cli/vale-ls — language server (Rust)
• vale-cli/vale-action — GitHub Action (TypeScript)
• vale-cli/packages — pre-packaged style guides
• vale-cli on GitHub — the organisation

Community and support

• Discord
• Vale Guru — Q&A over the docs
• Joseph Kato (@jdkato) — sole developer
• GitHub Sponsors
• Open Collective

Packages

• Homebrew
• Chocolatey
• Docker Hub

Related

• My Voice Profile
• Markdown
• AsciiDoc
• Grammarly
• Go
• Rust
• GitHub Actions
• Docker
• Neovim
• Open Source
• MIT License

About Sébastien

Ready to get to the next level?