Command line reference

Everything Terraflux does in its window it can also do from the command line: run a model, check it, run fifty replicates, calibrate a setting, or send a batch to a cluster. You type a command, press Enter, and Terraflux works without opening a window. The command line is how you run a model on a server, repeat an analysis exactly, or let a script run many of them in turn.

This reference is written for people who rarely use a terminal. It starts with how to open one and how a command is written; the next pages go through the commands by what they are for:

Page	Commands
Running models	`run`, `check`, `test`, `reproduce`, `new`, `methods`, `convert`, `ops`, `resample`, `app`
Batches: replicates, scenarios, calibration	`submit`, `calibrate`, `jobs`, `results`
Many machines	`serve`, `worker`, `workers`, `cluster`, `cloud-init`
The model's document	`report` (the document as an HTML page or a PDF)
AI assistants	`mcp`
Environment and files	the environment variables and where Terraflux keeps its files

Open a terminal#

WindowsmacOSLinux

Press Win, type PowerShell and open it. The Windows installer puts terraflux on the PATH, the list of folders where Windows looks for programs, so the command works from any folder once a new terminal is opened after the installation.

Open Terminal (Applications, Utilities). The command lives inside the application; link it once so that terraflux works anywhere:

ln -s /Applications/Terraflux.app/Contents/MacOS/terraflux /usr/local/bin/terraflux

Open your distribution's terminal (often Ctrl+Alt+T). The .deb package puts the command in /usr/bin; the archive's install.sh links it into ~/.local/bin.

Check that it works:

> terraflux --version
terraflux 1.41.0

If the terminal answers that it does not know the command, open a new terminal (the PATH is read when a terminal starts), or use the full path to the program.

How a command is written#

A command is the program's name, a command saying what to do, then arguments and options:

terraflux  run  model.toml  --out results  --set seed=7
   │        │       │            │              │
 program command argument      option       option with a value

An argument is what the command works on, here the model file. It has no name; its place says what it is.
An option starts with -- (or - and one letter, its short form: -o is --out). Some take a value after a space; others are switches, on when they are written (--quiet).
Options can come in any order after the command.
A path with spaces needs quotes: terraflux run "My models/forest.toml".
Paths are relative to the folder the terminal is in. cd changes it: cd C:\Users\me\project on Windows, cd ~/project elsewhere.

Every command explains itself with --help, and those explanations are what this reference shows in grey boxes:

terraflux --help          # the commands
terraflux run --help      # the options of run
terraflux cluster add --help

The commands#

Land use and land cover change modelling

Usage: terraflux [OPTIONS] [COMMAND]

Commands:
  app          Open the application (with a model, if given)
  run          Run a model and write its outputs
  check        Check a model and its data without running it
  reproduce    Run again what a run's manifest (manifest.json, written with its outputs) records: the same model, scenario, values and files (told when one changed), and tell whether every output is the same, byte for byte (vectors: the same features)
  test         Test models: run each (a folder: its models) and check what its [[tests]] say against the files of what they should be, and its check.assert nodes; `--update` writes those files from this run instead
  report       Write a model as a document: its data, preparation, model, validation and results, step by step, with the note, why and settings of each (an HTML page, or a PDF by the extension)
  plot         Run a model and write one of its Plots (`[[plots]]`, kept with the model) as a picture of its map: the layers at their opacity, the features with their style and labels, as the Viewer draws it (no legend or decorations)
  methods      Draft the methods section of a paper from a model: the methods it uses with the papers to cite, the model step by step and the references; or the references as BibTeX or RIS
  ops          List the operators (`--json`: their full signatures)
  new          Create a model from a classic land change model
  convert      Write a model in another format (by the extension: .toml or .json)
  mcp          A server of the Model Context Protocol on the standard input and output: an AI assistant (Claude, Gemini CLI, Codex...) builds, checks and runs models through it; the application, with the model open, shows its edits as they are made
  serve        Run a coordinator: workers ask it for tasks, clients submit batches to it
  worker       Run a headless worker: tasks from a coordinator, until stopped
  workers      The workers of a coordinator and what they do
  jobs         The jobs of a coordinator, done or not
  results      Follow a job of a coordinator to its end and write its files (those written already kept)
  submit       Run a batch of a model: replicates (one seed each) or scenarios, here or on a coordinator's workers
  calibrate    Calibrate settings of a model against an observed map, here or on a coordinator's workers
  sensitivity  A global sensitivity analysis of a model's output to its settings (Morris or Sobol, as SALib), here or on a coordinator's workers
  cluster      Clusters and servers reached by SSH: saved once, used by `submit --on`, `calibrate --on`, `results --on`
  cloud-init   The setup script (cloud-init user data) of a machine rented in the cloud: a server with Terraflux (then `terraflux cluster add`), or, with --worker, a machine working for a server's coordinator
  resample     Resample a raster to the grid of another (of the same coordinate reference system)
  help         Print this message or the help of the given subcommand(s)

Options:
      --threads <THREADS>  Threads to use (default and most: a quarter of the cores left free; never every core)
  -h, --help               Print help
  -V, --version            Print version

Options every command takes#

--threads N: How many threads Terraflux may use. By default it uses all the cores of the computer but one, so the machine stays usable; it never takes every core unless you ask. The environment variable TERRAFLUX_THREADS sets the same for every command (see Environment and files).
-h, --help: The command's help.
-V, --version: The version of Terraflux (with terraflux alone: terraflux --version).

Running terraflux with no command, or double-clicking the program, opens the application.

When something goes wrong#

Terraflux says what failed, where, and why, then stops with a non-zero exit code (so a script can tell that it failed). The most common messages:

The system cannot find the path specified / No such file or directory: A path in the command or in the model does not exist from where Terraflux looks. Paths inside a model are relative to the model file's folder; paths on the command line are relative to the terminal's folder.
TOML parse error ... missing field 'format': The file is not a Terraflux model, or its first line format = "terraflux/1" is missing.
unknown operator: A node names an operator that does not exist in this version; terraflux ops lists them all.

Before running a long model, terraflux check model.toml finds most problems in a fraction of a second: every operator, every connection between nodes and every input file is checked without running anything. After a change to a model, terraflux test tells whether it still gives what it gave before (see Running models).

Going further#

The model file the commands read: Your first model and Building models.
Running many models at once, on many machines: the guide to parallel and distributed computing.