{"id":17193,"library":"cspell-cli","title":"CSpell CLI","description":"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.","status":"active","version":"10.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/streetsidesoftware/cspell-cli","tags":["javascript","cspell"],"install":[{"cmd":"npm install cspell-cli","lang":"bash","label":"npm"},{"cmd":"yarn add cspell-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add cspell-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the core spelling logic and dictionaries; cspell-cli is a wrapper around it.","package":"cspell","optional":false}],"imports":[{"note":"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).","wrong":"import { lint } from 'cspell-cli';","symbol":"cspell-cli (command)","correct":"npx cspell-cli <command> [args...]"}],"quickstart":{"code":"const fs = require('fs');\nconst { spawnSync } = require('child_process');\n\nconst testFilePath = 'test-file.js';\nfs.writeFileSync(testFilePath, `\n// This is a tst file with some typoes.\nconst myVariable = 'hte';\nfunction chekSpelling() {\n  console.log(myVariable);\n}\nchekSpelling();\n`);\n\nconsole.log(`Checking '${testFilePath}' with cspell-cli...`);\n\n// Execute cspell-cli via npx to check the dummy file\n// npx will fetch cspell-cli if it's not locally installed.\nconst cspellProcess = spawnSync('npx', ['cspell-cli', testFilePath], { encoding: 'utf8' });\n\nconsole.log('\\n--- cspell-cli Output ---');\nconsole.log(cspellProcess.stdout);\nconsole.error(cspellProcess.stderr);\n\nif (cspellProcess.status === 0) {\n  console.log('\\nNo spelling errors found or process exited successfully.');\n} else {\n  console.log(`\\nSpelling errors found or process exited with code ${cspellProcess.status}.`);\n}\n\n// Clean up the dummy file\nfs.unlinkSync(testFilePath);\n","lang":"javascript","description":"Demonstrates how to programmatically execute `cspell-cli` via `npx` to spell check a temporary JavaScript file, capturing its output and exit status."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=10.0.0"},{"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`).","message":"This package requires Node.js version 20 or higher to run. Using older Node.js versions will result in execution errors.","severity":"gotcha","affected_versions":">=10.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`.","cause":"The `cspell-cli` package is not installed globally, or `npx` is not available/used, preventing the system from finding the executable.","error":"cspell-cli: command not found"},{"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).","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.","error":"Error: EACCES: permission denied, open '.../cspell.json'"},{"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`.","cause":"The current Node.js runtime environment is older than the minimum required version (Node.js 20) specified by `cspell-cli`.","error":"cspell-cli requires Node.js version >=20"},{"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.","cause":"`cspell-cli` could not locate a configuration file in the expected paths, or the specified path was incorrect.","error":"Configuration file 'cspell.config.yaml' not found."}],"ecosystem":"npm","meta_description":null}