---
name: geodms-run
description: Install GeoDMS and drive GeoDmsRun.exe, its headless calculation engine. Use for running a GeoDMS configuration, forcing and verifying calculation, printing statistics, dumping the configuration tree, explaining a single value, listing storage dependencies, and interpreting exit codes. Foundation for every GeoDMS task skill.
---

# Run GeoDMS headlessly with GeoDmsRun

`GeoDmsRun.exe` calculates items of a `.dms` configuration without a user interface and reports through streams, a log file and the process exit code. Everything below is specified in the [GeoDMS Run guide](https://github.com/ObjectVision/GeoDMS/wiki/User-Guide-GeoDMS-Run) and the [command-line reference](https://github.com/ObjectVision/GeoDMS/wiki/Command-line-options); this skill is the working summary. Report what was actually run and verified, never a prepared-but-unexecuted configuration as a result.

## Locate or install GeoDMS

Prefer an installation the user already has: `%ProgramFiles%\ObjectVision\GeoDms<version>.<flavour>\GeoDmsRun.exe`, version and build flavour readable from the directory name. Otherwise install from [official releases](https://github.com/ObjectVision/GeoDMS/releases) per the [installation instructions](https://github.com/ObjectVision/GeoDMS/wiki/Installation-Instructions); the Windows setups are standard NSIS installers, so `GeoDms<version>.<flavour>-Setup-x64.exe /S` from an elevated shell installs unattended (an optional `/D=<dir>` must be the last argument, unquoted). Keep the executable and the libraries it ships with together; never mix files of two releases. Record the version used with every result.

## Command-line contract

```
GeoDmsRun.exe [/L<LogFile>] [/S<X> /C<X> ...] <ConfigFile.dms> [<Item>|@<command> ...]
```

- `/L<log>` must be the very first argument, glued to an absolute path. The log **appends** on reuse; filter on today's date or use a fresh file.
- Set threading explicitly (`/S1 /S2 /S3`) so the run does not depend on the interactive user's registry settings. Options come before the configuration file; everything is processed left to right.
- Item paths are relative to the configuration root; the top-level container's name is not part of the path (`container foo { export { … } }` → `/export`). Naming a container calculates its whole subtree.
- In PowerShell, quote every `@…` argument (`'@statistics'`): a bare `@name` is the splatting operator and disappears silently, turning the command into a plain commit.

## Force, inspect and diagnose

A bare item is committed: calculated and written to its configured storage. An item **without** a writable storage can complete at metadata level without computing data, so force evaluation with `@statistics` or an `IntegrityCheck` item that depends on the result. The `@` commands (each applies to the items that follow it):

- `@statistics` — compute and print count, min, max, sum, mean, sd, #nulls; the fast way to verify data without rewriting a storage.
- `@dumpconfig <file>` — write the loaded configuration back out, `.dms` or `.xml` by extension. Use it to discover the item tree, resolved expressions and template/function instantiations without a GUI.
- `@valueinfo <row>` — print the value-explanation page (HTML) for one element of the items that follow: why a value is what it is, in particular why it is null.
- `@sourcedescr <item>` — print which storages an item is read from or written to; lists the file dependencies of a result before deploying or after a doubtful run.
- `@checkfunctions` — type-check every function definition in the configuration, including unreferenced ones; a CI-style gate.
- `@file <path>` — redirect subsequent report output to a file.

## Exit codes — always check them

| code | meaning |
|---|---|
| 0 | success |
| 1 | an item was not found or failed to compute — including, since GeoDMS 20.20.0, the item of a `@statistics`/`@valueinfo` request; the reason is on stderr as `Failure: …` |
| 2 | configuration unreadable, no arguments, unknown option, or an exception while updating |
| 3 | unexpected termination; the log ends with a `FATAL:` block (Release builds since 20.18.0) |
| -1073741819 | access violation; report it |

A zero exit plus an error-free log still does not establish a valid export: reopen the written file and check CRS, feature count and identifiers against the source.

## Deliver

State the GeoDMS version, the exact command lines, the `LocalDataDir` line GeoDmsRun prints first, the exit codes observed, and which outputs were verified by reopening them. Distinguish explicitly between work that ran and configurations that were only prepared.