Skip to content

Interacting with WhiteboxTools through the command line prompt

At its base, WhiteboxTools is a stand-alone executable command-line program. The Python scripting interface is effectively just interacting with this executable file through a series of process calls and reading the standard output. You can also interact directly with the WhiteboxTools executable file.

The following material has been extracted from the WhiteboxTools User Manual, which can be found in pdf form along with the download.

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:

--cd, --wdChanges the working directory; used in conjunction with --run flag.
-h, --helpPrints help information.
-l, --licensePrints the whitebox-tools license.
--listtoolsLists all available tools, with tool descriptions. Keywords may also be used, --listtools slope.
-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;
--toolparametersPrints the parameters (in json form) for a specific tool; e.g.
-vVerbose mode. Without this flag, tool outputs will not be printed.
--viewcodeOpens the source code of a tool in a web browser;
--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 any 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.

WhiteboxTools logo

Contact Information

Dr. John Lindsay
Rm. 346 Hutt Building
Department Geography, Environment & Geomatics
University of Guelph
50 Stone Rd. East
Guelph, ON, Canada, N1G 2W1

Phone: 519-824-4120 ext. 56074
Find me: LinkedIn, ResearchGate.

Recent News

No recent updates.