CSpell CLI

10.0.0 · active · verified Wed Apr 22

cspell-cli is the command-line interface for cspell, a robust spelling checker specifically designed for codebases. It provides comprehensive functionality to lint files, check spelling, trace words, and manage dictionaries directly from the terminal. The package is currently on a major version 10.0.0, released in April 2026, and follows a frequent release cadence, often updating in lockstep with new versions of the core cspell library. These updates can sometimes introduce breaking changes. Its key differentiators include extensive configuration options for various file types and languages, seamless integration with pre-commit hooks, and strong support for custom dictionaries, making it an essential tool for maintaining high code quality and consistency across diverse projects.

Common errors

```
cspell-cli: command not found
```
cause The `cspell-cli` package is not installed globally, or `npx` is not available/used, preventing the system from finding the executable.

fix Run `npx cspell-cli <command>` to use the project-local version or download it temporarily, or install it globally with `npm install -g cspell-cli`.
```
Error: EACCES: permission denied, open '.../cspell.json'
```
cause `cspell-cli` is attempting to create or modify configuration files (e.g., `cspell.json`, `cspell.config.yaml`) in a directory where the current user lacks write permissions.

fix Ensure the user executing `cspell-cli` has appropriate write permissions to the target directory. If necessary, adjust file permissions or run the command with elevated privileges (e.g., `sudo npx cspell-cli ...`, used with caution).
```
cspell-cli requires Node.js version >=20
```
cause The current Node.js runtime environment is older than the minimum required version (Node.js 20) specified by `cspell-cli`.

fix Upgrade your Node.js installation to version 20 or newer. Tools like `nvm` (Node Version Manager) can help manage multiple Node.js versions: `nvm install 20 && nvm use 20`.
```
Configuration file 'cspell.config.yaml' not found.
```
cause `cspell-cli` could not locate a configuration file in the expected paths, or the specified path was incorrect.

fix Create a `cspell.config.yaml` or `cspell.json` file in your project's root directory, or explicitly specify its location using the `--config <path>` option. Ensure the filename and path are correct.

Warnings

breaking Version 10.0.0 introduces significant breaking changes due to updating the underlying `cspell` library to its 10.x series. This may affect configuration files, dictionary formats, and CLI options.
Fix: Review the full `cspell` changelog for version 10.0.0 for specific API and configuration adjustments. Update existing `cspell.config.yaml` or `cspell.json` files and any automation scripts accordingly.
gotcha This package requires Node.js version 20 or higher to run. Using older Node.js versions will result in execution errors.
Fix: Ensure your development environment, CI/CD pipelines, and any runtime environments for `cspell-cli` are upgraded to Node.js 20 or a newer compatible version (e.g., using `nvm install 20 && nvm use 20`).
gotcha Installing `cspell-cli` globally (`npm install -g cspell-cli`) can lead to version inconsistencies, especially in projects that expect a specific version of `cspell-cli` or `cspell`.
Fix: It is generally recommended to use `npx cspell-cli` to ensure the project-local version (defined in `package.json`) is used, promoting consistent behavior across development environments. Only install globally if you explicitly manage a system-wide `cspell` version.
gotcha The `lint` command is the default action when `cspell-cli` is executed without a specific command. This can lead to unexpected behavior if users intend a different command (e.g., `check`) and omit it.
Fix: Always explicitly specify the command you intend to run (e.g., `cspell-cli lint .` or `cspell-cli check file.js`) to avoid ambiguity and ensure predictable execution.

Install

npm install cspell-cli npm
yarn add cspell-cli yarn
pnpm add cspell-cli pnpm

Imports

cspell-cli (command)
wrong:
```
import { lint } from 'cspell-cli';
```
correct:
```
npx cspell-cli <command> [args...]
```
This package is designed exclusively as a command-line interface. It does not export modules for programmatic `import` or `require()` usage. Its functionality is accessed solely by executing the `cspell-cli` command directly (e.g., via `npx` or a global installation).

Quickstart

Demonstrates how to programmatically execute `cspell-cli` via `npx` to spell check a temporary JavaScript file, capturing its output and exit status.

const fs = require('fs');
const { spawnSync } = require('child_process');

const testFilePath = 'test-file.js';
fs.writeFileSync(testFilePath, `
// This is a tst file with some typoes.
const myVariable = 'hte';
function chekSpelling() {
  console.log(myVariable);
}
chekSpelling();
`);

console.log(`Checking '${testFilePath}' with cspell-cli...`);

// Execute cspell-cli via npx to check the dummy file
// npx will fetch cspell-cli if it's not locally installed.
const cspellProcess = spawnSync('npx', ['cspell-cli', testFilePath], { encoding: 'utf8' });

console.log('\n--- cspell-cli Output ---');
console.log(cspellProcess.stdout);
console.error(cspellProcess.stderr);

if (cspellProcess.status === 0) {
  console.log('\nNo spelling errors found or process exited successfully.');
} else {
  console.log(`\nSpelling errors found or process exited with code ${cspellProcess.status}.`);
}

// Clean up the dummy file
fs.unlinkSync(testFilePath);

view raw JSON →