Command-Line Interface
WhiteboxTools is a command-line program and can be run either by calling it from a terminal application with appropriate commands and arguments, or, more conveniently, by calling it from a script. The following commands are recognized by the WhiteboxTools library:
| Command | Description |
|---|---|
| --cd, --wd | Changes the working directory; used in conjunction with --run flag. |
| -h, --help | Prints help information. |
| -l, --license | Prints the whitebox-tools license. |
| --listtools | Lists all available tools, with tool descriptions. Keywords may also be used, --listtools slope. |
| -r, --run | Runs a tool; used in conjunction with --cd flag; -r="LidarInfo". |
| --toolbox | Prints the toolbox associated with a tool; --toolbox=Slope. |
| --toolhelp | Prints the help associated with a tool; --toolhelp="LidarInfo". |
| --toolparameters | Prints the parameters (in json form) for a specific tool; e.g. --toolparameters="FeaturePreservingDenoise". |
| -v | Verbose mode. Without this flag, tool outputs will not be printed. |
| --viewcode | Opens the source code of a tool in a web browser; --viewcode="LidarInfo". |
| --version | Prints the version information. |
Generally, the Unix convention is that single-letter arguments (options) use a single hyphen (e.g. -h) while word-arguments (longer, more descriptive argument names) use double hyphens (e.g. --help). The same rule is used for passing arguments to tools as well. Use the --toolhelp argument to print information about a specific tool (e.g. --toolhelp=Clump).
Tool names can be specified either using the snake_case or CamelCase convention (e.g. lidar_info or LidarInfo).
The following is an example of calling the WhiteboxTools binary executable file directly from the command prompt:
>>./whitebox_tools --wd='/Users/johnlindsay/Documents/data/' ^
--run=DevFromMeanElev --input='DEM clipped.tif' ^
--output='DEV raster.tif' -v
Notice the quotation marks (single or double) used around directories and filenames, and string tool arguments in general. After the --run flag, used to call a tool, a series of tool-specific flags are provided to indicate the values of various input parameters. Note that the order of these flags is unimportant. Use the '-v' flag (run in verbose mode) to force the tool to print output to the command prompt. Please note that the whitebox_tools executable file must have permission to be executed; on some systems, this may require setting special permissions. Also, the above example uses the forward slash character (/), the directory path separator used on unix based systems. On Windows, users should use the back slash character (\) instead. Also, it is sometimes necessary to break (^) commands across multiple lines, as above, in order to better fit with the documents format. Actual command prompts (>>) should be contained to a single line.