# Technical Documentation: vale-cli/vale > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/vale-cli/vale) ### Overview (`README.md`)

Your style, our editor.

A command-line linter for prose. Turn your team's writing guidelines into checks that run
in your editor, in CI, and alongside your code—on macOS, Windows, and Linux, entirely offline.

Docs · Quickstart · Package Explorer · Vale CMS · Blog · Discord

Vale reporting alerts for a directory of Markdown files in a terminal.

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](https://vale.sh/adopters). ```console $ 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](https://github.com/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](https://github.com/sponsors/jdkato) or [Open Collective](https://opencollective.com/vale). Any donation—big, small, one-time, or recurring—is greatly appreciated! ### Spotlights

Mintlify
_{An AI-native documentation platform built for developers.}
_{Ships Vale as a built-in CI check.}

Promptless
_{Suggests doc updates when your product changes.}
_{Runs Vale on every doc its agents write.}

> Sponsors at $1,000 and above get a dedicated page on [vale.sh](https://vale.sh/sponsor). ### Grants Vale received a $10,000 grant from [FLOSS/fund](https://floss.fund/blog/second-tranche-2025-anniversary/) in its second 2025 tranche, alongside FFmpeg, Zig, Wireshark, and Blender. ### Organizations

Organizations sponsoring Vale on Open Collective

Everyone who funds Vale, individuals included, is listed on the [sponsors page](https://vale.sh/sponsor). ### Infrastructure Thanks to [GitBook](https://www.gitbook.com/solutions/open-source) for hosting the [documentation](https://docs.vale.sh).

## 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](https://docs.vale.sh/formats) 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](https://docs.vale.sh/topics/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](https://docs.vale.sh/formats/code). - **It finds prose in files that aren't prose.** A [View](https://docs.vale.sh/topics/views) 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](https://docs.vale.sh/checks/existence) 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](https://docs.vale.sh/topics/actions), 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](https://vale.sh/features/speed) 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](https://github.com/vale-cli/vale/releases) for each platform. Scoop, MacPorts, FreeBSD ports, conda-forge, the APT archive, and the rest are on the [installation page](https://docs.vale.sh/topics/installation). ## Quickstart Vale needs a configuration file that says where to keep styles and which to apply. Create one at the root of your project: ```ini StylesPath = styles MinAlertLevel = suggestion Packages = Microsoft [*.md] BasedOnStyles = Vale, Microsoft ``` Then download the styles and lint something: ```bash vale sync vale README.md ``` The [Quickstart](https://docs.vale.sh/topics/quickstart) walks through each step. To skip the reading, open a chat already pointed at [vale.sh/AGENTS.md](https://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](https://vale.sh/explorer). Or write your own: ```yaml # styles/Docs/Terms.yml extends: substitution message: "Use '%s' instead of '%s'." level: error swap: 'Vale cli|vale-cli': Vale CLI ``` That's the whole rule. See [Styles](https://docs.vale.sh/topics/styles) for the rest, and [Vale CMS](https://cms.vale.sh) 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](.github/CONTRIBUTING.md), which covers setting up a development environment, testing, benchmarking, and the [contributor license agreement](.github/CLA.md). This project follows a [code of conduct](.github/CODE_OF_CONDUCT.md). ## License [MIT](LICENSE) --- ### Overview (`testdata/hunspell/README.md`) # Hunspell conformance fixtures Copied from the `tests/` directory of [hunspell/hunspell](https://github.com/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](https://github.com/btford/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](https://github.com/rowanmanning/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: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. 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. 3. 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](https://github.com/btford/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