0
# CLI Interface
1

2
Complete command-line interface for file compilation, watching, CSS conversion, and build integration with options for compression, source maps, debugging, and plugin support.
3

4
## Capabilities
5

6
### Basic Commands
7

8
Core command-line operations for Stylus compilation.
9

10
```bash { .api }
11
# Compile single file to stdout
12
stylus input.styl
13

14
# Compile file to specific output
15
stylus input.styl -o output.css
16

17
# Compile multiple files
18
stylus styles/*.styl -o build/
19

20
# Compile directory
21
stylus src/ -o build/
22
```
23

24
### Watch Mode
25

26
Automatic recompilation when files change.
27

28
```bash { .api }
29
# Watch single file
30
stylus -w input.styl -o output.css
31

32
# Watch directory with compression
33
stylus -w -c src/ -o build/
34
```
35

36
### CSS Conversion
37

38
Convert existing CSS files to Stylus syntax.
39

40
```bash { .api }
41
# Convert CSS to Stylus (stdout)
42
stylus --css < input.css
43

44
# Convert CSS to Stylus file
45
stylus --css input.css output.styl
46

47
# Convert with custom indentation
48
stylus --css --indent="  " input.css output.styl
49
```
50

51
### Compilation Options
52

53
Control output format and optimization.
54

55
```bash { .api }
56
# Compress output CSS
57
stylus -c input.styl -o output.css
58

59
# Include line numbers in output
60
stylus -l input.styl -o output.css
61

62
# Include Firebug debug information
63
stylus -f input.styl -o output.css
64

65
# Generate source maps
66
stylus -m input.styl -o output.css
67

68
# Print compiled CSS to stdout
69
stylus -p input.styl
70

71
# Compare compiled output with existing file
72
stylus -d input.styl output.css
73
```
74

75
### Include Paths
76

77
Specify directories to search for @import files.
78

79
```bash { .api }
80
# Single include path
81
stylus -I ./styles input.styl
82

83
# Multiple include paths
84
stylus -I ./styles -I ./node_modules input.styl
85

86
# Include path with compilation
87
stylus -I ./mixins -c input.styl -o output.css
88
```
89

90
### Plugin Support
91

92
Use Stylus plugins for extended functionality.
93

94
```bash { .api }
95
# Use single plugin
96
stylus -u autoprefixer-stylus input.styl
97

98
# Use multiple plugins
99
stylus -u nib -u autoprefixer-stylus input.styl
100

101
# Plugin with compilation
102
stylus -u nib -c input.styl -o output.css
103
```
104

105
### URL Processing
106

107
Configure URL handling in imports and assets.
108

109
```bash { .api }
110
# Inline imported CSS files
111
stylus -U input.styl -o output.css
112

113
# Resolve relative URLs
114
stylus -r input.styl -o output.css
115

116
# Auto-prefix CSS properties
117
stylus -P input.styl -o output.css
118

119
# Auto-prefix with specific prefix
120
stylus -P webkit input.styl -o output.css
121
```
122

123
### Development Features
124

125
Tools for debugging and development workflow.
126

127
```bash { .api }
128
# Print file dependencies
129
stylus -s input.styl
130

131
# Include CSS imports in output
132
stylus --include-css input.styl -o output.css
133

134
# Set custom output extension
135
stylus --ext .min.css input.styl -o build/
136

137
# Set custom output extension for processed files
138
stylus --out-ext .processed.css src/ -o build/
139
```
140

141
### Information Commands
142

143
Get help and version information.
144

145
```bash { .api }
146
# Display help
147
stylus -h
148
stylus --help
149

150
# Display version
151
stylus -V
152
stylus --version
153
```
154

155
## Complete Option Reference
156

157
```bash { .api }
158
# All command-line options
159
stylus [options] [files...]
160

161
Options:
162
  -w, --watch                 Watch for changes and recompile
163
  -o, --out <dir>            Output directory or file
164
  -C, --css <src> [dest]     Convert CSS to Stylus syntax
165
  -I, --include <path>       Include path for @import statements
166
  -c, --compress             Compress output CSS
167
  -d, --compare              Compare compiled output with existing file
168
  -f, --firebug              Include Firebug debug information
169
  -l, --line-numbers         Include line numbers in output CSS
170
  -m, --sourcemap            Generate source map (.map file)
171
  -p, --print                Print compiled CSS to stdout
172
  -u, --use <plugin>         Use the given plugin
173
  -U, --inline               Inline imported CSS files
174
  -r, --resolve-url          Resolve relative URLs in imports
175
  -P, --prefix [prefix]      Auto-prefix CSS properties
176
  -s, --print-deps           Print file dependencies to stdout
177
  -h, --help                 Display help information
178
  -V, --version              Display version number
179
      --include-css          Include imported CSS in output
180
      --ext <extension>      Output file extension
181
      --out-ext <extension>  Output extension for processed files
182
      --indent <string>      Indentation string (for CSS conversion)
183
```
184

185
## Usage Examples
186

187
```bash
188
# Basic compilation workflow
189
stylus main.styl -o main.css
190

191
# Development with watch mode
192
stylus -w -l -f src/styles.styl -o public/css/styles.css
193

194
# Production build with compression and source maps
195
stylus -c -m src/*.styl -o build/css/
196

197
# Using plugins and includes
198
stylus -u nib -u autoprefixer-stylus -I ./mixins -I ./variables main.styl -o main.css
199

200
# CSS to Stylus conversion
201
stylus --css legacy-styles.css modern-styles.styl
202

203
# Print dependencies for build tools
204
stylus -s main.styl > dependencies.txt
205

206
# Compare output (useful for testing)
207
stylus -d main.styl expected-output.css
208

209
# Multi-file compilation with custom extensions
210
stylus --ext .min.css --compress src/*.styl -o build/
211

212
# Complex build pipeline
213
stylus -u nib -I ./node_modules -I ./styles -c -m -P webkit src/main.styl -o dist/styles.css
214
```
215

216
## Exit Codes
217

218
```bash { .api }
219
# Success
220
0    # Compilation successful
221

222
# Error codes
223
1    # General error (syntax error, file not found, etc.)
224
2    # Comparison failed (when using -d/--compare option)
225
```
226

227
## Integration Examples
228

229
### npm Scripts
230

231
```json
232
{
233
  "scripts": {
234
    "css": "stylus src/styles.styl -o public/css/styles.css",
235
    "css:watch": "stylus -w src/styles.styl -o public/css/styles.css",
236
    "css:build": "stylus -c -m src/styles.styl -o dist/styles.css",
237
    "css:deps": "stylus -s src/styles.styl"
238
  }
239
}
240
```
241

242
### Makefile
243

244
```makefile
245
CSS_SRC = src/styles.styl
246
CSS_OUT = public/css/styles.css
247

248
css:
249
	stylus $(CSS_SRC) -o $(CSS_OUT)
250

251
css-watch:
252
	stylus -w $(CSS_SRC) -o $(CSS_OUT)
253

254
css-build:
255
	stylus -c -m $(CSS_SRC) -o $(CSS_OUT)
256

257
css-deps:
258
	stylus -s $(CSS_SRC)
259
```
260

261
### Shell Scripts
262

263
```bash
264
#!/bin/bash
265
# Build script with error handling
266

267
set -e
268

269
echo "Building Stylus files..."
270

271
# Compile with plugins and includes
272
stylus -u nib -I ./styles -c src/main.styl -o dist/main.css
273

274
# Generate source map
275
stylus -m src/main.styl -o dist/main.css
276

277
# Print dependencies
278
echo "Dependencies:"
279
stylus -s src/main.styl
280

281
echo "Build complete!"
282
```