CLI & Manifests

The GeoLens CLI (geolens) is the fastest way to get data into an instance from a terminal or CI pipeline. It wraps the Python SDK to publish single files, scan directories, export STAC metadata, and apply declarative manifests (geolens.yaml) that describe a whole catalog.

Install

Isolated install

Prefer pipx for a CLI you can run anywhere without touching your project's virtualenv.

pip install geolens-cli      # installs the `geolens` command
# or, for an isolated tool install:
pipx install geolens-cli

Verify the install:

geolens --version
geolens --help

Authenticate

Log in to an instance and store credentials. The instance URL is the API base — include the /api suffix:

geolens login http://localhost:8080/api
# prompts for username and password (admin / admin on a fresh install)

By default the bearer token is stored in your operating system keyring. Pass --no-keyring to fall back to a credentials.toml file instead (useful on headless hosts without a keyring service):

geolens login https://geolens.example.com/api --no-keyring

You can also store a token or API key non-interactively — handy for scripts:

geolens login https://geolens.example.com/api --token "$JWT"
geolens login https://geolens.example.com/api --api-key "$GEOLENS_API_KEY"

Check who you are, or clear credentials:

geolens whoami     # prints the active user and instance
geolens logout     # removes stored credentials for the active instance

Credential & instance precedence

For non-interactive use (CI especially), you can skip geolens login entirely and pass everything through the environment:

• Instance: --instance <url> flag → GEOLENS_INSTANCE env → the instance saved by geolens login.
• Token: stored credentials (keyring / credentials.toml) → GEOLENS_TOKEN env.

export GEOLENS_INSTANCE=https://geolens.example.com/api
export GEOLENS_TOKEN=...   # a JWT from POST /api/auth/login
geolens whoami

Publish a single file

geolens publish uploads one local vector or raster file and runs the full ingest flow (upload → preview → commit), then prints the new dataset’s URL:

geolens publish ./city-parks.geojson --name "City Parks"
geolens publish ./elevation.tif --name "Elevation" --description "10m DEM"

By default the command waits for ingestion to resolve the dataset id. Use --no-wait to return immediately with a job-search URL instead:

geolens publish ./big-raster.tif --no-wait

Commit is not idempotent

Re-running publish on a file that already committed prints “already committed” and exits non-zero. To re-ingest, delete the existing dataset first, or use a manifest with a stable key for idempotent updates.

Scan a directory

geolens scan walks a directory and reports what would be ingested — a dry run with no upload. Use it to preview a bulk import:

geolens scan ./gis-exports
geolens scan ./gis-exports --include-ext .gpkg,.tif --max-depth 2
geolens scan ./gis-exports --json        # machine-readable output

Manifests: repeatable catalogs

For multi-dataset catalogs that you want to version and re-apply, describe your sources in a geolens.yaml manifest and apply it declaratively.

geolens init                 # scaffold ./geolens.yaml
geolens validate geolens.yaml  # local schema check — no API call
geolens apply geolens.yaml     # validate + apply via the GeoLens API
geolens apply geolens.yaml --dry-run   # preview apply outcomes without writes

Each dataset carries a stable key, so re-applying an edited manifest updates the matching datasets instead of creating duplicates.

`apply` references sources — it does not upload

geolens apply sends the manifest to the server, which resolves each source by its URI — an HTTP(S) URL, a cloud storage URI (s3://, gs://, az://, abfs://), or a path already staged on the server. It does not upload files from your machine.

To publish a local file, use geolens publish instead.

Manifest schema (v1)

The top level requires manifest_version: "1", a catalog block, and a non-empty datasets array.

catalog — required title; optional description, organization, and a contact object (name, email, url).

datasets[]

Field	Required	Notes
key	Yes	Stable identity for idempotent apply. Lowercase a–z 0–9 . _ -, up to 128 chars.
title	Yes	Human-readable dataset title.
description	No	Longer description.
sources	Yes	One or more source objects (below).
metadata	No	Tags, CRS, license, bbox (below).
publication	Yes	Publication intent (below).

sources[]

Field	Required	Notes
type	Yes	One of vector, raster_cog, vrt.
uri	Yes	Relative path, https://, or s3:// / gs:// / az:// / abfs:// URI.
format	No	Driver hint, e.g. geojson, gpkg.
layer	No	Layer name for multi-layer sources.
title / description	No	Per-source overrides.

metadata (all optional) — tags (string array), organization, crs (EPSG:NNNN), license, attribution, bbox ([minx, miny, maxx, maxy] in WGS84).

publication — required intent, one of draft, ready, internal, published.

Example manifest

manifest_version: "1"
catalog:
  title: Regional Open Data
  description: Public datasets published by the Regional Data Office.
  organization: Regional Open Data Office
datasets:
  - key: regional-trails
    title: Regional trails
    description: Recreational trail network.
    sources:
      - type: vector
        uri: https://data.example.com/trails.geojson
        format: geojson
    metadata:
      tags: [trails, recreation]
      crs: EPSG:4326
      license: CC-BY-4.0
      attribution: Regional Open Data Office
      bbox: [-78.0, 38.0, -76.5, 39.5]
    publication:
      intent: ready

Export STAC metadata

Export STAC API 1.0 item metadata for a raster dataset (vector datasets are rejected with a clear message):

geolens export stac <dataset_id>              # pretty JSON to stdout
geolens export stac <dataset_id> -o item.json # write to a file
geolens export stac <dataset_id> --compact    # single line, for piping to jq

CI integration

The CLI is built for pipelines — authenticate via environment variables, validate locally, then apply. Every command accepts --json for machine-readable output and returns a non-zero exit code on failure.

export GEOLENS_INSTANCE=https://geolens.example.com/api
export GEOLENS_TOKEN=${{ secrets.GEOLENS_TOKEN }}

geolens validate geolens.yaml          # fails the build on schema errors
geolens apply geolens.yaml --json      # apply and emit a JSON report

Global options

These apply to every command:

Flag	Effect
--instance <url>	Override the active instance for this command.
--json	Machine-readable JSON output.
-v, --verbose	Debug logging to stderr.
-q, --quiet	Suppress non-error output.
--version	Print the CLI version and exit.