1--- 2pageid: cli-options 3title: Command Line 4layout: docs 5section: Invocation 6permalink: docs/cli-options.html 7--- 8 9The `watchman` executable contains both the client and the server components 10of the watchman service. 11 12By default, when `watchman` is run, it will attempt to communicate with your 13existing server instance (each user has their own persistent process), and will 14attempt to start it if it doesn't exist. 15 16There are some options that affect how `watchman` will locate the server, some 17options that affect only the client and some others that affect only the 18server. Since all of the options are understood by the same executable we've 19broken those out into sections of their own to make it clearer when they apply. 20 21## Quick note on default locations 22 23Watchman will prefer to resolve your user name from the `$USER` environmental 24variable, or `$LOGNAME` if `$USER` was not set. If neither are set watchman 25will look it up from the system using `getpwuid(getuid())`. When we refer to 26`<USER>` in this documentation we mean the result of this resolution. 27 28In some cases Watchman will need to create files in a temporary location. 29Watchman will resolve this temporary location by looking at the `$TMPDIR` 30environmental variable, or `$TMP` if `$TMPDIR` was not set. If neither are set 31watchman will use `/tmp`. When we refer to `<TMPDIR>` in this documentation we 32mean the result of this resolution. 33 34Watchman tracks its persistent state in a location that we refer to as the 35`<STATEDIR>` in this documentation. 36 37*Since 3.1.* 38 39The `STATEDIR` defaulted to `<PREFIX>/var/run/watchman`. You can change this 40default when you build watchman by using the configure option 41`--enable-statedir`. 42 43Earlier versions of Watchman didn't have a default statedir and would instead 44use the `<TMPDIR>` for this state. We switched away from that because some 45environments randomize the `<TMPDIR>` location and this made it difficult for 46clients to locate the Watchman service. 47 48*Since 3.8.* 49 50The `STATEDIR` defaults to `<PREFIX>/var/run/watchman/<USER>-state`. You can 51change this default when you build watchman by using the configure option 52`--enable-statedir`; the configure option replaces the 53`<PREFIX>/var/run/watchman` portion of this string. If you specify 54`--disable-statedir` then that portion of the string will be computed from the 55`<TMPDIR>` location. 56 57Watchman will create the `<USER>-state` portion if it does not exist, and will 58perform some permission and ownership checks to reduce the risk of untrusted 59users placing files in this location. If those checks are not satisfied, 60watchman will refuse to start. 61 62 63## Locating the service 64 65``` 66 -U, --sockname=PATH Specify alternate sockname 67``` 68 69The default location for sockname will be `<STATEDIR>/<USER>`. Older versions 70of Watchman would default to `<TMPDIR>/.watchman.<USER>`, depending on how 71it was configured. 72 73If you are building a client to access the service programmatically, we 74recommend that you invoke [watchman get-sockname]( 75/watchman/docs/cmd/get-sockname.html) to discover the path that the client and 76server would use. This has the side effect of spawning the service for you if 77it isn't already running. 78 79## Client Options 80 81The `watchman` executable will attempt to start the service if there is no 82response on the socket specified above. In some cases it is desirable to avoid 83starting the service if it isn't running: 84 85``` 86 --no-spawn Don't spawn service if it is not already running. 87 Will try running the command in client mode if 88 possible. 89 --no-local When no-spawn is enabled, don't use client mode 90``` 91 92Client mode implements the [watchman find command]( 93/watchman/docs/cmd/find.html) as an immediate search. 94 95These options control how the client talks to the server: 96 97``` 98 -p, --persistent Persist and wait for further responses 99 --server-encoding=ARG CLI<->server encoding. json or bser. 100``` 101 102Persistent connections have relatively limited use with the CLI, but can be 103useful to connect ad-hoc to the service to receive logging information (See 104[log-level](/watchman/docs/cmd/log-level.html)). 105 106The server encoding option controls how requests and responses are formatted 107when talking to the server. You generally shouldn't need to worry about this. 108 109### Input and Output 110 111Most simple invocations of the CLI will pass a list of arguments: 112 113```bash 114$ watchman watch /path/to/dir 115``` 116 117This is turned into a request like this: 118 119```json 120["watch", "/path/to/dir"] 121``` 122 123and sent to the service using the [Socket Interface]( 124/watchman/docs/socket-interface.html). 125 126The response is received and then sent to the `stdout` stream formatted based on 127the selected output-encoding: 128 129``` 130 --output-encoding=ARG CLI output encoding. json (default) or bser 131 --no-pretty Don't pretty print JSON output (more efficient 132 when being processed by another program) 133``` 134 135Each command has its own response output but watchman will always include a 136field named `error` if something about the request was not successful. In case 137of some protocol level errors (eg: connection was terminated) instead of 138printing a response on `stdout`, an unstructured error message will be printed 139to `stderr` and the process will exit with a non-zero exit status. 140 141Instead of passing the request as command line parameters, you can send a JSON 142representation on the `stdin` stream. These invocations are all equivalent: 143 144```bash 145$ watchman watch /path/to/dir 146``` 147 148```bash 149$ watchman -j <<-EOT 150["watch", "/path/to/dir"] 151EOT 152``` 153 154```bash 155$ watchman -j <<< '["watch", "/path/to/dir"]' 156``` 157 158```bash 159$ echo '["watch", "/path/to/dir"]' | watchman -j 160``` 161 162```bash 163$ echo '["watch", "/path/to/dir"]' > cmd.json 164$ watchman -j < cmd.json 165``` 166 167```bash 168$ watchman --json-command <<-EOT 169["watch", "/path/to/dir"] 170EOT 171``` 172 173*Since 3.8* 174 175The CLI now also recognizes BSER as a valid input stream when using the `-j` 176option. This will implicitly set `--server-encoding=bser` and 177`--output-encoding=bser` if those options have not been set to something else. 178 179## Exit Status 180 181The `watchman` binary will exit with a return code of 0 in most cases; this 182indicates that the output it generated should be valid JSON. To determine if 183your command was successful, you need to parse the JSON and look for the 184`error` field as described above. 185 186`watchman` will exit with a non-zero exit status in cases where something 187low-level went wrong, such as protocol level errors (eg: connection was 188terminated). 189 190## Server Options 191 192These options are used when starting the server. They are recognized by the 193client and affect how it will start the server, but have no effect if the 194server is already running. To change the effective values of these options 195for a running server, you will need to restart it (you can stop it by running 196[watchman shutdown-server](/watchman/docs/cmd/shutdown-server.html)). 197 198By default, watchman will remember all watches and associated triggers and 199reinstate them if the process is restarted. This state is stored in the 200*statefile*: 201 202``` 203 --statefile=PATH Specify path to file to hold watch and trigger state 204 -n, --no-save-state Don't save state between invocations 205``` 206 207The default location for statefile will be `<STATEDIR>/<USER>.state`. Older 208versions of watchman may store the state in `<TMPDIR>/.watchman.<USER>.state`, 209depending on how they were configured. 210 211``` 212-o, --logfile=PATH Specify path to logfile 213 --log-level set log verbosity (0 = off, default is 1, verbose = 2) 214``` 215 216The default location for logfile will be `<STATEDIR>/<USER>.log`. Older 217versions of watchman may store the logs in `<TMPDIR>/.watchman.<USER>.log`, 218depending on how they were configured. 219 220In some relatively uncommon circumstances, such as in test harnesses, you may 221need to directly run the service without it putting itself into the background: 222 223``` 224 -f, --foreground Run the service in the foreground 225``` 226 227*Since 4.6.* 228 229``` 230 --inetd Spawning from an inetd style supervisor 231``` 232 233When this flag is specified, watchman will use stdin as the listening socket 234rather than attempting to set it up for itself. This allows some other process 235to maintain the socket and defer activating the watchman service until a client 236is ready to connect. This is most practically beneficial when used together 237with `systemd`. 238 239[This commit includes a sample configuration for systemd](https://github.com/facebook/watchman/commit/2985377eaf8c8538b28fae9add061b67991a87c2). 240