remark-cli

12.0.1 verified Sat Apr 25 auth: no javascript

Command-line interface for processing markdown with the remark ecosystem. Current stable version is 12.0.1, released as part of the remark monorepo. The CLI allows inspecting, linting, and transforming markdown files using over 150 plugins. It is the primary way to integrate remark into CI/CD pipelines or npm scripts. Key differentiators: full access to the unified ecosystem, supports configuration files (JSON, YAML, JS), and can output formatted syntax trees. Requires Node.js 16+. ESM-only package, does not support CommonJS require().

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/remark-cli/index.js from /path/to/project/script.js not supported. ↓

cause Using require() to import remark-cli, which is ESM-only since v12.

fix

Use import { remark } from 'remark' for programmatic use, or run CLI via npx or npm scripts.

error Cannot find module 'remark-preset-lint-markdown-style-guide' ↓

cause The preset package is not installed or not in node_modules.

fix

Run npm install --save-dev remark-preset-lint-markdown-style-guide

error SyntaxError: Unexpected token 'export' ↓

cause Using CommonJS module.exports in a .remarkrc.js config file; ESM syntax required.

fix

Change module.exports to export default. Ensure package.json has type: module or use .mjs extension.

error Error: Cannot find module './local-plugin' ↓

cause Relative path to local plugin missing file extension; Node.js ESM resolution requires full extension.

fix

Use --use ./local-plugin.mjs (or .js/.cjs with type: module) instead of just ./local-plugin.

Warnings

breaking ESM-only since version 12.0.0: require() is not supported. Use import or run via npx. ↓

fix Update Node.js to 16+ and use import syntax in config files.

breaking Node.js 12 support dropped in v11.0.0 (and Node 14 dropped in v12.0.0). Current minimum is Node 16. ↓

fix Upgrade Node.js to version 16 or higher.

gotcha If using --output, the file is overwritten without confirmation. Always back up or use version control. ↓

fix Ensure you have a backup or use version control before running with --output.

deprecated The --report option with custom reporters may not work with ESM-only plugins in newer versions. ↓

fix Use only built-in reporters ('json', 'vfile-reporter-json') or verify plugin ESM compatibility.

gotcha Plugin resolution changed in v11.0.0 to match modern Node.js behavior. Relative paths like ./plugins/custom.mjs now require .mjs extension. ↓

fix Specify full extension for local plugins (e.g., --use ./plugin.mjs).

breaking YAML 1.2 compliance introduced in v11.0.0 may cause parsing differences in config files that relied on YAML 1.1 quirks. ↓

fix Review .remarkrc or .remarkignore files for YAML 1.2 compatibility (e.g., boolean values, octal numbers).

Install

npm install remark-cli

yarn add remark-cli

pnpm add remark-cli

Imports

remark-cli (binary)

wrong

remark . --use remark-validate-links (without npx if not globally installed)

correct

npx remark . --use remark-validate-links

Best used via npx or as a devDependency script. Global install not recommended.

Programmatic API (run)
wrong
```
import remark from 'remark-cli'
```
correct
```
import { remark } from 'remark'
```
remark-cli is a CLI wrapper; use the 'remark' package for programmatic use.
Config file (remark.config.js or .remarkrc.js)
wrong
```
module.exports = { plugins: ['remark-preset-lint-consistent'] }
```
correct
```
export default { plugins: ['remark-preset-lint-consistent'] }
```
Since remark-cli 12.0.0, config files are ESM-only. Use export default.

Quickstart

Configure a lint script for markdown files in package.json using remark-cli with a preset.

{
  "scripts": {
    "lint:md": "remark . --frail --use remark-preset-lint-consistent --quiet"
  },
  "devDependencies": {
    "remark-cli": "^12.0.1",
    "remark-preset-lint-consistent": "^6.0.0"
  }
}