0
# Command Line Options
1

2
Configuration options for the watchman binary, controlling daemon behavior, logging, and client-server interaction.
3

4
## Capabilities
5

6
### Socket and Connection Options
7

8
Control how Watchman communicates between client and daemon.
9

10
```bash { .api }
11
# Socket configuration
12
watchman -U <sockname>     # Use alternate socket path
13
watchman --sockname=<path> # Long form socket path option
14
```
15

16
**Default socket locations:**
17
- With `--enable-statedir`: `<STATEDIR>/$USER`
18
- Otherwise: `$TMPDIR/.watchman.$USER`
19

20
**Example:**
21
```bash
22
# Use custom socket location
23
watchman -U /var/run/watchman/custom.sock watch ~/project
24

25
# Connect to specific socket
26
watchman --sockname=/tmp/my-watchman.sock watch-list
27
```
28

29
### Logging Options
30

31
Configure log output and destination.
32

33
```bash { .api }
34
# Logging configuration
35
watchman -o <logfile>      # Specify log file path
36
watchman --logfile=<path>  # Long form log file option
37
```
38

39
**Default log locations:**
40
- With `--enable-statedir`: `<STATEDIR>/$USER.log`
41
- Otherwise: `$TMPDIR/.watchman.$USER.log`
42

43
**Example:**
44
```bash
45
# Custom log file
46
watchman -o /var/log/watchman.log -f
47

48
# Log to specific location
49
watchman --logfile=/home/user/watchman.log watch ~/project
50
```
51

52
### Daemon Control Options
53

54
Control daemon startup and execution mode.
55

56
```bash { .api }
57
# Daemon control
58
watchman -f                # Foreground mode (don't daemonize)
59
watchman --foreground      # Long form foreground option
60
watchman --no-spawn        # Don't spawn daemon if not running
61
```
62

63
**Foreground mode:**
64
- Runs daemon in current terminal
65
- Useful for debugging and development
66
- Outputs logs to terminal
67

68
**No-spawn mode:**
69
- Prevents automatic daemon startup
70
- Will try client-mode commands if possible
71
- Useful for testing daemon availability
72

73
**Example:**
74
```bash
75
# Run daemon in foreground for debugging
76
watchman -f
77

78
# Check if daemon is running without starting it
79
watchman --no-spawn watch-list
80
```
81

82
### State Management Options
83

84
Control state file usage and persistence.
85

86
```bash { .api }
87
# State management
88
watchman -n                    # Don't save state between invocations
89
watchman --no-save-state       # Long form no-save-state option
90
watchman --statefile=<path>    # Custom state file location
91
```
92

93
**State file behavior:**
94
- Persists watches and triggers across restarts
95
- Default location: `$TMPDIR/.watchman.$USER.state`
96
- Can be disabled with `-n` flag
97

98
**Example:**
99
```bash
100
# Disable state persistence
101
watchman -n watch ~/project
102

103
# Custom state file location
104
watchman --statefile=/var/lib/watchman/state watch ~/project
105
```
106

107
### Client Interaction Options
108

109
Control client behavior and output formatting.
110

111
```bash { .api }
112
# Client options
113
watchman -p                # Persistent mode for multiple commands
114
watchman --persistent      # Long form persistent option
115
watchman -j                # Read JSON command from stdin
116
watchman --json-command    # Long form JSON input option
117
watchman --no-pretty       # Don't pretty-print JSON output
118
```
119

120
**Persistent mode:**
121
- Keeps connection open for multiple commands
122
- Useful for interactive sessions
123
- Required for receiving subscription notifications
124

125
**JSON command mode:**
126
- Reads command from stdin as JSON array
127
- Enables complex commands with structured data
128
- Required for advanced queries and subscriptions
129

130
**Example:**
131
```bash
132
# Interactive persistent session
133
watchman --persistent log-level debug
134

135
# JSON command input
136
watchman -j <<-EOT
137
["query", "/home/user/project", {
138
  "expression": ["suffix", "js"],
139
  "fields": ["name"]
140
}]
141
EOT
142

143
# Compact JSON output
144
watchman --no-pretty watch-list
145
```
146

147
### Timing and Behavior Options
148

149
Control filesystem settling and other timing behavior.
150

151
```bash { .api }
152
# Timing options
153
watchman -s <milliseconds>  # Filesystem settle time
154
watchman --settle=<ms>      # Long form settle option
155
```
156

157
**Settle time:**
158
- How long to wait for filesystem to quiet down
159
- Default: 20 milliseconds  
160
- Prevents excessive trigger/notification activity
161
- Higher values reduce sensitivity to rapid changes
162

163
**Example:**
164
```bash
165
# Longer settle time for busy filesystems
166
watchman -s 100 watch ~/project
167

168
# Quick settle for responsive monitoring
169
watchman --settle=5 watch ~/development
170
```
171

172
## Usage Examples
173

174
### Development Setup
175

176
```bash
177
#!/bin/bash
178
# dev-watchman.sh - Development Watchman configuration
179

180
# Start Watchman in foreground with debug logging
181
watchman -f -o dev-watchman.log &
182
WATCHMAN_PID=$!
183

184
# Wait for daemon to start
185
sleep 2
186

187
# Set up watches with longer settle time for development
188
watchman -s 50 watch ~/my-project
189
watchman -s 50 watch ~/shared-lib
190

191
# Enable debug logging for development
192
watchman --persistent log-level debug &
193

194
# Cleanup on exit
195
trap "kill $WATCHMAN_PID" EXIT
196
```
197

198
### Production Configuration
199

200
```bash
201
#!/bin/bash
202
# prod-watchman.sh - Production Watchman setup
203

204
# Custom paths for production
205
SOCK_PATH="/var/run/watchman/production.sock"
206
LOG_PATH="/var/log/watchman/production.log"  
207
STATE_PATH="/var/lib/watchman/production.state"
208

209
# Start daemon with production settings
210
watchman \
211
  --sockname="$SOCK_PATH" \
212
  --logfile="$LOG_PATH" \
213
  --statefile="$STATE_PATH" \
214
  --settle=20 \
215
  watch /var/www/html
216

217
# Verify setup
218
watchman --sockname="$SOCK_PATH" watch-list
219
```
220

221
### Testing and Debugging
222

223
```bash
224
#!/bin/bash
225
# test-watchman.sh - Testing configuration
226

227
# Check if daemon is already running
228
if watchman --no-spawn watch-list > /dev/null 2>&1; then
229
    echo "Watchman daemon is running"
230
else
231
    echo "Starting Watchman daemon for testing"
232
    
233
    # Start in foreground for debugging
234
    watchman -f -n &  # No state saving for tests
235
    WATCHMAN_PID=$!
236
    
237
    # Wait for startup
238
    sleep 1
239
fi
240

241
# Run tests with compact output
242
watchman --no-pretty watch ~/test-project
243

244
# Cleanup
245
[ -n "$WATCHMAN_PID" ] && kill $WATCHMAN_PID
246
```
247

248
### Batch Processing
249

250
```bash
251
#!/bin/bash
252
# batch-queries.sh - Batch query processing
253

254
# Prepare JSON commands
255
COMMANDS=(
256
  '["watch", "/project1"]'
257
  '["watch", "/project2"]'  
258
  '["find", "/project1", "*.js"]'
259
  '["since", "/project2", "n:batch_cursor"]'
260
)
261

262
# Execute all commands in persistent session
263
{
264
    for cmd in "${COMMANDS[@]}"; do
265
        echo "$cmd"
266
    done
267
} | watchman -j --no-pretty --persistent
268
```
269

270
## Environment Variables
271

272
Watchman recognizes several environment variables:
273

274
### User and Temporary Directory
275
- `$USER` or `$LOGNAME`: Current user (for default paths)
276
- `$TMPDIR` or `$TMP`: Temporary directory (fallback to `/tmp`)
277

278
### Socket Override  
279
- `$WATCHMAN_SOCK`: Override default socket path
280

281
### Debugging
282
- `$WATCHMAN_LOG_LEVEL`: Set default log level (debug, info, warn, error)
283

284
**Example:**
285
```bash
286
# Override socket location via environment
287
export WATCHMAN_SOCK=/custom/path/watchman.sock
288
watchman watch ~/project
289

290
# Debug mode via environment
291
export WATCHMAN_LOG_LEVEL=debug
292
watchman -f
293
```
294

295
## Common Option Combinations
296

297
### Interactive Development
298
```bash
299
# Foreground with debug logging and custom settle time
300
watchman -f -s 100 --logfile=dev.log
301
```
302

303
### Production Daemon
304
```bash
305
# Background daemon with custom paths and state persistence
306
watchman --sockname=/var/run/watchman.sock --statefile=/var/lib/watchman.state
307
```
308

309
### Testing Mode
310
```bash
311
# No state, no spawn, compact output
312
watchman -n --no-spawn --no-pretty
313
```
314

315
### Batch Processing
316
```bash
317
# JSON input with persistent connection and compact output
318
watchman -j -p --no-pretty
319
```