vale

Check the style of a file

$ vale [path/to/file]

$ vale --config='[path/to/.vale.ini]' [path/to/file]

$ vale --output=JSON [path/to/file]

$ vale --minAlertLevel=[suggestion|warning|error] [path/to/file]

$ cat [file.md] | vale --ext=.md

$ vale ls-config

vale [options]

-h, --help
    Display help information and exit.

-v, --version
    Display Vale's version information and exit.

--config
    Specify a path to a custom configuration file (e.g., a _vale.ini file).

--ext
    Limit linting to files with the specified extensions only.

--glob
    Include files matching a specific glob pattern for linting.

--ignore-filename
    Ignore the filename when determining the syntax of the input.

--in
    Read content from a specified file (useful when piping content).

--minAlertLevel
    Set the minimum alert level to report (e.g., suggestion, warning, error).

--no-exit
    Always exit with a 0 status code, regardless of linting errors found.

--no-wrap
    Do not wrap output lines in the console.

--output
    Specify the output format (e.g., text, JSON, sarif).

--relative
    Report file paths relative to the current working directory.

--sort
    Sort the output by file path and then by line number.

--stdin
    Read content directly from standard input for linting.

--styles
    Enable only the specified styles for the linting process.

--update
    Update all configured Vale styles to their latest versions.

--debug
    Show detailed debug information during execution.

--normalize
    Use a normalized (simplified) tree for linting, potentially affecting certain rule behaviors.

Vale is a powerful command-line tool designed to help writers, editors, and technical communicators maintain consistency, enforce style guides, and catch common writing errors in various markup formats like Markdown, reStructuredText, AsciiDoc, and HTML. Unlike simple spell-checkers, Vale focuses on stylistic elements, grammar, tone, and adherence to specific style guides (e.g., Google Developer Documentation Style Guide, Microsoft Writing Style Guide, or custom rulesets).

It operates based on a highly configurable system of 'styles' and 'rules' defined in INI files, allowing users to tailor its behavior to their specific project requirements. This makes it an invaluable tool in 'documentation-as-code' workflows, where automated quality checks for written content are crucial for maintaining high standards and streamlining content creation processes.

Vale is not a standard Unix command-line utility found in base Linux distributions; it must be installed separately (e.g., via Homebrew, Scoop, Go's go install, or by downloading pre-compiled binaries). Its effectiveness is highly dependent on the quality and specificity of its configuration files and style rules, which users often need to create or adapt to their project's unique requirements. While powerful, it may not catch every grammatical nuance or stylistic subtlety that a human editor would.

Vale's primary configuration is managed through _vale.ini or .vale.ini files. These files, typically located in the project root or a user's home directory, define enabled styles, ignore rules, and other global settings, dictating how Vale processes and reports issues.

The core of Vale's functionality lies in its 'styles,' which are collections of specific 'rules.' Rules are typically written in YAML or JSON and define checks such as forbidden words, required formatting, sentence length limits, or specific grammatical patterns. Users can leverage a rich ecosystem of community-maintained styles (e.g., Google, Microsoft, write-good) or create entirely custom rule sets tailored to their unique style guides.

Vale is frequently integrated into text editors (via plugins), continuous integration/continuous deployment (CI/CD) pipelines (to automate quality checks on pull requests or commits), and various build systems. This allows for automated enforcement of writing standards, ensuring content adheres to defined quality benchmarks before publication.

Vale was created by Dale Higgs and first released around 2017. It was developed to address the growing need for a fast, customizable, and syntax-aware prose linter that could be easily integrated into modern development and documentation workflows. Its design prioritized speed, extensibility through custom rule sets, and ease of configuration via INI files. It quickly gained traction within the documentation-as-code community as a robust tool for automating consistent writing styles across large content bases, and its development continues with active community contributions.

textlint (a JavaScript-based linter for text), proselint (another popular prose linter), languagetool (an open-source grammar and style checker), markdownlint (a linter specifically for Markdown syntax and style), mdl (Markdown Linter, a Ruby-based Markdown style checker)