{"id":18674,"library":"postcss-cli","title":"PostCSS CLI","description":"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.","status":"active","version":"11.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/postcss/postcss-cli","tags":["javascript","cli","postcss","postcss-runner"],"install":[{"cmd":"npm install postcss-cli","lang":"bash","label":"npm"},{"cmd":"yarn add postcss-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add postcss-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: PostCSS must be installed separately to run the CLI. This was a breaking change in version 8.0.0.","package":"postcss","optional":false}],"imports":[{"note":"The CLI is invoked as 'postcss', not 'postcss-cli'. The package provides a binary named 'postcss'.","wrong":"npx postcss-cli input.css -o output.css","symbol":"CLI (executable)","correct":"npx postcss input.css -o output.css"},{"note":"Though primarily a CLI tool, postcss-cli can also be used programmatically (e.g., for testing). Ensure you import from 'postcss-cli', not 'postcss'.","wrong":"const postcss = require('postcss')","symbol":"Programmatic API","correct":"const postcss = require('postcss-cli')"}],"quickstart":{"code":"npm install --save-dev postcss postcss-cli\n\n# Basic usage: compile input.css to output.css\nnpx postcss input.css -o output.css\n\n# Watch mode\nnpx postcss input.css -o output.css --watch\n\n# Using a config file (postcss.config.js)\n# Example config:\n# module.exports = {\n#   plugins: [\n#     require('autoprefixer'),\n#   ]\n# }\nnpx postcss src/*.css --dir build --base src\n\n# With stdin/stdout piping\ncat input.css | npx postcss -u autoprefixer > output.css\n\n# Specify environment\nNODE_ENV=production npx postcss input.css -o output.css --no-map","lang":"javascript","description":"Installation and common CLI usage patterns: basic output, watch mode, config file, glob/dir, piping, and env variables."},"warnings":[{"fix":"Install postcss alongside postcss-cli: npm install --save-dev postcss postcss-cli","message":"PostCSS is now a peer dependency (v8.0.0). You must install postcss separately.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Upgrade Node to v18 or later, or use an older version of postcss-cli.","message":"Dropped support for Node 6 & 8 (v7.0.0) and Node 4 (v6.0.0). PostCSS CLI v11 requires Node >=18.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Ensure you have the correct PostCSS version installed: npm install postcss@8","message":"Upgrade to PostCSS v8 (v8.0.0) with peer dependency; v6.0.0 upgraded to PostCSS v7.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Add --verbose flag to see detailed output, or check exit codes and output files.","message":"CLI is silent by default since v5.0.0. Use --verbose for noisy logs.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Use long option names (e.g., --output, --dir, --version).","message":"Non-obvious shorthand arguments removed in v5.0.0 (-x, -p, -s, -t, -e, -b, -c), also -v removed as --version alias.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Remove 'from'/'to' from your postcss.config.js; the CLI handles them automatically.","message":"Cannot set 'from' or 'to' options in config file; they are always set by the CLI.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run: npm install postcss@8 --save-dev","cause":"Incompatible PostCSS version installed. postcss-cli v8+ requires PostCSS 8.","error":"Error: PostCSS plugin postcss-import requires PostCSS 8."},{"fix":"Use npx postcss or install globally: npm install -g postcss postcss-cli. Alternatively, add a script in package.json.","cause":"postcss-cli not installed or not in PATH.","error":"postcss: command not found"},{"fix":"Remove `from` and `to` from your config file; they are automatically supplied by the CLI.","cause":"postcss.config.js contains `from` or `to` options which are reserved for CLI.","error":"Error: The `from` option should be set by the CLI, not in config"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}