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.