0
# Command Line Interface
1

2
Comprehensive CLI tool for build processes, file watching, and batch compilation with extensive configuration options for development and production workflows.
3

4
## Capabilities
5

6
### Basic Usage
7

8
```bash { .api }
9
# Compile single file
10
node-sass input.scss output.css
11

12
# Compile with options
13
node-sass --output-style compressed --source-map true input.scss output.css
14

15
# Watch for changes
16
node-sass --watch --recursive src/ --output dist/
17

18
# Get help
19
node-sass --help
20

21
# Get version
22
node-sass --version
23
```
24

25
### Input/Output Options
26

27
Control how files are processed and where output is written.
28

29
```bash { .api }
30
# Input file (required unless using --data)
31
node-sass input.scss [output.css]
32

33
# Output directory (for --watch mode)
34
--output <dir>
35
-o <dir>
36

37
# Watch directory or file for changes
38
--watch
39
-w
40

41
# Recursively watch directories
42
--recursive
43
-r
44

45
# Read from stdin, write to stdout
46
echo "$primary: blue; .test { color: $primary; }" | node-sass --stdin
47

48
# Specify input as indented Sass syntax (not SCSS)
49
--indented-syntax
50
-i
51
```
52

53
**Usage Examples:**
54

55
```bash
56
# Basic file compilation
57
node-sass styles/main.scss dist/main.css
58

59
# Watch entire directory
60
node-sass --watch --recursive --output dist/ src/
61

62
# Process indented Sass
63
node-sass --indented-syntax styles/main.sass dist/main.css
64

65
# Pipe processing
66
cat input.scss | node-sass --stdin > output.css
67
```
68

69
### Output Style Options
70

71
Control the formatting and compression of generated CSS.
72

73
```bash { .api }
74
# CSS output style
75
--output-style <style>
76
# Values: nested (default), expanded, compact, compressed
77

78
# Indentation type for output
79
--indent-type <type>
80
# Values: space (default), tab
81

82
# Indentation width (max 10)
83
--indent-width <number>
84
# Default: 2
85

86
# Line ending style
87
--linefeed <style>
88
# Values: cr, crlf, lf (default), lfcr
89

90
# Decimal precision for numbers
91
--precision <number>
92
# Default: 5
93
```
94

95
**Usage Examples:**
96

97
```bash
98
# Production build with compression
99
node-sass --output-style compressed --precision 3 src/main.scss dist/main.css
100

101
# Development build with readable output
102
node-sass --output-style expanded --indent-type space --indent-width 4 src/main.scss dist/main.css
103

104
# Custom line endings for Windows
105
node-sass --linefeed crlf --output-style expanded src/main.scss dist/main.css
106
```
107

108
### Source Map Options
109

110
Generate and configure source maps for debugging.
111

112
```bash { .api }
113
# Generate source map
114
--source-map <true|false|path>
115

116
# Embed source contents in source map
117
--source-map-contents
118

119
# Embed source map as data URI in CSS
120
--source-map-embed
121

122
# Base path for source map URLs
123
--source-map-root <path>
124

125
# Omit source map URL comment from CSS
126
--omit-source-map-url
127
-x
128
```
129

130
**Usage Examples:**
131

132
```bash
133
# Generate source map file
134
node-sass --source-map true src/main.scss dist/main.css
135

136
# Custom source map location
137
node-sass --source-map dist/maps/main.css.map src/main.scss dist/main.css
138

139
# Inline source map
140
node-sass --source-map-embed src/main.scss dist/main.css
141

142
# Source map with embedded sources
143
node-sass --source-map true --source-map-contents src/main.scss dist/main.css
144
```
145

146
### Import and Path Options
147

148
Configure how @import statements are resolved.
149

150
```bash { .api }
151
# Additional paths for @import resolution
152
--include-path <path>
153
# Can be used multiple times
154

155
# Follow symlinked directories
156
--follow
157

158
# Environment variable: SASS_PATH
159
# Colon-separated list of import paths
160
export SASS_PATH="/usr/local/sass:/home/user/sass"
161
```
162

163
**Usage Examples:**
164

165
```bash
166
# Multiple include paths
167
node-sass --include-path node_modules --include-path src/styles src/main.scss dist/main.css
168

169
# Using environment variable
170
export SASS_PATH="node_modules:src/partials"
171
node-sass src/main.scss dist/main.css
172

173
# Follow symlinks in watch mode
174
node-sass --watch --follow --recursive src/ --output dist/
175
```
176

177
### Advanced Options
178

179
Extended functionality for debugging and customization.
180

181
```bash { .api }
182
# Include debug info in output
183
--source-comments
184

185
# Quiet mode - suppress output except errors
186
--quiet
187
-q
188

189
# Path to custom importer JavaScript file
190
--importer <path>
191

192
# Path to custom functions JavaScript file  
193
--functions <path>
194

195
# Ring bell on errors
196
--error-bell
197
```
198

199
**Usage Examples:**
200

201
```bash
202
# Debug build with comments
203
node-sass --source-comments --output-style expanded src/main.scss dist/main.css
204

205
# Quiet build process
206
node-sass --quiet --output-style compressed src/main.scss dist/main.css
207

208
# Custom functions and importers
209
node-sass --functions build/sass-functions.js --importer build/sass-importer.js src/main.scss dist/main.css
210
```
211

212
### Watch Mode
213

214
Automatic recompilation when source files change.
215

216
```bash { .api }
217
# Watch single file
218
node-sass --watch input.scss --output output.css
219

220
# Watch directory
221
node-sass --watch --recursive src/ --output dist/
222

223
# Watch with specific options
224
node-sass --watch --output-style compressed --source-map true src/ --output dist/
225
```
226

227
**Watch Mode Behavior:**
228

229
- Monitors source files and all imported dependencies
230
- Automatically recompiles when any dependency changes
231
- Outputs compilation status and timing information
232
- Continues running until manually stopped (Ctrl+C)
233
- Handles new files and deletions in watch directories
234
- Preserves file structure in output directory
235

236
**Usage Examples:**
237

238
```bash
239
# Development workflow
240
node-sass --watch --recursive --output-style expanded --source-map true src/styles/ --output public/css/
241

242
# Production watch
243
node-sass --watch --output-style compressed --quiet src/main.scss --output dist/main.css
244

245
# Watch with custom configuration
246
node-sass --watch --recursive --include-path node_modules --functions build/functions.js src/ --output dist/
247
```
248

249
### Custom Functions File
250

251
JavaScript file exporting custom Sass functions.
252

253
```javascript { .api }
254
// Example functions file (sass-functions.js)
255
module.exports = {
256
  // Function with variable arguments
257
  'double(...)': function(args, done) {
258
    const value = args.getValue(0);
259
    const doubled = new sass.types.Number(
260
      value.getValue() * 2,
261
      value.getUnit()
262
    );
263
    done(doubled);
264
  },
265
  
266
  // Function with named arguments
267
  'add-alpha($color, $alpha)': function(color, alpha, done) {
268
    const newColor = new sass.types.Color(
269
      color.getR(),
270
      color.getG(),
271
      color.getB(),
272
      alpha.getValue()
273
    );
274
    done(newColor);
275
  }
276
};
277
```
278

279
### Custom Importer File
280

281
JavaScript file exporting custom import resolution logic.
282

283
```javascript { .api }
284
// Example importer file (sass-importer.js)
285
module.exports = function(url, prev, done) {
286
  // Handle npm: imports
287
  if (url.startsWith('npm:')) {
288
    const packageName = url.slice(4);
289
    try {
290
      const packagePath = require.resolve(packageName);
291
      done({ file: packagePath });
292
    } catch (error) {
293
      done(new Error(`Package not found: ${packageName}`));
294
    }
295
  }
296
  // Handle other custom imports
297
  else if (url.startsWith('http://') || url.startsWith('https://')) {
298
    // Could fetch remote files
299
    done(new Error('Remote imports not supported'));
300
  }
301
  // Let Sass handle normal imports
302
  else {
303
    done(null);
304
  }
305
};
306
```
307

308
### Error Handling
309

310
CLI provides detailed error information for debugging.
311

312
```bash
313
# Error output includes:
314
# - Error message and description
315
# - File path and line/column numbers
316
# - Stack trace for JavaScript errors
317
# - Compilation context
318

319
# Exit codes:
320
# 0 - Success
321
# 1 - Compilation error
322
# 2 - Invalid arguments
323
# 3 - No input specified
324
```
325

326
**Example Error Output:**
327

328
```
329
Error: Invalid CSS after "  color: invalid-function(": expected expression (e.g. 1px, bold), was ")"
330
        on line 3 of src/main.scss
331
>>   color: invalid-function();
332
   ----------------------------^
333

334
Compilation failed in 15ms
335
```
336

337
### Configuration via package.json
338

339
CLI options can be specified in package.json scripts.
340

341
```json
342
{
343
  "scripts": {
344
    "sass:dev": "node-sass --watch --recursive --output-style expanded --source-map true src/styles/ --output public/css/",
345
    "sass:build": "node-sass --output-style compressed --source-map true src/styles/main.scss public/css/main.css",
346
    "sass:watch": "node-sass --watch --quiet --include-path node_modules src/main.scss --output dist/main.css"
347
  }
348
}
349
```