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:

CommandDescription
--cd, --wdChanges the working directory; used in conjunction with --run flag.
--compress_rastersSets the compress_raster option in the settings.json file; determines if newly created rasters are compressed. e.g. --compress_rasters=true
-h, --helpPrints help information.
-l, --licensePrints the whitebox-tools license.
--listtoolsLists all available tools, with tool descriptions. Keywords may also be used, --listtools slope.
--max_procsSets the maximum number of processors used. -1 = all available processors. e.g. --max_procs=2
-r, --runRuns a tool; used in conjunction with --cd flag; -r="LidarInfo".
--toolboxPrints the toolbox associated with a tool; --toolbox=Slope.
--toolhelpPrints the help associated with a tool; --toolhelp="LidarInfo".
--toolparametersPrints the parameters (in json form) for a specific tool; e.g. --toolparameters="FeaturePreservingDenoise".
-vVerbose mode. With this flag set to false, tool outputs will not be printed. -v=true, -v=false
--viewcodeOpens the source code of a tool in a web browser; --viewcode="LidarInfo".
--versionPrints 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.