# 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."* The distinction that matters: 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 it the right 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. ## 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](https://vale.sh/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. One caveat worth recording: the GitHub organisation moved from `errata-ai` to `vale-cli`. Older links redirect, but anything you copy from a 2023 blog post points at the previous name. ## Why I keep this note Because I already have the rules; what I lack is enforcement. [[My Voice Profile]] carries a banned-words list, an anti-filler section, and a table of headline patterns that should never ship. The `osk-writing-humanizer` skill adds banned phrases and AI-pattern detection on top. Every one of those is checked today by an agent choosing to be careful, which means every one of them is checked *probabilistically*. Most of that list maps onto Vale rules directly. Banned words are an `existence` rule. Preferred replacements ("utilize" → "use", "leverage" → "use") are `substitution`. The em-dash-as-clause-separator ban is `existence` with a scope. Hedging clusters are `occurrence`. Headline patterns are `existence` scoped to headings. What survives is the genuinely judgment-heavy part: tone, register, whether the argument lands. Which is the part an agent should be spending attention on anyway. The general principle, and the reason this outlives the tool: **anything you can state as a rule should be checked by a machine, so the humans and the agents can spend their attention on what can't be.** A style guide nobody enforces is a document. A style guide with a linter is a system. ## References **Main** - [vale.sh](https://vale.sh/) — home - [Documentation](https://docs.vale.sh/) - [Installation guide](https://docs.vale.sh/topics/installation) - [Styles and extension points](https://docs.vale.sh/topics/styles) - [Supported markup formats](https://docs.vale.sh/formats) **Tools** - [Vale CMS](https://cms.vale.sh) — hosted authoring layer - [Vale Studio](https://studio.vale.sh) — web playground - [Config Generator](https://vale.sh/generator) - [Package Explorer](https://vale.sh/explorer) - [Library](https://vale.sh/library) **Source** - [vale-cli/vale](https://github.com/vale-cli/vale) — the CLI (Go) - [vale-cli/vale-ls](https://github.com/vale-cli/vale-ls) — language server (Rust) - [vale-cli/vale-action](https://github.com/vale-cli/vale-action) — GitHub Action (TypeScript) - [vale-cli/packages](https://github.com/vale-cli/packages) — pre-packaged style guides - [vale-cli on GitHub](https://github.com/vale-cli) — the organisation **Community and support** - [Discord](https://discord.gg/DM86VURrNY) - [Vale Guru](https://gurubase.io/g/vale) — Q&A over the docs - [Joseph Kato (@jdkato)](https://github.com/jdkato) — sole developer - [GitHub Sponsors](https://github.com/sponsors/jdkato) - [Open Collective](https://opencollective.com/vale) **Packages** - [Homebrew](https://formulae.brew.sh/formula/vale) - [Chocolatey](https://community.chocolatey.org/packages/vale) - [Docker Hub](https://hub.docker.com/r/jdkato/vale) ## Related - [[My Voice Profile]] - [[Markdown]] - [[AsciiDoc]] - [[Grammarly]] - [[Go]] - [[Rust]] - [[GitHub Actions]] - [[Docker]] - [[Neovim]] - [[Open Source]] - [[MIT License]]