0
# CLI Interface
1

2
Command-line interface with main command and subcommands for various linting operations. The CLI provides comprehensive control over linting behavior, configuration, and output formatting.
3

4
## Capabilities
5

6
### Main Command
7

8
Primary command for linting Solidity files with extensive configuration options.
9

10
```bash { .api }
11
solhint [options] <file> [...other_files]
12
```
13

14
**Options:**
15
- `-f, --formatter [name]` - Report formatter (stylish, table, tap, unix, json, compact, sarif)
16
- `-w, --max-warnings [number]` - Maximum number of allowed warnings
17
- `-c, --config [file_name]` - Configuration file to use
18
- `-q, --quiet` - Report errors only (suppress warnings)
19
- `--ignore-path [file_name]` - File to use as .solhintignore
20
- `--fix` - Automatically fix problems where possible
21
- `--cache` - Only lint files that changed since last run
22
- `--cache-location [file_name]` - Path to cache file
23
- `--noPrompt` - Skip confirmation prompt for fix operations
24
- `--init` - Create configuration file
25
- `--disc` - Skip update checking
26
- `--save` - Save report to timestamped file
27
- `--noPoster` - Remove Discord community banner
28

29
**Usage Examples:**
30

31
```bash
32
# Basic linting
33
solhint contracts/Token.sol
34

35
# Lint multiple files
36
solhint contracts/Token.sol contracts/Crowdsale.sol
37

38
# Use glob patterns
39
solhint 'contracts/**/*.sol'
40
solhint 'contracts/*.sol' 'test/*.sol'
41

42
# With configuration file
43
solhint -c .solhint-strict.json contracts/*.sol
44

45
# Different output formats
46
solhint -f json contracts/*.sol
47
solhint -f table contracts/*.sol > report.txt
48

49
# Auto-fix issues
50
solhint --fix contracts/*.sol
51

52
# Quiet mode (errors only)
53
solhint -q contracts/*.sol
54

55
# With caching for performance
56
solhint --cache contracts/**/*.sol
57

58
# Limit warnings
59
solhint -w 5 contracts/*.sol
60

61
# Save report to file
62
solhint --save contracts/*.sol
63
```
64

65
### Stdin Command
66

67
Process Solidity code from standard input for pipeline integration.
68

69
```bash { .api }
70
solhint stdin [--filename <name>]
71
```
72

73
**Options:**
74
- `--filename [file_name]` - Name of file for reporting purposes
75

76
**Usage Examples:**
77

78
```bash
79
# Process from stdin
80
echo "contract Test {}" | solhint stdin
81

82
# With filename for better error reporting
83
echo "contract Test {}" | solhint stdin --filename Test.sol
84

85
# From file via pipe
86
cat contracts/Token.sol | solhint stdin --filename Token.sol
87

88
# With formatting
89
cat contracts/Token.sol | solhint stdin -f json
90

91
# In build pipelines
92
curl -s https://example.com/contract.sol | solhint stdin --filename remote.sol
93
```
94

95
### Init Config Command
96

97
Create a default configuration file for the project.
98

99
```bash { .api }
100
solhint init-config
101
```
102

103
**Usage Examples:**
104

105
```bash
106
# Create default .solhint.json
107
solhint init-config
108

109
# Alternative syntax
110
solhint --init
111
```
112

113
**Generated Configuration:**
114
```json
115
{
116
  "extends": "solhint:recommended"
117
}
118
```
119

120
### List Rules Command
121

122
Display all rules covered by current configuration files.
123

124
```bash { .api }
125
solhint list-rules [-c <config_file>]
126
```
127

128
**Options:**
129
- `-c, --config [file_name]` - Configuration file to analyze
130

131
**Usage Examples:**
132

133
```bash
134
# List rules from default config
135
solhint list-rules
136

137
# List rules from specific config
138
solhint list-rules -c .solhint-strict.json
139
```
140

141
**Output Format:**
142
```
143
Configuration File: 
144
{
145
  "extends": "solhint:recommended",
146
  "rules": {
147
    "func-visibility": "error",
148
    "max-line-length": ["warn", 120]
149
  }
150
}
151

152
Rules: 
153
- avoid-call-value: error
154
- avoid-low-level-calls: error
155
- func-visibility: error
156
- max-line-length: ["warn", 120]
157
```
158

159
## Exit Codes
160

161
```bash { .api }
162
# Exit codes
163
0   # No errors found
164
1   # Linting errors found  
165
255 # Bad options or configuration errors
166
```
167

168
**Usage Examples:**
169

170
```bash
171
# Check exit code in scripts
172
if solhint contracts/*.sol; then
173
  echo "No errors found"
174
else
175
  echo "Linting failed with exit code $?"
176
fi
177

178
# In CI/CD pipelines
179
solhint contracts/*.sol || exit 1
180
```
181

182
## Configuration Options
183

184
### Formatter Selection
185

186
```bash
187
# Available formatters
188
solhint -f stylish contracts/*.sol    # Default, human-readable
189
solhint -f json contracts/*.sol       # Machine-readable JSON
190
solhint -f table contracts/*.sol      # Tabular format
191
solhint -f compact contracts/*.sol    # One-line per issue
192
solhint -f unix contracts/*.sol       # Editor-friendly format
193
solhint -f tap contracts/*.sol        # Test Anything Protocol
194
solhint -f sarif contracts/*.sol      # Security tools format
195
```
196

197
### Configuration File Selection
198

199
```bash
200
# Configuration file hierarchy (searched in order)
201
# 1. Command line: -c option
202
solhint -c custom-config.json contracts/*.sol
203

204
# 2. Project files (searched automatically)
205
# - package.json (solhint property)
206
# - .solhint.json
207
# - .solhintrc
208
# - .solhintrc.json
209
# - .solhintrc.yaml/.yml
210
# - .solhintrc.js
211
# - solhint.config.js
212
```
213

214
### Ignore Files
215

216
```bash
217
# Default ignore file
218
.solhintignore
219

220
# Custom ignore file
221
solhint --ignore-path .custom-ignore contracts/*.sol
222
```
223

224
**Ignore File Format:**
225
```
226
# Ignore patterns (one per line)
227
node_modules/
228
**/*.temp.sol
229
contracts/test/**
230
contracts/mocks/*
231
```
232

233
### Warning Limits
234

235
```bash
236
# Fail if more than 5 warnings
237
solhint -w 5 contracts/*.sol
238

239
# Allow unlimited warnings
240
solhint -w -1 contracts/*.sol
241

242
# No warnings allowed (fail on any warning)
243
solhint -w 0 contracts/*.sol
244
```
245

246
## Auto-fixing
247

248
### Fix Command Options
249

250
```bash
251
# Auto-fix with confirmation prompt
252
solhint --fix contracts/*.sol
253

254
# Auto-fix without prompt (dangerous)
255
solhint --fix --noPrompt contracts/*.sol
256
```
257

258
**Fixable Rules Examples:**
259
- `func-visibility` - Add missing visibility modifiers
260
- `var-name-mixedcase` - Fix variable naming
261
- `quotes` - Fix quote style consistency
262
- `visibility-modifier-order` - Reorder modifiers
263

264
**Safety Features:**
265
- Backup confirmation prompt by default
266
- Only applies safe, well-tested fixes
267
- Reports which fixes were applied
268
- Original issues marked as `[FIXED]` in output
269

270
### Fix Workflow
271

272
```bash
273
# 1. Review issues first
274
solhint contracts/*.sol
275

276
# 2. Apply fixes with confirmation
277
solhint --fix contracts/*.sol
278
# Prompts: "FIX option detected. Please BACKUP your contracts first. Continue? (y/n)"
279

280
# 3. Review changes
281
git diff
282

283
# 4. Run again to see remaining issues
284
solhint contracts/*.sol
285
```
286

287
## Caching
288

289
### Cache Options
290

291
```bash
292
# Enable caching for faster repeat runs
293
solhint --cache contracts/**/*.sol
294

295
# Custom cache location
296
solhint --cache --cache-location .custom-cache contracts/*.sol
297
```
298

299
**Cache Behavior:**
300
- Default location: `node_modules/.cache/solhint/.solhintcache.json`
301
- Caches results for files with no errors
302
- Considers file content hash and configuration hash
303
- Skips unchanged files on subsequent runs
304
- Automatically invalidated when files or config change
305

306
### Cache Management
307

308
```bash
309
# Clear cache (delete cache file)
310
rm node_modules/.cache/solhint/.solhintcache.json
311

312
# Disable caching temporarily
313
solhint --no-cache contracts/*.sol  # (not available, use config)
314
```
315

316
## Integration Examples
317

318
### Package.json Scripts
319

320
```json
321
{
322
  "scripts": {
323
    "lint": "solhint 'contracts/**/*.sol'",
324
    "lint:fix": "solhint --fix 'contracts/**/*.sol'",
325
    "lint:json": "solhint -f json 'contracts/**/*.sol'",
326
    "lint:ci": "solhint -f json 'contracts/**/*.sol' > lint-results.json"
327
  }
328
}
329
```
330

331
### Git Hooks
332

333
```bash
334
# .git/hooks/pre-commit
335
#!/bin/sh
336
echo "Running Solhint..."
337
solhint -q 'contracts/**/*.sol'
338
if [ $? -ne 0 ]; then
339
  echo "Linting failed. Commit aborted."
340
  exit 1
341
fi
342
```
343

344
### CI/CD Integration
345

346
```yaml
347
# GitHub Actions
348
- name: Run Solhint
349
  run: |
350
    solhint -f json 'contracts/**/*.sol' > lint-results.json
351
    
352
- name: Check Results  
353
  run: |
354
    if [ $(jq '.[] | .errorCount' lint-results.json | jq -s 'add') -gt 0 ]; then
355
      echo "Linting errors found"
356
      exit 1
357
    fi
358
```
359

360
### VS Code Integration
361

362
```json
363
// .vscode/tasks.json
364
{
365
  "version": "2.0.0",
366
  "tasks": [
367
    {
368
      "label": "solhint",
369
      "type": "shell", 
370
      "command": "solhint",
371
      "args": ["${file}"],
372
      "group": "build",
373
      "presentation": {
374
        "echo": true,
375
        "reveal": "always",
376
        "focus": false,
377
        "panel": "shared"
378
      },
379
      "problemMatcher": {
380
        "owner": "solhint",
381
        "fileLocation": "relative",
382
        "pattern": {
383
          "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error)\\s+(.*)\\s+([a-z-]+)$",
384
          "file": 1,
385
          "line": 2, 
386
          "column": 3,
387
          "severity": 4,
388
          "message": 5,
389
          "code": 6
390
        }
391
      }
392
    }
393
  ]
394
}
395
```
396

397
## Error Handling
398

399
### Common Error Scenarios
400

401
```bash
402
# Configuration file not found
403
solhint -c missing.json contracts/*.sol
404
# Exit code: 255
405

406
# No files match pattern
407
solhint 'nonexistent/**/*.sol'
408
# Exit code: 255
409

410
# Invalid formatter
411
solhint -f invalid-formatter contracts/*.sol  
412
# Exit code: 255
413

414
# Linting errors found
415
solhint contracts/*.sol  # (when errors exist)
416
# Exit code: 1
417
```
418

419
### Troubleshooting
420

421
```bash
422
# Verbose error information
423
DEBUG=solhint* solhint contracts/*.sol
424

425
# Check configuration loading
426
solhint list-rules
427

428
# Test with minimal config
429
echo '{"extends": "solhint:recommended"}' > .test-config.json
430
solhint -c .test-config.json contracts/*.sol
431
```