0
# CLI Usage
1

2
The sass-lint command-line interface provides comprehensive linting capabilities for Sass and SCSS files with extensive configuration options and output formatting.
3

4
## Capabilities
5

6
### Basic Command
7

8
Execute sass-lint with file patterns to analyze Sass/SCSS files.
9

10
```bash { .api }
11
sass-lint [options] <pattern>
12
```
13

14
**Parameters:**
15
- `pattern` (optional) - Glob pattern or file path to lint. If omitted, uses config file patterns
16

17
### Command Options
18

19
Configure sass-lint behavior through command-line options.
20

21
```bash { .api }
22
# Configuration
23
-c, --config [path]          # Path to custom config file
24
-i, --ignore [pattern]       # Pattern to ignore files (comma-separated for multiple)
25

26
# Output Control  
27
-v, --verbose               # Enable verbose output
28
-f, --format [format]       # Output format (uses ESLint formatters)
29
-o, --output [output]       # Write output to file path
30

31
# Behavior Control
32
-q, --no-exit              # Do not exit with error code on failures
33
-s, --syntax [syntax]      # Force syntax type (sass or scss)
34
--max-warnings [integer]   # Maximum warnings before exit code 1
35
```
36

37
**Available Formats:**
38
- `stylish` (default) - Human-readable format with colors
39
- `compact` - Compact single-line format
40
- `json` - JSON formatted output
41
- `junit` - JUnit XML format
42
- `checkstyle` - Checkstyle XML format
43
- `tap` - TAP (Test Anything Protocol) format
44
- `unix` - Unix-style format
45

46
**Usage Examples:**
47

48
```bash
49
# Basic linting with verbose output
50
sass-lint '**/*.scss' -v
51

52
# Use custom config file
53
sass-lint -c .sass-lint.yml 'src/**/*.scss'
54

55
# Multiple ignore patterns
56
sass-lint -i 'vendor/**, node_modules/**' 'src/**/*.scss'
57

58
# JSON output to file
59
sass-lint -f json -o results.json 'src/**/*.scss'
60

61
# Force SCSS syntax and limit warnings
62
sass-lint -s scss --max-warnings 10 'src/**/*.css'
63

64
# No exit on errors (useful in CI)
65
sass-lint -q 'src/**/*.scss'
66
```
67

68
### Exit Codes
69

70
sass-lint uses standard exit codes to indicate results.
71

72
```bash { .api }
73
# Exit Code Meanings
74
0  # Success - no errors found
75
1  # Failure - errors found or max warnings exceeded
76
```
77

78
### Configuration Priority
79

80
Command-line options override configuration file settings in this priority order:
81

82
1. Command-line options (highest priority)
83
2. Configuration file (`.sass-lint.yml`, `.sasslintrc`)
84
3. package.json `sasslintConfig` property
85
4. Default configuration (lowest priority)
86

87
### File Pattern Examples
88

89
```bash
90
# Single file
91
sass-lint styles.scss
92

93
# All SCSS files in directory
94
sass-lint '**/*.scss'
95

96
# Multiple patterns (space-separated)
97
sass-lint 'src/**/*.scss' 'components/**/*.sass'
98

99
# Specific directories
100
sass-lint 'src/' 'components/'
101

102
# Mixed file types
103
sass-lint '**/*.{scss,sass}'
104
```
105

106
### Integration Examples
107

108
```bash
109
# CI/CD Integration
110
sass-lint '**/*.scss' -f json -o lint-results.json || exit 1
111

112
# Pre-commit Hook
113
sass-lint '**/*.scss' -q && echo "Sass lint passed"
114

115
# Build Script Integration
116
sass-lint 'src/**/*.scss' --max-warnings 0 -f compact
117

118
# Watch Mode (with external tools)
119
chokidar '**/*.scss' -c 'sass-lint {path}'
120
```
121

122
### Error Handling
123

124
```bash { .api }
125
# Common Exit Scenarios
126
sass-lint files...          # Exit 1 if errors found
127
sass-lint -q files...       # Never exit with error code
128
sass-lint --max-warnings 0  # Exit 1 if any warnings found
129
sass-lint --max-warnings 5  # Exit 1 if >5 warnings found
130
```
131

132
### Configuration File Discovery
133

134
sass-lint automatically discovers configuration files in this order:
135

136
1. Path specified by `-c/--config` option
137
2. `.sass-lint.yml` in current directory or parent directories
138
3. `.sasslintrc` in current directory or parent directories  
139
4. `sasslintConfig` property in package.json
140
5. Default built-in configuration
141

142
### Output Examples
143

144
**Stylish Format (Default):**
145
```
146
src/components/button.scss
147
  12:3  error  Expected single space after ':'  space-after-colon
148
  15:1  warning  Rule declaration should be followed by an empty line  empty-line-between-blocks
149

150
✖ 2 problems (1 error, 1 warning)
151
```
152

153
**JSON Format:**
154
```json
155
[
156
  {
157
    "filePath": "src/components/button.scss",
158
    "messages": [
159
      {
160
        "ruleId": "space-after-colon",
161
        "severity": 2,
162
        "message": "Expected single space after ':'",
163
        "line": 12,
164
        "column": 3
165
      }
166
    ],
167
    "errorCount": 1,
168
    "warningCount": 0
169
  }
170
]
171
```
172

173
**Compact Format:**
174
```
175
src/components/button.scss: line 12, col 3, Error - Expected single space after ':' (space-after-colon)
176
```