PostCSS CLI

PostCSS CLI is a command-line interface tool for processing CSS files using PostCSS plugins. It provides comprehensive features for CSS processing workflows including file watching, sourcemaps, directory processing, and flexible plugin configuration.

Package Information

• Package Name: postcss-cli
• Package Type: npm
• Language: JavaScript (Node.js)
• Installation: npm install -D postcss postcss-cli
• Node.js Requirement: >=18
• Module Type: ESM (ES Modules)

Core Installation

PostCSS CLI requires PostCSS as a peer dependency:

npm install -D postcss postcss-cli

Basic Usage

# Basic file processing
postcss input.css -o output.css

# Directory processing
postcss src/**/*.css --base src --dir build

# Watch mode for development
postcss input.css -o output.css --watch

# Pipe processing
cat input.css | postcss -u autoprefixer > output.css

Capabilities

CLI Command

The main postcss command provides all functionality through command-line options.

postcss [input.css] [OPTIONS] [-o|--output output.css] [--watch|-w]
postcss <input.css>... [OPTIONS] --dir <output-directory> [--watch|-w]
postcss <input-directory> [OPTIONS] --dir <output-directory> [--watch|-w]
postcss <input-glob-pattern> [OPTIONS] --dir <output-directory> [--watch|-w]
postcss <input.css>... [OPTIONS] --replace

Basic Options:

• -o, --output - Output file (conflicts with --dir, --replace)
• -d, --dir - Output directory (conflicts with --output, --replace)
• -r, --replace - Replace (overwrite) the input file (conflicts with --output, --dir)
• -m, --map - Create an external sourcemap
• --no-map - Disable the default inline sourcemaps
• -w, --watch - Watch files for changes and recompile as needed
• --verbose - Be verbose with processing output
• --env - A shortcut for setting NODE_ENV

Plugin Options (without config file):

• -u, --use - List of postcss plugins to use
• --parser - Custom postcss parser
• --stringifier - Custom postcss stringifier
• --syntax - Custom postcss syntax

Directory Options (for use with --dir):

• --ext - Override the output file extension
• --base - Mirror the directory structure relative to this path in the output directory

Advanced Options:

• --include-dotfiles - Enable glob to match files/dirs that begin with "."
• --poll - Use polling for file watching (optional interval, default 100ms)
• --config - Set a custom directory to look for a config file

Input/Output Patterns

Single File Processing:

postcss input.css -o output.css

Multiple File Processing:

postcss file1.css file2.css --dir build/

Directory Processing:

postcss src/ --dir build/

Glob Pattern Processing:

postcss src/**/*.css --base src --dir build/

Replace Mode:

postcss src/**/*.css --replace

Stdin/Stdout Processing:

cat input.css | postcss > output.css
# Or with plugins
cat input.css | postcss -u autoprefixer > output.css

File Watching

Watch mode monitors input files and dependencies for changes:

# Basic watch mode
postcss input.css -o output.css --watch

# Watch with directory output
postcss src/**/*.css --base src --dir build --watch

# Watch with polling (useful for network drives)
postcss input.css -o output.css --watch --poll
postcss input.css -o output.css --watch --poll 500  # Custom interval

Watch Features:

• Monitors input files and their dependencies
• Smart recompilation based on dependency changes
• Non-fatal error handling in watch mode
• Dependency tracking for @import and similar statements

Sourcemap Support

PostCSS CLI provides flexible sourcemap options:

# Default: inline sourcemaps
postcss input.css -o output.css

# External sourcemaps
postcss input.css -o output.css --map

# Disable sourcemaps
postcss input.css -o output.css --no-map

Sourcemap Behavior:

• Inline sourcemaps are enabled by default
• External sourcemaps create .map files alongside output
• Custom sourcemap annotations supported via config
• Cannot output external sourcemaps when writing to stdout

Plugin Configuration

CLI Plugin Usage (without config file):

# Single plugin
postcss input.css -o output.css -u autoprefixer

# Multiple plugins
postcss input.css -o output.css -u autoprefixer -u cssnano

# Custom parser/syntax
postcss input.sss -o output.css --parser sugarss
postcss input.css -o output.css --syntax postcss-scss

Config File Support:

PostCSS CLI automatically discovers postcss.config.js files:

// postcss.config.js
module.exports = {
  parser: 'sugarss',
  plugins: [
    require('postcss-import')({ ...options }),
    require('postcss-url')({ url: 'copy', useHash: true }),
  ]
}

Context-Aware Configuration:

// postcss.config.js with context
module.exports = (ctx) => ({
  map: ctx.options.map,
  parser: ctx.file.extname === '.sss' ? 'sugarss' : false,
  plugins: {
    'postcss-import': { root: ctx.file.dirname },
    cssnano: ctx.env === 'production' ? {} : false
  }
})

Context Object Properties:

• ctx.env - NODE_ENV value (default: 'development')
• ctx.file - File information object with dirname, basename, extname
• ctx.options - PostCSS options including map, parser, syntax, stringifier

Configuration Restrictions:

• Cannot set from or to options in config files (CLI-controlled)
• Use --config to specify custom config directory
• CLI options override config file settings when using context

Directory Processing Features

Base Path Mirroring:

# Mirror directory structure
postcss src/components/**/*.css --base src --dir build/
# Input: src/components/button.css → Output: build/components/button.css

Extension Override:

# Change output extension
postcss src/**/*.scss --ext .css --dir build/

Dotfile Processing:

# Include hidden files in glob matching
postcss src/**/*.css --include-dotfiles --dir build/

Error Handling and Logging

Verbose Mode:

postcss input.css -o output.css --verbose

Error Types Handled:

• CSS syntax errors with formatted output
• Plugin loading and execution errors
• File system read/write errors
• Configuration validation errors
• Dependency resolution errors

Exit Codes:

• 0 - Success
• 1 - Error (except in watch mode where processing continues)

Environment and Context

Environment Control:

# Set NODE_ENV for config functions
postcss input.css -o output.css --env production

File Context in Config: Each processed file provides context to config functions:

• File path information (dirname, basename, extname)
• CLI options passed through
• Environment variables

Configuration Examples

Basic Plugin Chain:

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-import'),
    require('autoprefixer'),
    require('cssnano')
  ]
}

Environment-Specific Configuration:

// postcss.config.js
module.exports = (ctx) => ({
  map: ctx.options.map,
  plugins: {
    'postcss-import': { root: ctx.file.dirname },
    'autoprefixer': {},
    'cssnano': ctx.env === 'production' ? {} : false
  }
})

File Extension-Based Processing:

// postcss.config.js
module.exports = (ctx) => ({
  parser: ctx.file.extname === '.sss' ? 'sugarss' : false,
  plugins: [
    require('postcss-import'),
    require('autoprefixer')
  ]
})

Integration Patterns

Build Tool Integration:

# npm scripts
"scripts": {
  "css:build": "postcss src/styles.css -o dist/styles.css",
  "css:watch": "postcss src/styles.css -o dist/styles.css --watch",
  "css:prod": "postcss src/styles.css -o dist/styles.css --env production"
}

CI/CD Usage:

# Production build with error checking
postcss src/**/*.css --base src --dir dist/ --env production
if [ $? -ne 0 ]; then
  echo "CSS build failed"
  exit 1
fi

Development Workflow:

# Development with watch and verbose output
postcss src/**/*.css --base src --dir build/ --watch --verbose

Performance Features

• Incremental Processing: Only reprocesses changed files in watch mode
• Dependency Tracking: Smart recompilation based on file dependencies
• File Caching: Uses read-cache for file content caching
• Change Detection: Skips writing if output content is unchanged
• Parallel Processing: Processes multiple files concurrently

Limitations

• No Programmatic API: This is a CLI tool only, no Node.js API is exported
• No Library Functions: All functionality is CLI-specific
• Config File Restrictions: Cannot set from/to options in config files
• Watch Mode Limitations: Cannot watch when reading from stdin
• Stdout Limitations: Cannot use external sourcemaps or watch mode with stdout output