geolens (CLI)
Apache-2.0 command-line interface for the GeoLens API.
Login, scan local directories of spatial data, apply manifest-driven catalogs, publish vector or raster files, refresh remote service datasets, inspect source status, run PostGIS analysis operations, and export STAC metadata against any GeoLens instance.
See docs.getgeolens.com for the full command reference.
Quickstart
pip install geolens-cli
geolens login https://geolens.example.com/api
geolens scan ./data
geolens init
geolens validate geolens.yaml
geolens schema --output geolens-manifest-v1.schema.json
geolens apply --dry-run geolens.yaml
geolens apply geolens.yaml
geolens publish ./data/cities.geojson
geolens status <dataset-id>
geolens refresh <dataset-id> --wait
geolens analysis preview <dataset-id> --operation buffer --distance 500 > ring.geojson
geolens analysis materialize <dataset-id> --operation buffer --distance 500 --title "500 m ring" # waits for the job; --timeout to bound it
geolens export stac <dataset-id> -o cities.stac.json
For a one-command quickstart, run geolens publish examples/manifests/first-catalog/city-parks.geojson against a running stack. See the full walkthrough at docs.getgeolens.com.
The CLI consumes the geolens Python SDK package. Manifest apply posts to the generated POST /ingest/manifest/apply contract through the SDK-owned client transport rather than a hand-rolled HTTP client.
Apply versus refresh
geolens apply reconciles declared catalog configuration. It re-imports a
manifest entry only when that entry's fingerprint changes; applying an
unchanged manifest returns skip_complete and does not re-fetch a remote
source whose data changed independently.
geolens refresh <dataset-id> is the explicit data-refresh path. It re-pulls
the dataset from the origin binding stored by GeoLens, without accepting a URL,
layer, or client-selected trigger. Add --wait to poll the refresh job to a
terminal state without an implicit deadline; pass --timeout when automation
needs a finite bound. This is the supported command for scheduled cron or CI
refresh jobs; use apply when the declared source configuration itself changes.
Protected services can receive a transient credential with --token. Use bare
--token to open a hidden-input prompt, which keeps the value out of terminal
output and shell history. Supplying a token value directly is supported for
automation but can expose it through process arguments or shell history, so
inject it only through an appropriately protected runner. GeoLens never stores
the credential in the dataset binding.
geolens status <dataset-id> reports the catalog status together with source
origin, freshness, health, and the last successful refresh time. Use --json
before the command for a machine-readable status payload.
Manifest schema distribution
The versioned manifest JSON Schema is intentionally distributed inside
geolens-cli, rather than as a separate package. A second artifact would add a
release/version-skew surface without a demonstrated independent consumer; the
CLI is already the canonical manifest authoring and validation tool. Editors and
non-Python tooling can obtain the exact installed schema with geolens schema
or geolens schema -o schema.json. Its stable $id identifies manifest v1.
This decision should be revisited if multiple consumers need schema releases on a cadence independent from the CLI. Until then, schema changes and CLI versions ship atomically and the wheel test locks resource inclusion.
Environment variables
The CLI normally stores its active instance through geolens login and keeps
tokens in the OS keyring. Ephemeral CI jobs can avoid persistent state with:
| Variable | Purpose |
|---|---|
GEOLENS_INSTANCE |
GeoLens instance URL. The CLI normalizes the URL and appends /api when needed. An explicit --instance option takes precedence. |
GEOLENS_TOKEN |
Bearer token used instead of the keyring/credentials file. Treat it as a secret and inject it from the CI secret store. |
For load-test and seed-script variables, use the documented Tooling / Load
Tests section in the repository's .env.example.
1 maintainer
Metadata
1 maintainer
Release files for geolens-cli 1.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| geolens_cli-1.16.0.tar.gz | 85.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| geolens_cli-1.16.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 149.2 kB
Release files / geolens_cli-1.16.0.tar.gz
| Download URL | geolens_cli-1.16.0.tar.gz |
|---|---|
| Size | 85.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b391a3d26569ae8d27df07d828b3e2abd48e73cb0b576896b9387f1ed36dc680
|
|
BLAKE2b-256 checksum How to use checksums |
9bd90192047b8c09c0f20862fc32e5c3c7ad9824a6d31d3e573a0ec19ddb3afd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / geolens_cli-1.16.0-py3-none-any.whl
| Download URL | geolens_cli-1.16.0-py3-none-any.whl |
|---|---|
| Size | 64.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
099332467ff66484661c94062403a0ab78c103fcd2367cdbf4e4072e13d70e69
|
|
BLAKE2b-256 checksum How to use checksums |
8710b848f5e1a37fa371057a9254bfd4aff4bc411ea9d16a7b0e897932892df4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
