Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nikaplanet.com/llms.txt

Use this file to discover all available pages before exploring further.

GeoEngine provides a set of CLI commands to inspect workers, read container logs, and repair broken state. This guide covers the most common debugging scenarios.

​
Check What Has Changed

Before re-applying a worker, use geoengine diff to see which tracked files have changed since the last apply: 
# Check tracked files: geoengine.yaml, Dockerfile, and build-relevant worker files
geoengine diff
This is useful for confirming which changes will be picked up when you run geoengine apply next.

​
Inspect Registered Workers

List all registered workers and their current status: 
# Summary view
geoengine workers

# Expanded view — shows all versions as sub-rows beneath each worker
geoengine workers --all
The output table includes the following columns:
ColumnDescription
IDWorker UUID used by the CLI and Docker tags
NAMEWorker name
LATEST TAGMost recently applied local tag plus the total number of applied tags, e.g. claude-1.0.0 (3)
LAST APPLIEDRelative time since last apply (e.g. 3 min 42 s ago)
If a worker is missing from this list after geoengine apply, run geoengine patch to repair the worker registry (see below).

​
Inspect a Specific Worker

Get detailed information about a single worker: 
# Show the latest applied version, config hash, and available versions list
geoengine describe

# Show info for a specific previously-built tag
geoengine describe --tag claude-1.0.0
The output includes:
  • Name and description
  • Version and applied at timestamp
  • Config hash — a SHA-256 of the applied config; useful to confirm two builds used the same configuration
  • Applied tags — all local tags currently on disk for this worker
  • Runtime image — the base runtime image used when the tag was applied, when available

​
Read Container Logs

Container logs stream to stderr automatically when you run a worker. To separate logs from the structured result, use --json mode: 
geoengine run --actor CLI --json --input input-file=/path/to/file.tif
  • stderr — container log output, streamed in real time
  • stdout — the final JSON result, printed on completion:
{
  "job_id": "01HX4V2Z9B2F4T8H6P9K3N7Q1M",
  "status": "completed",
  "exit_code": 0,
  "files": [
    {
      "name": "output.geojson",
      "path": "/path/to/output/file",
      "size": 1024,
      "kind": "output"
    }
  ]
}
A non-zero exit_code means the container script exited with an error. Check stderr for the Python/R traceback.

​
Inspect Run History

Every geoengine run is saved locally by default, with metadata and compressed streamed logs under ~/.geoengine/runs/<worker_id>/<job_id>/. Use the job_id from the JSON result to inspect the run later: 
geoengine worker runs show <job-id> --json
geoengine worker runs logs <job-id> --stream stderr --tail 100
Use geoengine run --no-history for sensitive or ephemeral runs that should not be written to local history.

​
Debug Worker Tests

If geoengine test fails, rerun the failing case with logs and keep the output folder: 
geoengine test --case <case-name> --verbose --keep-workdir
Inspect .geoengine-test/<case-name>/ to confirm what the worker actually wrote. If the output is correct but the comparison failed, update the expected file, tolerance, or ignored JSON paths in tests/geoengine.test.yaml.

​
Force a Clean Rebuild

If your Docker image is stale or a dependency change isn’t being picked up, force a full rebuild with --no-cache: 
geoengine apply --no-cache
This bypasses Docker’s layer cache and rebuilds the image from scratch. Use it when:
  • You’ve updated a package version in pixi.toml but the old version is still being used
  • The image is in an inconsistent state after a failed build
  • You want to confirm the image builds cleanly from the current config

​
Repair GeoEngine Artifacts

geoengine patch performs a maintenance sweep and repairs any broken state across all GeoEngine-managed artifacts: 
geoengine patch
Run this after upgrading GeoEngine, or whenever workers, plugins, or agent skills are behaving unexpectedly. It checks and repairs:
  • Global registry (~/.geoengine/settings.bin) — validates the settings file
  • Worker state files — validates state/*.json, reports orphaned records
  • Config snapshots — validates saves/<worker>/map.json, checks all referenced snapshots exist
  • GIS plugins — reinstalls stale or missing plugin files for QGIS and ArcGIS Pro
  • Agent skills — syncs skill files into each installed agent’s skills folder; files with matching SHA-256 hashes are skipped
geoengine patch exits with a non-zero status if any validation issue is found, making it safe to use in scripts.

​
Delete a Worker or Version

If a worker is in a broken state and needs to be removed: 
# Delete a worker entirely by ID (shows a confirmation prompt)
geoengine delete --id <worker-id>

# Delete the worker in the current directory
geoengine delete

# Delete a specific tag only (removes image, mapping, and snapshot)
geoengine delete --tag claude-1.0.0
After deleting, re-apply the worker with geoengine apply to recreate it cleanly.

​
Common Issues

​
Build fails: command.script not found

Make sure the script path in geoengine.yaml is relative to the worker directory and the file actually exists there.

​
geoengine apply rejects my version number

In production mode, the version in geoengine.yaml must be a valid semantic version (MAJOR.MINOR.PATCH) and must be greater than or equal to the highest version already recorded. Use geoengine apply --dev to skip this check during development.

​
Worker appears in geoengine workers but not in QGIS/ArcGIS

Run geoengine patch to reinstall any stale plugin files, then close and reopen the GIS Processing Toolbox to refresh the worker list.

​
Dependency changes not reflected after apply

Run geoengine apply --no-cache to force a full Docker rebuild. Docker may be using a cached layer that predates your pixi.toml changes.