Technical Documentation: vale-cli/vale
ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference
Overview (`README.md`)
Vale doesn't ship opinions of its own. It's a framework for enforcing your style: a published guide like Microsoft's or Google's, an in-house set of terms, or both. It's run by teams at AWS, NVIDIA, Microsoft, GitLab, and Red Hat, among others who publish their configs.
$ vale sync
SUCCESS Synced 2 package(s) to 'styles'.
$ vale docs/
docs/configure.md
3:7 suggestion Consider using 'use' instead of 'utilize'. Microsoft.Wordiness
3:44 suggestion 'are loaded' looks like passive voice. Microsoft.Passive
9:12 error Use 'Vale CLI' instead of 'Vale cli'. Docs.Terms
docs/install.md
3:40 warning Use 'select' instead of the input-specific verb 'Click'. Microsoft.UIVerbs
4:28 error Did you really mean 'existant'? Vale.Spelling
✖ 2 errors, 1 warning and 2 suggestions in 2 files.:heart: Sponsors
Hi there! I'm @jdkato, the sole developer of Vale. If you'd like to help me dedicate more time to developing, documenting, and supporting Vale, feel free to donate through GitHub Sponsors or Open Collective. Any donation—big, small, one-time, or recurring—is greatly appreciated!
Spotlights
Sponsors at $1,000 and above get a dedicated page on vale.sh.
Grants
Vale received a $10,000 grant from FLOSS/fund in its second 2025 tranche, alongside FFmpeg, Zig, Wireshark, and Blender.
Organizations
Everyone who funds Vale, individuals included, is listed on the sponsors page.
Infrastructure
Thanks to GitBook for hosting the documentation.
Why Vale
Most tools see text. Vale sees a document.
- It parses your markup instead of guessing at it. Markdown, AsciiDoc, reStructuredText, HTML, and every other format go through a real parser. A rule can target headings, lists, or table cells, and code spans, URLs, and fenced blocks are skipped before a rule ever runs. See Scopes.
- Your comments are documentation too. Vale lifts comments and docstrings out of source code with tree-sitter grammars, so a comment marker inside a string literal stays code. The Markdown in a Rust doc comment, or the reStructuredText in a Python docstring, is linted as though it were its own file. See Code.
- It finds prose in files that aren't prose. A View says where the writing is in an OpenAPI description, a notebook cell, or a commit message, so Vale lints that and passes over the rest.
- Rules are files, and they read grammar. Extension points in YAML run from a token list to part-of-speech patterns, cross-file relationships, readability formulas, and scripts. A rule can carry its own fix, which an editor applies with one keystroke and an agent applies without deciding anything.
- One binary, nothing alongside it. Written in Go, with no runtime to install and files linted in parallel. See the benchmark on GitLab's documentation.
- Private by design. Nothing leaves your machine: no account, no upload, and no training on your writing.
Install
| macOS | brew install vale |
| Windows | choco install vale · winget install -e --id errata-ai.Vale |
| Linux | sudo snap install vale · sudo pacman -S vale · sudo apt install vale |
| Docker | docker pull jdkato/vale |
| Go | go install github.com/vale-cli/vale/v3/cmd/vale@latest |
Every release also ships prebuilt binaries for each platform. Scoop, MacPorts, FreeBSD ports, conda-forge, the APT archive, and the rest are on the installation page.
Quickstart
Vale needs a configuration file that says where to keep styles and which to apply. Create one at the root of your project:
StylesPath = styles
MinAlertLevel = suggestion
Packages = Microsoft
[*.md]
BasedOnStyles = Vale, MicrosoftThen download the styles and lint something:
vale sync
vale README.mdThe Quickstart walks through each step. To skip the reading, open a chat already pointed at vale.sh/AGENTS.md and have an assistant set it up.
Styles
A style is a folder of YAML rules. Start from one that's published—Microsoft, Google, Red Hat, and more are one line in your config away—and browse them all in the Package Explorer. Or write your own:
# styles/Docs/Terms.yml
extends: substitution
message: "Use '%s' instead of '%s'."
level: error
swap:
'Vale cli|vale-cli': Vale CLIThat's the whole rule. See Styles for the rest, and Vale CMS to author a full project—config, rules, vocabularies, and tests—in the browser, with the real engine linting live.
Contributing
Bug reports, feature requests, documentation fixes, and pull requests are all welcome. Start with the contributing guide, which covers setting up a development environment, testing, benchmarking, and the contributor license agreement. This project follows a code of conduct.
License
Overview (`testdata/hunspell/README.md`)
Hunspell conformance fixtures
Copied from the tests/ directory of hunspell/hunspell
at commit f06471975def682cf0c7cb291235e2512de7abb5 (2026-09-13). Only the.aff, .dic, .good, .wrong, and .sug files are kept.
Hunspell is tri-licensed MPL 1.1 / GPL 2.0+ / LGPL 2.1+ (license.hunspell).
These files are used here under the Mozilla Public License 1.1, a copy of which
is in LICENSE. They are test data read by go test only and are never
compiled into or distributed with a Vale binary. The rest of this repository
remains under its own license.
internal/spell/hunspell_test.go runs every fixture: each word in .good must be accepted,
and each line in .wrong must be rejected. Fixtures the checker does not pass
yet are listed there with the reason, so the list is the scoreboard.
Overview (`testdata/styles/README.md`)
NOTE: These styles are maintained for testing purposes only. You can
find the publicly available styles at https://github.com/errata-ai/styles.
Overview (`testdata/pkg/write-good/README.md`)
Based on write-good.
Naive linter for English prose for developers who can't write good and wanna learn to do other stuff good too.
The MIT License (MIT)
Copyright (c) 2014 Brian Ford
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.Overview (`testdata/styles/Joblint/README.md`)
Based on Joblint.
Test tech job posts for issues with sexism, culture, expectations, and recruiter fails.
Copyright (c) 2015, Rowan Manning
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.Overview (`testdata/styles/proselint/README.md`)
Copyright © 2014–2015, Jordan Suchow, Michael Pacer, and Lara A. Ross
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Overview (`testdata/styles/write-good/README.md`)
Based on write-good.
Naive linter for English prose for developers who can't write good and wanna learn to do other stuff good too.
The MIT License (MIT)
Copyright (c) 2014 Brian Ford
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.--- METRICS ---
- Files Extracted: 7
- Estimated Token Budget: ~3966 tokens
- Canonical Reference: https://codewiki.google/github.com/vale-cli/vale