> For the complete documentation index, see [llms.txt](https://docs.vale.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vale.sh/topics/cli.md).
# CLI
Learn how the `vale` command reads its input, finds its configuration, and reports.
## [Input](#input)
`vale` takes files, directories, or nothing:
```sh
vale README.md docs/ # named files and directories, recursively
cat draft.md | vale --ext=.md # standard input
vale "Some text to check." # a string that is not a path
```
A directory is walked for every file its configuration has a section for, narrowed by `--glob` when one is given; see [Globbing](/guides/globbing.md). Input on stdin is read as plain text unless `--ext` names a format, or `--path` names the file it came from, which also puts it under that path's configuration section. An argument that is neither a file nor a directory is linted as text, so a mistyped path that is nearly a command name is reported rather than checked.
With no input and nothing on stdin, `vale` prints a short introduction and an example configuration.
## [Configuration](#configuration)
A run needs a configuration file, found in this order:
1. The file named by `--config`.
2. The file named by `VALE_CONFIG_PATH`.
3. The first of `.vale.ini`, `_vale.ini`, `vale.ini`, `.vale`, or `_vale` found in the working directory or any directory above it, then in the home directory.
Whichever one is found, the user-level configuration in the operating system's config directory is read too, underneath it, so preferences that hold across projects live in one place and a project's own settings win. `vale ls-dirs` prints where that is, and `--no-global` leaves it out of a run.
The same two environment variables `ls-vars` reports are all Vale reads:
| Variable | Description |
| ------------------ | ------------------------------------------------------------------------------------------ |
| `VALE_CONFIG_PATH` | A configuration file to use instead of searching for one. |
| `VALE_STYLES_PATH` | The default [`StylesPath`](/keys/stylespath.md), used when no configuration file sets one. |
## [Commands](#commands)
| Name | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sync` | Install every entry in the configuration's Packages key into the StylesPath. Run it after adding a package, and in CI before linting.
$ vale sync
|
| `ls-config` | Resolve the configuration the way a lint run would, every source in order, and print the result as JSON. The fastest way to see which styles and rules a directory has in scope.
$ vale ls-config
|
| `ls-metrics` | Print the counts Vale computed while reading a file, as JSON: words, sentences, paragraphs, and the elements of its markup. See metric.
$ vale ls-metrics README.md
|
| `ls-dirs` | Print where Vale looks for the default StylesPath, the user-level configuration, and the native messaging host, and whether each is there.
$ vale ls-dirs
|
| `ls-vars` | Print the environment variables Vale reads, what each does, and its current value.
$ vale ls-vars
|
| `help` | Print the listing of options and commands, or one command's own help.
$ vale help sync
|
`ls-config`, `ls-dirs`, and `ls-vars` print JSON instead of a table under `--output=JSON`. The tables look like this on macOS:
```console
$ vale ls-dirs
Asset | Default Location | Found
StylesPath | /Users/me/Library/Application Support/vale/styles | ✓
.vale.ini | /Users/me/Library/Application Support/vale/.vale.ini | ✗
vale-native | /Users/me/Library/Application Support/vale/native/vale-native | ✗
$ vale ls-vars
Variable | Description | Value
VALE_CONFIG_PATH | Override the default search process by specifying a .vale.ini file. | ✗
VALE_STYLES_PATH | Specify the location of the default StylesPath. | ✗
```
## [Options](#options)
| Name | Description | |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `--config` | The configuration file to use, instead of searching for one.
$ vale --config='path/to/.vale.ini' README.md
| |
| `--output` | The report format: CLI, line, JSON, or the path of a template. See Output.
$ vale --output=JSON README.md
| |
| `--minAlertLevel` | The lowest level to report: suggestion, warning, or error. Overrides the configuration's MinAlertLevel.
$ vale --minAlertLevel=error README.md
| |
| `--glob` | A pattern the files under a directory must match. See Globbing.
$ vale --glob='\*.md' docs/
| |
| `--filter` | An expression choosing which rules run. See Filters.
$ vale --filter='.Level == "error"' README.md
| |
| `--ext` | The format to read stdin as, by file extension.
$ echo "This is Markdown" | vale --ext=.md
|
| `--path` | The file stdin stands for, so its configuration section and format apply and its path appears in the report.
$ cat draft.md | vale --path=docs/draft.md
|
| `--ignore-syntax` | Read every file as plain text, line by line, with no markup parsing.
$ vale --ignore-syntax README.md
| |
| `--no-exit` | Exit 0 even when errors were found.
$ vale --no-exit README.md
| |
| `--no-wrap` | Do not wrap long messages in the CLI format.
$ vale --no-wrap README.md
| |
| `--no-color` | Do not color the CLI format.
$ vale --no-color README.md
| |
| `--no-global` | Do not read the user-level configuration.
$ vale --no-global README.md
| |
| `--plain-progress` | Log each step of a long operation instead of redrawing a progress bar, for CI logs that keep every frame.
$ vale sync --plain-progress
| |
| `--version`, `-v` | Print the version.
$ vale --version
| |
| `--help`, `-h` | Print the listing of options and commands. After a command, that command's help.
$ vale sync --help
| |
## [Output](#output)
`--output` chooses how alerts are reported. The built-in formats sort them by line and column within each file.
**`CLI`**, the default, is a colored table per file with a summary line, wrapped to the terminal's width unless `--no-wrap` says otherwise:
Each row is the line and column, the level, the message, and the rule that fired. The summary counts every alert at or above `MinAlertLevel`, and the exit code follows the errors.
**`line`** is one alert per line, in the shape editors and scripts parse:
```console
$ vale --output=line README.md
README.md:3:17:write-good.Weasel:'very' is a weasel word!
README.md:3:37:write-good.Passive:'were fixed' may be passive voice. Use active voice if you can.
README.md:6:23:Vale.Spelling:Did you really mean 'detials'?
```
**`JSON`** is an object keyed by file path, each holding its alerts. An alert carries the rule, the level, the matched text, its line and span, the message, and any [action](/topics/actions.md) with what it resolves to:
```json
{
"README.md": [
{
"Action": { "Name": "replace", "Params": ["use"] },
"Suggestions": ["use"],
"Span": [9, 15],
"Check": "House.Terms",
"Description": "",
"Link": "",
"Message": "Use 'use' instead of 'utilize'.",
"Severity": "error",
"Match": "utilize",
"Line": 1
}
]
}
```
**A template** is anything else: the path of a Go template, or the name of one in the `StylesPath`'s `config/templates` directory, rendered with the same data. See [Templates](/topics/templates.md).
Errors in Vale's own configuration are printed to standard error, and follow `--output` where the format has a place for them: a rule that fails to load reports its file and line.
## [Exit codes](#exit-codes)
| Code | Meaning |
| ---- | ------------------------------------------------------------------------------------------------------------------ |
| `0` | The run completed and found no alert at the `error` level. Warnings and suggestions do not change the code. |
| `1` | The run completed and found at least one `error`. `--no-exit` turns this into `0`, for a CI job that reports only. |
| `2` | Vale itself could not run: a missing configuration, a rule that failed to load, an argument that is not a path. |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.vale.sh/topics/cli.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.