postcss-cli

library11.0.1jsnpmunverified

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.

devops

npm install postcss-cli

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POSTCSS-CLI

postcss-cli

devopsjavascriptv11.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CLI (executable)

✓ npx postcss input.css -o output.css

✗ npx postcss-cli input.css -o output.css

The CLI is invoked as 'postcss', not 'postcss-cli'. The package provides a binary named 'postcss'.

Programmatic API

✓ const postcss = require('postcss-cli')

✗ const postcss = require('postcss')

Though primarily a CLI tool, postcss-cli can also be used programmatically (e.g., for testing). Ensure you import from 'postcss-cli', not 'postcss'.

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

postcss --version

Debug

Known issues

breakingPostCSS 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

affects: >=8.0.0

breakingDropped 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.

affects: >=7.0.0

breakingUpgrade 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

affects: >=6.0.0

gotchaCLI 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.

affects: >=5.0.0

gotchaNon-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).

affects: >=5.0.0

gotchaCannot 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.

affects: all

Errors

Common errors & fixes

Error: PostCSS plugin postcss-import requires PostCSS 8.

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

fix

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

postcss: command not found

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: The `from` option should be set by the CLI, not in config

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.

Upgrade

Version history

11.0.1latest on npm

Audit

Dependencies

postcssrequiredPeer dependency: PostCSS must be installed separately to run the CLI. This was a breaking change in version 8.0.0.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/postcss/postcss-cli ↗

packagehttps://www.npmjs.com/package/postcss-cli ↗

homepagehttps://postcss.org/ ↗