postcss-cli

postcss-cli is the official command-line runner for PostCSS, the tool that parses CSS into an AST so plugins can transform it programmatically. It wraps postcss-load-config’s resolution flow, so plugins and options defined in a postcss.config.js are picked up automatically, letting teams standardize how CSS is processed across a project without hand-writing a build script.

Beyond straightforward single-file transforms, postcss-cli supports directory-wide globs via —dir, in-place edits via —replace, and a watch mode built on chokidar that recompiles only the files actually affected by a changed dependency, tracked through an internal dependency graph derived from PostCSS’s own dependency messages. It also handles inline or external source maps, custom parsers/stringifiers/syntaxes, and per-file processing context so a postcss.config.js function can vary options file by file.

What You Get

• A single binary (the postcss command) that runs your existing postcss.config.js plugin chain against any file, directory, or glob pattern.
• Directory-wide processing via —dir, optionally mirroring the input folder structure into the output directory with —base.
• Watch mode that recompiles only the files affected by a changed dependency, tracked via a dependency graph built from PostCSS’s own dependency and dir-dependency messages.
• Built-in inline or external source map generation, plus support for custom parsers, stringifiers, and syntaxes (e.g. SugarSS) without extra tooling.

Common Use Cases

• Compiling a CSS bundle through a chain of PostCSS plugins (postcss-import, autoprefixer, cssnano) as part of an npm build script.
• Replacing a Sass/Less pipeline with plain CSS plus PostCSS plugins configured once in postcss.config.js.
• Watching a src/ directory during development so edits to any imported partial or config file trigger a targeted recompile.
• Piping CSS through PostCSS plugins in a shell pipeline (cat input.css | postcss -u autoprefixer > output.css) for one-off transforms.

Under The Hood

Architecture

index.js is a single procedural entry point: it parses argv via lib/args.js (yargs), expands glob/dir input with tinyglobby, resolves each file’s config through postcss-load-config (wrapped in a local rc helper that rejects from/to overrides), runs the file through postcss(), and writes output via lib/outputFile.js, which skips the write entirely if content is unchanged. Watch mode layers chokidar on top, tracking which files depend on which via lib/DependencyGraph.js, a thin wrapper around the dependency-graph package that consumes PostCSS’s own dependency/dir-dependency result messages, so a changed partial only triggers recompilation of its actual dependents rather than the whole input set. There’s no framework or DI layer — it’s a small set of single-purpose lib/ modules around one script, with the dependency-tracked watch mode as the one genuinely stateful piece.

Tech Stack

The package is pure ESM (“type”: “module”) and requires Node >=22. Runtime dependencies are all narrowly scoped: chokidar (watching), dependency-graph, picocolors (terminal color), postcss-load-config (config resolution), postcss-reporter (warning formatting), pretty-hrtime, read-cache, slash, tinyglobby (globbing), and yargs (argument parsing), with postcss itself as a peer dependency. No bundler is involved — the package ships its plain ESM source (index.js plus lib/) directly per its “files” field. CI runs the Node 22/24/26 matrix on both Ubuntu and Windows via GitHub Actions.

Code Quality

The test/ directory holds a broad set of CLI-level integration tests (covering config resolution, directory processing, globbing, source maps, custom parsers/syntaxes, replace mode, stdin/stdout, and watch mode) run with ava, each spawning the actual built binary through a shared test/helpers/cli.js rather than mocking internals, plus a couple of colocated unit tests next to lib/ modules. The ci npm script chains eslint, the ava/c8 coverage run, and a prettier format check, so lint and formatting are enforced before merge. The codebase is plain JavaScript with no static type checking (no TypeScript, no JSDoc type annotations observed).

API Design The CLI mirrors postcss.config.js options directly onto flags (—map/—no-map, —parser, —stringifier, —syntax), so users don’t have to learn a separate flag vocabulary. Defaults are sensible — no output flag falls back to stdout, no input falls back to stdin — and yargs renders a grouped, example-driven —help. Getting started requires minimal boilerplate: npm i -D postcss postcss-cli then postcss input.css -o output.css runs with zero configuration, and error messages name the specific problem (e.g. rejecting --dir/--replace combined with stdin, or from/to overrides in the config file) rather than failing generically.