CLI Reference

All GeoEngine commands follow the form geoengine <command> [options]. Run any command with --help to see its usage inline.

Authentication

Sign in to GeoEngine with your Nika account. Credentials are stored securely on your machine and persist across sessions. Required before using any other command.

geoengine auth login

`geoengine auth logout`

Sign out and remove stored credentials.

geoengine auth logout

`geoengine auth status`

Reads logged in user’s details.

geoengine auth status

Worker Setup

`geoengine init`

Create a new geoengine.yaml and pixi.toml template in the current directory. Also generates .dockerignore, Dockerfile, and geoengine.lock which should not be touched.

geoengine init [--name <worker>] [--env py|r]

Flag	Description
`--name <worker>`	Worker name. Defaults to the current directory name if omitted.
`--env py`	Generate a Python environment template (default).
`--env r`	Generate an R environment template.

`geoengine apply`

Register the worker, save config, generate a Dockerfile, build the Docker image, and manage GIS plugins — all in one step.

geoengine apply [<worker>] [--dev] [--no-cache] [--build-arg KEY=VALUE]

Flag	Description
`<worker>`	Worker name or path. Defaults to the worker in the current directory.
`--dev`	Skip semantic version validation; tag the image as `latest` only; do not save a config snapshot.
`--no-cache`	Force a full Docker rebuild, bypassing the layer cache.
`--build-arg KEY=VALUE`	Pass a custom Docker build argument into the image build.

What apply does:

Validates geoengine.yaml
Generates a Dockerfile from pixi.toml (if one doesn’t already exist)
Builds the Docker image (skipped automatically if config and image are unchanged)
Registers the worker if new
Saves a config snapshot (production mode only)
Installs or updates GIS plugins based on the plugins section

See Creating a Worker and Versioning Workers for full details.

Running Workers

`geoengine run`

Execute a worker in a Docker container. File and folder inputs are auto-mounted.

geoengine run [<worker-uuid>] --input KEY=VALUE [--input KEY=VALUE ...] [--json] [--ver <version>] [-- <extra args>]

Flag	Description
`<worker-uuid>`	Worker UUID. Defaults to the worker in the current directory (via `geoengine.lock`).
`--input KEY=VALUE`	Pass an input to the worker. Repeat for multiple inputs. File/folder paths are auto-mounted into the container.
`--json`	Structured output mode: container logs go to stderr, a JSON result is printed to stdout on completion.
`--ver <version>`	Run a specific previously-built version using its snapshotted config. Defaults to `latest`.
`-- <extra args>`	Pass additional arguments directly to the container command (after the trailing `--`).

Input mounting:

file inputs are mounted at /inputs/<key>/<filename>
folder inputs are mounted at /mnt/input_<key>/
Non-path values are passed through as plain string arguments

JSON result format (with --json):

{
  "status": "completed",
  "exit_code": 0,
  "files": [
    { "name": "output.geojson", "path": "/path/on/host", "size": 1024, "kind": "output" }
  ]
}

Publishing Workers

`geoengine push`

Publish a previously-applied production worker image to the cloud registry, making it available for team members to run via the QGIS or ArcGIS Pro plugin without a local setup.

geoengine push [--uuid <worker-uuid>] [--ver <version>] [--tenant <tenant>]

Flag	Description
`--uuid <worker-uuid>`	Worker to push. Defaults to the worker in the current directory (via `geoengine.lock`).
`--ver <version>`	Version to push. Defaults to the highest numbered version available locally.
`--tenant <tenant>`	Tenant to publish under. Defaults to your owned tenant.

Requires a prior production geoengine apply (without --dev). See Cloud Push for the full workflow.

Inspecting Workers

`geoengine workers`

List all registered workers.

geoengine workers [--all] [--json] [--gis arcgis|qgis]

Flag	Description
`--all`	Expand all version sub-rows inline below each worker.
`--json`	Output as JSON (includes `uuid`, `name`, `has_tool`, `description`).
`--gis arcgis\|qgis`	List only workers registered in the specified GIS plugin.

Output columns (default): UUID, NAME, LATEST APPLIED, LAST APPLIED, LATEST PUSHED, TEAM, QGIS, ARCGIS

LATEST APPLIED — highest applied semver version plus the number of available versions, e.g. 1.0.7 (7)
LAST APPLIED — relative time since last apply (e.g. 3 min 42 s ago)
LATEST PUSHED — highest pushed version for the displayed tenant plus that tenant’s pushed-version count
TEAM — tenant name for the displayed push history

With --all, the columns change to UUID, NAME, VERSION, LAST APPLIED, PUSHED, TEAM, QGIS, ARCGIS — expanding each worker with sub-rows for every version.

`geoengine describe`

Show detailed information about a specific worker.

geoengine describe [<worker-uuid>] [--ver <version>] [--json]

Flag	Description
`<worker-uuid>`	Worker UUID. Defaults to the worker in the current directory (via `geoengine.lock`).
`--ver <version>`	Show info for a specific version snapshot instead of the latest.
`--json`	Output as JSON (includes `name`, `description`, `version`, `inputs`, `applied_at`, `available_versions`, `config_hash`, `plugins_qgis`, `plugins_arcgis`).

`geoengine diff`

Check which tracked files have changed since the last apply.

geoengine diff [--file all|config|dockerfile|worker]

Flag	Description
`--file all`	Check all tracked files (default).
`--file config`	Check only `geoengine.yaml`.
`--file dockerfile`	Check only the `Dockerfile`.
`--file worker`	Check only the worker script directory.

Managing Workers

`geoengine delete`

Delete a worker or a specific version.

geoengine delete [--uuid <worker-uuid>] [--ver <version>]

Flag	Description
`--uuid <worker-uuid>`	Worker to delete. Defaults to the worker in the current directory (via `geoengine.lock`).
`--ver <version>`	Delete only this version (removes its Docker image, map entry, and config snapshot). Omit to delete the entire worker.

Running without --ver shows a confirmation prompt before deleting the worker’s registration, all saved configs, and all state.

Image Management

`geoengine image list`

List all GeoEngine-managed Docker images.

geoengine image list

`geoengine image import`

Import a Docker image from a tarball (useful for air-gapped environments).

geoengine image import <file.tar> --tag <name:tag>

`geoengine image remove`

Remove a Docker image and its associated version entry and config snapshot.

geoengine image remove <image:tag>

Environment Variables

Global environment variables are injected into every worker container at runtime.

`geoengine env set`

Set one or more global environment variables.

geoengine env set KEY=value
geoengine env set KEY="value with spaces"
geoengine env set KEY1=val1 KEY2=val2
geoengine env set -f path/to/.env   # Load from a .env file

Inline variables override file variables if both are provided in the same command.

`geoengine env unset`

Remove one or more global environment variables.

geoengine env unset KEY
geoengine env unset KEY1 KEY2

`geoengine env list`

List all currently set global environment variables.

geoengine env list

`geoengine env show`

Show the value of a single global environment variable.

geoengine env show KEY

Maintenance & Updates

`geoengine patch`

Validate all GeoEngine artifacts and repair anything that is broken or out of date. Safe to run at any time; exits with a non-zero status if issues are found.

geoengine patch

Run this after upgrading GeoEngine to sync workers, GIS plugins, and agent skills with the new binary.

geoengine patch --init   # Interactive — select which AI agents to install skills for

`geoengine update`

Update GeoEngine to the latest version using the original install method (Homebrew, curl, or PowerShell), then automatically run geoengine patch.

geoengine update

`geoengine uninstall`

Remove the GeoEngine binary and GeoEngine files.

geoengine uninstall

Quick Reference

Command	Description
`geoengine auth login\|logout\|status`	Authentication-related commands, to login, logout, and see user details
`geoengine init [--name] [--env py\|r]`	Create GeoEngine-required worker artifacts
`geoengine apply [--dev] [--no-cache] [--build-arg K=V]`	Register, build image, and install GIS plugins
`geoengine push [--uuid <uuid>] [--ver V] [--tenant T]`	Publish a production image to the cloud registry
`geoengine run [<worker-uuid>] --input K=V [--json] [--ver V]`	Run a worker in a container (UUID or current directory)
`geoengine diff [--file all\|config\|dockerfile\|worker]`	Check tracked file changes since last apply
`geoengine workers [--all] [--json] [--gis arcgis\|qgis]`	List registered workers
`geoengine describe [<worker-uuid>] [--ver V] [--json]`	Show worker details and config hash
`geoengine delete [--uuid <worker-uuid>] [--ver V]`	Delete a worker or a single version
`geoengine image list\|import\|remove`	Manage Docker images
`geoengine env set\|unset\|list\|show`	Manage global environment variables
`geoengine patch [--init]`	Repair artifacts and sync plugins/agent skills
`geoengine update`	Update to latest version, then run patch
`geoengine uninstall`	Remove GeoEngine binary and data

Tutorials

Access Control

File Storage

Map Visualization

Data Analysis

Database Management

Data Conversion Pipeline

Image Labeling

Field Survey

Custom Geoprocess Deployment

Best Practices

​Authentication

​geoengine auth login

​geoengine auth logout

​geoengine auth status

​Worker Setup

​geoengine init

​geoengine apply

​Running Workers

​geoengine run

​Publishing Workers

​geoengine push

​Inspecting Workers

​geoengine workers

​geoengine describe

​geoengine diff

​Managing Workers

​geoengine delete

​Image Management

​geoengine image list

​geoengine image import

​geoengine image remove

​Environment Variables

​geoengine env set

​geoengine env unset

​geoengine env list

​geoengine env show

​Maintenance & Updates

​geoengine patch

​geoengine update

​geoengine uninstall

​Quick Reference