0
# PostCSS CLI
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: postcss-cli
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install -D postcss postcss-cli`
10
- **Node.js Requirement**: >=18
11
- **Module Type**: ESM (ES Modules)
12

13
## Core Installation
14

15
PostCSS CLI requires PostCSS as a peer dependency:
16

17
```bash
18
npm install -D postcss postcss-cli
19
```
20

21
## Basic Usage
22

23
```bash
24
# Basic file processing
25
postcss input.css -o output.css
26

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

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

33
# Pipe processing
34
cat input.css | postcss -u autoprefixer > output.css
35
```
36

37
## Capabilities
38

39
### CLI Command
40

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

43
```bash { .api }
44
postcss [input.css] [OPTIONS] [-o|--output output.css] [--watch|-w]
45
postcss <input.css>... [OPTIONS] --dir <output-directory> [--watch|-w]
46
postcss <input-directory> [OPTIONS] --dir <output-directory> [--watch|-w]
47
postcss <input-glob-pattern> [OPTIONS] --dir <output-directory> [--watch|-w]
48
postcss <input.css>... [OPTIONS] --replace
49
```
50

51
**Basic Options:**
52
- `-o, --output` - Output file (conflicts with --dir, --replace)
53
- `-d, --dir` - Output directory (conflicts with --output, --replace)
54
- `-r, --replace` - Replace (overwrite) the input file (conflicts with --output, --dir)
55
- `-m, --map` - Create an external sourcemap
56
- `--no-map` - Disable the default inline sourcemaps
57
- `-w, --watch` - Watch files for changes and recompile as needed
58
- `--verbose` - Be verbose with processing output
59
- `--env` - A shortcut for setting NODE_ENV
60

61
**Plugin Options (without config file):**
62
- `-u, --use` - List of postcss plugins to use
63
- `--parser` - Custom postcss parser
64
- `--stringifier` - Custom postcss stringifier
65
- `--syntax` - Custom postcss syntax
66

67
**Directory Options (for use with --dir):**
68
- `--ext` - Override the output file extension
69
- `--base` - Mirror the directory structure relative to this path in the output directory
70

71
**Advanced Options:**
72
- `--include-dotfiles` - Enable glob to match files/dirs that begin with "."
73
- `--poll` - Use polling for file watching (optional interval, default 100ms)
74
- `--config` - Set a custom directory to look for a config file
75

76
### Input/Output Patterns
77

78
**Single File Processing:**
79
```bash
80
postcss input.css -o output.css
81
```
82

83
**Multiple File Processing:**
84
```bash
85
postcss file1.css file2.css --dir build/
86
```
87

88
**Directory Processing:**
89
```bash
90
postcss src/ --dir build/
91
```
92

93
**Glob Pattern Processing:**
94
```bash
95
postcss src/**/*.css --base src --dir build/
96
```
97

98
**Replace Mode:**
99
```bash
100
postcss src/**/*.css --replace
101
```
102

103
**Stdin/Stdout Processing:**
104
```bash
105
cat input.css | postcss > output.css
106
# Or with plugins
107
cat input.css | postcss -u autoprefixer > output.css
108
```
109

110
### File Watching
111

112
Watch mode monitors input files and dependencies for changes:
113

114
```bash
115
# Basic watch mode
116
postcss input.css -o output.css --watch
117

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

121
# Watch with polling (useful for network drives)
122
postcss input.css -o output.css --watch --poll
123
postcss input.css -o output.css --watch --poll 500  # Custom interval
124
```
125

126
**Watch Features:**
127
- Monitors input files and their dependencies
128
- Smart recompilation based on dependency changes
129
- Non-fatal error handling in watch mode
130
- Dependency tracking for @import and similar statements
131

132
### Sourcemap Support
133

134
PostCSS CLI provides flexible sourcemap options:
135

136
```bash
137
# Default: inline sourcemaps
138
postcss input.css -o output.css
139

140
# External sourcemaps
141
postcss input.css -o output.css --map
142

143
# Disable sourcemaps
144
postcss input.css -o output.css --no-map
145
```
146

147
**Sourcemap Behavior:**
148
- Inline sourcemaps are enabled by default
149
- External sourcemaps create `.map` files alongside output
150
- Custom sourcemap annotations supported via config
151
- Cannot output external sourcemaps when writing to stdout
152

153
### Plugin Configuration
154

155
**CLI Plugin Usage (without config file):**
156
```bash
157
# Single plugin
158
postcss input.css -o output.css -u autoprefixer
159

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

163
# Custom parser/syntax
164
postcss input.sss -o output.css --parser sugarss
165
postcss input.css -o output.css --syntax postcss-scss
166
```
167

168
**Config File Support:**
169

170
PostCSS CLI automatically discovers `postcss.config.js` files:
171

172
```javascript
173
// postcss.config.js
174
module.exports = {
175
  parser: 'sugarss',
176
  plugins: [
177
    require('postcss-import')({ ...options }),
178
    require('postcss-url')({ url: 'copy', useHash: true }),
179
  ]
180
}
181
```
182

183
**Context-Aware Configuration:**
184
```javascript
185
// postcss.config.js with context
186
module.exports = (ctx) => ({
187
  map: ctx.options.map,
188
  parser: ctx.file.extname === '.sss' ? 'sugarss' : false,
189
  plugins: {
190
    'postcss-import': { root: ctx.file.dirname },
191
    cssnano: ctx.env === 'production' ? {} : false
192
  }
193
})
194
```
195

196
**Context Object Properties:**
197
- `ctx.env` - NODE_ENV value (default: 'development')
198
- `ctx.file` - File information object with `dirname`, `basename`, `extname`
199
- `ctx.options` - PostCSS options including `map`, `parser`, `syntax`, `stringifier`
200

201
**Configuration Restrictions:**
202
- Cannot set `from` or `to` options in config files (CLI-controlled)
203
- Use `--config` to specify custom config directory
204
- CLI options override config file settings when using context
205

206
### Directory Processing Features
207

208
**Base Path Mirroring:**
209
```bash
210
# Mirror directory structure
211
postcss src/components/**/*.css --base src --dir build/
212
# Input: src/components/button.css → Output: build/components/button.css
213
```
214

215
**Extension Override:**
216
```bash
217
# Change output extension
218
postcss src/**/*.scss --ext .css --dir build/
219
```
220

221
**Dotfile Processing:**
222
```bash
223
# Include hidden files in glob matching
224
postcss src/**/*.css --include-dotfiles --dir build/
225
```
226

227
### Error Handling and Logging
228

229
**Verbose Mode:**
230
```bash
231
postcss input.css -o output.css --verbose
232
```
233

234
**Error Types Handled:**
235
- CSS syntax errors with formatted output
236
- Plugin loading and execution errors
237
- File system read/write errors
238
- Configuration validation errors
239
- Dependency resolution errors
240

241
**Exit Codes:**
242
- `0` - Success
243
- `1` - Error (except in watch mode where processing continues)
244

245
### Environment and Context
246

247
**Environment Control:**
248
```bash
249
# Set NODE_ENV for config functions
250
postcss input.css -o output.css --env production
251
```
252

253
**File Context in Config:**
254
Each processed file provides context to config functions:
255
- File path information (dirname, basename, extname)
256
- CLI options passed through
257
- Environment variables
258

259
## Configuration Examples
260

261
**Basic Plugin Chain:**
262
```javascript
263
// postcss.config.js
264
module.exports = {
265
  plugins: [
266
    require('postcss-import'),
267
    require('autoprefixer'),
268
    require('cssnano')
269
  ]
270
}
271
```
272

273
**Environment-Specific Configuration:**
274
```javascript
275
// postcss.config.js
276
module.exports = (ctx) => ({
277
  map: ctx.options.map,
278
  plugins: {
279
    'postcss-import': { root: ctx.file.dirname },
280
    'autoprefixer': {},
281
    'cssnano': ctx.env === 'production' ? {} : false
282
  }
283
})
284
```
285

286
**File Extension-Based Processing:**
287
```javascript
288
// postcss.config.js
289
module.exports = (ctx) => ({
290
  parser: ctx.file.extname === '.sss' ? 'sugarss' : false,
291
  plugins: [
292
    require('postcss-import'),
293
    require('autoprefixer')
294
  ]
295
})
296
```
297

298
## Integration Patterns
299

300
**Build Tool Integration:**
301
```bash
302
# npm scripts
303
"scripts": {
304
  "css:build": "postcss src/styles.css -o dist/styles.css",
305
  "css:watch": "postcss src/styles.css -o dist/styles.css --watch",
306
  "css:prod": "postcss src/styles.css -o dist/styles.css --env production"
307
}
308
```
309

310
**CI/CD Usage:**
311
```bash
312
# Production build with error checking
313
postcss src/**/*.css --base src --dir dist/ --env production
314
if [ $? -ne 0 ]; then
315
  echo "CSS build failed"
316
  exit 1
317
fi
318
```
319

320
**Development Workflow:**
321
```bash
322
# Development with watch and verbose output
323
postcss src/**/*.css --base src --dir build/ --watch --verbose
324
```
325

326
## Performance Features
327

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

334
## Limitations
335

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