Skip to main content
The sync command downloads and installs Vale style packages from external sources defined in your .vale.ini configuration file.

​
Usage

vale sync
This command reads the Packages setting from your .vale.ini file and downloads each package to your StylesPath directory.
Run vale sync after adding new packages to your configuration or when setting up Vale in a new environment.

​
Configuration

Define packages in the root section of your .vale.ini file:
.vale.ini
StylesPath = styles
MinAlertLevel = suggestion

Packages = https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip, \
           https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip

[*]
BasedOnStyles = Vale, Microsoft, write-good
​
Packages
string
Comma-separated list of package URLs to download. Each URL should point to a .zip file containing a Vale style package.Packages can come from:
  • GitHub releases (most common)
  • Direct URLs to .zip files
  • Any HTTP/HTTPS endpoint serving Vale packages

​
How It Works

1

Read configuration

Vale locates your .vale.ini file and parses the Packages list.
2

Download packages

Each package URL is downloaded in sequence with a progress indicator:
Syncing Microsoft
Syncing write-good
✔ Synced 2 package(s) to 'styles'.
3

Extract and install

Each .zip file is extracted to your StylesPath directory. The package name is derived from the filename.
4

Verify installation

After syncing, the styles are immediately available for use in your configuration.

​
Package Sources

​
Official Vale Styles

Vale maintains several official style packages:

Microsoft

Microsoft Writing Style Guide rules
https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip

Google

Google Developer Documentation Style Guide
https://github.com/errata-ai/Google/releases/latest/download/Google.zip

write-good

Naive linter for English prose
https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip

proselint

Linter for prose from Corinne Shuttleworth
https://github.com/errata-ai/proselint/releases/latest/download/proselint.zip

​
Custom Packages

You can host your own Vale packages:
1

Create package structure

Organize your style rules in a directory:
MyStyle/
├── rule1.yml
├── rule2.yml
└── vocabularies/
    ├── accept.txt
    └── reject.txt
2

Create zip file

Compress the directory:
zip -r MyStyle.zip MyStyle/
3

Host the package

Upload to GitHub releases, a web server, or any accessible URL.
4

Add to configuration

Reference the URL in your .vale.ini:
Packages = https://example.com/MyStyle.zip

​
Examples

StylesPath = styles
Packages = https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip

[*]
BasedOnStyles = Microsoft

​
Common Workflows

​
Initial Setup

When setting up Vale in a new project: 
# Create .vale.ini with desired packages
echo "StylesPath = styles
Packages = https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip

[*]
BasedOnStyles = Microsoft" > .vale.ini

# Download packages
vale sync

# Start linting
vale .

​
CI/CD Integration

In continuous integration pipelines:
GitHub Actions
steps:
  - uses: actions/checkout@v3
  
  - name: Install Vale
    run: |
      wget https://github.com/errata-ai/vale/releases/latest/download/vale_Linux_64-bit.tar.gz
      tar -xzf vale_Linux_64-bit.tar.gz
      sudo mv vale /usr/local/bin/
  
  - name: Sync Vale packages
    run: vale sync
  
  - name: Run Vale
    run: vale .

​
Update Packages

To update to the latest package versions: 
# Remove existing packages
rm -rf styles/*

# Re-download
vale sync
Using latest in GitHub release URLs ensures you always get the most recent package version when running vale sync.

​
Troubleshooting

​
Package Download Fails

If a package fails to download:
  • Verify the URL is accessible in a browser
  • Check network connectivity and firewall rules
  • Ensure you have write permissions to the StylesPath directory
  • Try downloading the .zip file manually to test

​
Package Not Found After Sync

If styles aren’t available after syncing:
  • Verify the package extracted to the correct directory
  • Check that the style name in BasedOnStyles matches the package directory name
  • Run vale ls-dirs to confirm your StylesPath location
  • Inspect the package contents to ensure it has .yml rule files

​
Configuration Pipeline

Packages are stored in the .vale-config subdirectory of your StylesPath as part of Vale’s configuration pipeline. This directory is managed automatically and shouldn’t be modified manually.
Don’t commit the .vale-config directory to version control. Instead, commit your .vale.ini configuration and run vale sync to install packages.

​
Directory Structure

After running sync, your project structure looks like: 
project/
├── .vale.ini
└── styles/
    ├── .vale-config/      # Managed by sync (don't modify)
    ├── Microsoft/         # Downloaded package
    │   ├── rule1.yml
    │   └── rule2.yml
    └── write-good/        # Downloaded package
        ├── rule1.yml
        └── rule2.yml
  • ls-dirs - View default directories including StylesPath
  • ls-config - Verify your configuration loaded correctly

Build docs developers (and LLMs) love

Get started for freeTalk to us