0
# Command Line Interface
1

2
CLI tool for running commands when files change, with support for throttling and various watch modes. Perfect for development workflows, build automation, and continuous testing.
3

4
## Capabilities
5

6
### Basic Command
7

8
The CLI watches a directory and executes a command whenever files change.
9

10
```bash { .api }
11
sane <command> [...directory] [options]
12
```
13

14
**Arguments:**
15
- `<command>` - Shell command to execute when files change (required)
16
- `[directory]` - Directory to watch (optional, defaults to current directory)
17

18
**Basic Examples:**
19

20
```bash
21
# Watch current directory, run tests on any change
22
sane 'npm test'
23

24
# Watch specific directory
25
sane 'npm run build' src/
26

27
# Run linter when JavaScript files change
28
sane 'eslint src/' --glob='**/*.js'
29
```
30

31
### Watch Options
32

33
Control which files are watched and how they're filtered.
34

35
```bash { .api }
36
--glob=<pattern>, -g    # Glob pattern(s) to watch
37
--ignored=<pattern>, -i # Pattern(s) to ignore
38
--dot, -d              # Watch dot files
39
```
40

41
**Examples:**
42

43
```bash
44
# Watch only CSS files
45
sane 'sass compile' --glob='**/*.scss'
46

47
# Watch multiple file types
48
sane 'npm run build' --glob='**/*.js' --glob='**/*.css'
49

50
# Ignore specific directories
51
sane 'npm test' --ignored='node_modules/**' --ignored='dist/**'
52

53
# Watch dot files (like .env files)
54
sane 'npm run env-check' --dot
55
```
56

57
### Watcher Mode Options
58

59
Choose the file watching strategy based on your environment.
60

61
```bash { .api }
62
--poll, -p                          # Use polling mode
63
--watchman                          # Use Watchman mode (note: -w conflicts with --wait)  
64
--watchman-path=<path>              # Custom Watchman binary path
65
```
66

67
**Examples:**
68

69
```bash
70
# Use polling (good for virtual environments)
71
sane 'npm test' --poll
72

73
# Use Watchman for large projects
74
sane 'npm run build' --watchman
75

76
# Custom Watchman path
77
sane 'npm test' --watchman --watchman-path=/usr/local/bin/watchman
78
```
79

80
### Execution Control Options
81

82
Control when and how the command executes.
83

84
```bash { .api }
85
--wait=<seconds>, -w    # Throttle command execution (note: -w conflicts with --watchman)
86
--only-changes, -o      # Run command only on changes (skip initial run)
87
--quiet, -q            # Disable console output
88
```
89

90
**Examples:**
91

92
```bash
93
# Wait 3 seconds between command executions
94
sane 'npm run build' --wait=3
95

96
# Only run on file changes, not at startup
97
sane 'npm test' --only-changes
98

99
# Suppress sane's output messages
100
sane 'npm run build' --quiet
101
```
102

103
## Usage Patterns
104

105
### Development Workflows
106

107
```bash
108
# Live reload development server
109
sane 'npm run dev' src/ --glob='**/*.js' --wait=1
110

111
# Auto-compile TypeScript
112
sane 'tsc' --glob='**/*.ts' --ignored='**/*.d.ts'
113

114
# Run tests on source changes
115
sane 'npm test' src/ test/ --glob='**/*.js' --only-changes
116
```
117

118
### Build Automation
119

120
```bash
121
# Rebuild CSS when SCSS changes
122
sane 'sass src/styles:dist/css' --glob='**/*.scss'
123

124
# Lint and format code
125
sane 'npm run lint && npm run format' --glob='**/*.js'
126

127
# Generate documentation
128
sane 'jsdoc src/' --glob='**/*.js' --wait=5
129
```
130

131
### File Processing
132

133
```bash
134
# Optimize images when added
135
sane 'imagemin src/images/* --out-dir=dist/images' --glob='**/*.{jpg,png,gif}'
136

137
# Copy assets to build directory
138
sane 'cp -r src/assets/* dist/' src/assets/ --wait=2
139

140
# Update translation files
141
sane 'i18n-extract' --glob='**/*.js' --ignored='**/*.spec.js'
142
```
143

144
## Command Output
145

146
The CLI provides informative output about its operations:
147

148
```bash
149
$ sane 'echo "Files changed!"' src/ --glob='**/*.js'
150
Watching: /path/to/project/src/**/*.js
151
ready
152
Change detected in: src/main.js
153
Files changed!
154
```
155

156
With `--quiet` flag:
157

158
```bash
159
$ sane 'echo "Files changed!"' --quiet
160
Files changed!
161
```
162

163
## Error Handling
164

165
The CLI handles various error conditions gracefully:
166

167
- **Invalid command**: Exits with helpful usage message
168
- **Directory not found**: Shows error and exits
169
- **Command execution failure**: Shows command error but continues watching
170
- **Watcher initialization failure**: Shows error and attempts fallback modes
171

172
## CLI Limitations
173

174
**Flag Conflict**: The CLI implementation has a bug where the `-w` flag is mapped to both `--wait` and `--watchman` options. When using `-w`, the last parsed option will take precedence. To avoid conflicts:
175
- Use full flag names: `--wait=3` and `--watchman`
176
- Or be aware that `-w` will activate both wait and watchman modes simultaneously
177

178
## Environment Integration
179

180
### Package.json Scripts
181

182
```json
183
{
184
  "scripts": {
185
    "watch": "sane 'npm run build' src/ --glob='**/*.js'",
186
    "watch:test": "sane 'npm test' --only-changes --quiet",
187
    "watch:scss": "sane 'sass compile' --glob='**/*.scss' --wait=1"
188
  }
189
}
190
```
191

192
### Makefile Integration
193

194
```makefile
195
watch:
196
	sane 'make build' src/ --glob='**/*.js'
197

198
watch-test:
199
	sane 'make test' --only-changes
200

201
.PHONY: watch watch-test
202
```
203

204
### Shell Aliases
205

206
```bash
207
# .bashrc or .zshrc
208
alias watch-js='sane "npm test" --glob="**/*.js" --only-changes'
209
alias watch-build='sane "npm run build" --wait=2'
210
```
211

212
## Advanced Usage
213

214
### Complex Commands
215

216
```bash
217
# Multiple commands with conditional logic
218
sane 'npm run lint && npm test && npm run build' --wait=3
219

220
# Using shell operators
221
sane 'npm test || echo "Tests failed!"' --only-changes
222

223
# Background processes
224
sane 'npm run build &' --wait=1
225
```
226

227
### Directory-Specific Watching
228

229
```bash
230
# Watch specific subdirectories
231
sane 'npm run build-components' src/components/ --glob='**/*.jsx'
232
sane 'npm run build-styles' src/styles/ --glob='**/*.scss'
233

234
# Multiple directory patterns
235
sane 'npm test' --glob='src/**/*.js' --glob='test/**/*.js'
236
```
237

238
### Integration with External Tools
239

240
```bash
241
# With Docker
242
sane 'docker-compose restart api' api/ --glob='**/*.js' --wait=5
243

244
# With PM2
245
sane 'pm2 restart app' --only-changes --quiet
246

247
# With systemd
248
sane 'sudo systemctl reload nginx' config/ --glob='**/*.conf' --wait=10
249
```