PostCSS CLI

11.0.1 verified Sat Apr 25 auth: no javascript

Official command-line interface for PostCSS, the popular CSS post-processor. Current stable version is 11.0.1 (2024-05-??). PostCSS CLI allows you to run PostCSS plugins from the terminal, supporting input/output files, directories, glob patterns, stdin/stdout piping, and watch mode. It requires Node ≥18 and PostCSS ≥8 as a peer dependency. Unlike alternative tools like PostCSS's programmatic API or build tool plugins, this CLI is designed for direct command-line usage and scripting, with support for configuration files (postcss.config.js), custom parsers/syntaxes, and sourcemaps. Version 8.0.0 made PostCSS a peer dependency, and version 7.0.0 dropped Node 6 & 8 support. The tool is actively maintained by the PostCSS core team.

Common errors

error Error: PostCSS plugin postcss-import requires PostCSS 8. ↓

cause Incompatible PostCSS version installed. postcss-cli v8+ requires PostCSS 8.

fix

Run: npm install postcss@8 --save-dev

error postcss: command not found ↓

cause postcss-cli not installed or not in PATH.

fix

Use npx postcss or install globally: npm install -g postcss postcss-cli. Alternatively, add a script in package.json.

error Error: The `from` option should be set by the CLI, not in config ↓

cause postcss.config.js contains `from` or `to` options which are reserved for CLI.

fix

Remove from and to from your config file; they are automatically supplied by the CLI.

Warnings

breaking PostCSS is now a peer dependency (v8.0.0). You must install postcss separately. ↓

fix Install postcss alongside postcss-cli: npm install --save-dev postcss postcss-cli

breaking Dropped support for Node 6 & 8 (v7.0.0) and Node 4 (v6.0.0). PostCSS CLI v11 requires Node >=18. ↓

fix Upgrade Node to v18 or later, or use an older version of postcss-cli.

breaking Upgrade to PostCSS v8 (v8.0.0) with peer dependency; v6.0.0 upgraded to PostCSS v7. ↓

fix Ensure you have the correct PostCSS version installed: npm install postcss@8

gotcha CLI is silent by default since v5.0.0. Use --verbose for noisy logs. ↓

fix Add --verbose flag to see detailed output, or check exit codes and output files.

gotcha Non-obvious shorthand arguments removed in v5.0.0 (-x, -p, -s, -t, -e, -b, -c), also -v removed as --version alias. ↓

fix Use long option names (e.g., --output, --dir, --version).

gotcha Cannot set 'from' or 'to' options in config file; they are always set by the CLI. ↓

fix Remove 'from'/'to' from your postcss.config.js; the CLI handles them automatically.

Install

npm install postcss-cli

yarn add postcss-cli

pnpm add postcss-cli

Imports

CLI (executable)
wrong
```
npx postcss-cli input.css -o output.css
```
correct
```
npx postcss input.css -o output.css
```
The CLI is invoked as 'postcss', not 'postcss-cli'. The package provides a binary named 'postcss'.
Programmatic API
wrong
```
const postcss = require('postcss')
```
correct
```
const postcss = require('postcss-cli')
```
Though primarily a CLI tool, postcss-cli can also be used programmatically (e.g., for testing). Ensure you import from 'postcss-cli', not 'postcss'.

Quickstart

Installation and common CLI usage patterns: basic output, watch mode, config file, glob/dir, piping, and env variables.

npm install --save-dev postcss postcss-cli

# Basic usage: compile input.css to output.css
npx postcss input.css -o output.css

# Watch mode
npx postcss input.css -o output.css --watch

# Using a config file (postcss.config.js)
# Example config:
# module.exports = {
#   plugins: [
#     require('autoprefixer'),
#   ]
# }
npx postcss src/*.css --dir build --base src

# With stdin/stdout piping
cat input.css | npx postcss -u autoprefixer > output.css

# Specify environment
NODE_ENV=production npx postcss input.css -o output.css --no-map