CLI & Manifests
Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.
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, refresh, replace and inspect datasets, run analysis
operations, export STAC metadata, apply declarative manifests
(geolens.yaml) that describe a whole catalog, migrate an ArcGIS organization,
and create users in bulk.
Install
Section titled “Install”pip install geolens-cli # installs the `geolens` command# or, for an isolated tool install:pipx install geolens-cligeolens-cli requires Python 3.11 or newer.
Verify the install:
geolens --versiongeolens --helpTo run a command without installing anything, uvx fetches the package on
demand:
uvx --from geolens-cli geolens --versionPin the version in automation (uvx --from geolens-cli==<version> geolens ...).
The examples repo
keeps the pinned form of the manifest commands on this page, next to a
working manifest and GitHub Actions workflow.
Authenticate
Section titled “Authenticate”Log in to an instance and store credentials. The CLI talks to the API base
and appends /api itself when you leave it off, so
https://geolens.example.com and https://geolens.example.com/api resolve to
the same stored credential — the examples here spell the suffix out:
geolens login http://localhost:8080/api# prompts for your admin username and password (auto-generated at install; see your .env)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-keyringYou 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"# pass `-` to read the secret from stdin (keeps it out of argv / shell history):echo "$JWT" | geolens login https://geolens.example.com/api --token ---token and --api-key are mutually exclusive; pass only one.
Check who you are, or clear credentials:
geolens whoami # prints the active user and instancegeolens logout # removes stored credentials for the active instancePublish a single file
Section titled “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-waitRefresh a dataset
Section titled “Refresh a dataset”geolens refresh <dataset_id> re-pulls a dataset from its server-stored source
binding — the same manual refresh as the dataset page, for datasets with an
upstream to re-pull (Service, registered PostGIS table, STAC):
geolens refresh <dataset_id> # queue the job and returngeolens refresh <dataset_id> --wait # follow it to a terminal stategeolens refresh <dataset_id> --wait --timeout 600 # bound the waitUnlike publish, refresh does not wait by default. --timeout takes
seconds (finite, greater than 0) and requires --wait; without it, --wait
follows the job however long it queues.
For a protected service, pass --token with no value to get a hidden prompt:
geolens refresh <dataset_id> --tokenAn explicit --token <value> can be visible in argv and shell history. The
token is used for that refresh only — GeoLens never stores it on the dataset,
so each refresh of a protected service needs it again.
Verified refresh
Section titled “Verified refresh”Service refreshes verify the source feature count against the number of features fetched before publishing the replacement. A mismatch rejects the run and leaves the current dataset serving. The same gate blocks a refresh when the source count is unavailable, the replacement is empty, or columns were removed or retyped. These runs are recorded as blocked for review.
--accept-blocked-run is a one-time acceptance. It applies only when the next
fetch has the same source, attributes, and geometries as the reviewed result.
It cannot approve a different result or a later source change. Matching counts
still do not prove that a mutable provider served every page from one snapshot.
Use --auth-file with a protected JSON file for a source bearer token, Basic
credential, or named header. It is mutually exclusive with --token. With
--wait and global --json, the CLI waits for the durable run and emits its
terminal result as JSON:
geolens --json refresh <dataset_id> --auth-file ./source-auth.json --waitgeolens --json refresh <dataset_id> --auth-file ./source-auth.json --wait \ --accept-blocked-run <run_id>The durable run remains in refresh history after the background job is purged, so automation can retain the run id and terminal status.
Replace a dataset’s data
Section titled “Replace a dataset’s data”geolens replace <dataset-id> <file> uploads a local file over an existing
dataset’s data — the CLI equivalent of the web app’s Re-Upload dialog:
geolens replace <dataset_id> ./city-parks-2026.geojsongeolens replace <dataset_id> ./parcels.gpkg --layer parcels_currentgeolens replace <dataset_id> ./elevation.tif --waitIt runs the same upload, preview, commit flow as publish, pointed at the
dataset’s reupload endpoints: uploads the file, prints the preview (detected
layer, feature count, SRID), and prompts for confirmation before committing.
From 1.19.1 the preview refuses a file with no geometry over a dataset that
stores geometry, with a message saying nothing was changed and to import the
file as a new dataset; a Parquet file over the ingest ceiling gets the ceiling
message there too, rather than being reported as malformed.
--layer picks a layer out of a multi-layer file — required when the file
has more than one, since the CLI refuses to commit an unnamed default.
--srid overrides the detected SRID. From 1.19.1 it must be an EPSG code
the instance knows: a code that neither PROJ nor PostGIS has is refused at
commit with a message naming it, and nothing is queued. --wait polls the
replace job to a terminal state and exits non-zero on failure; without it, the
command returns once the job is queued. --yes/-y skips the confirmation
prompt, and is required together with --json, which never prompts. --yes
does not acknowledge review reasons: with --wait, a replacement that needs
review (for example, a removed column) still stops as a blocked run, and the CLI
prints the geolens refresh <id> --accept-blocked-run <run_id> command and
exits 6. Confirming at the prompt does acknowledge them.
replace refuses a dataset whose data comes from a service, a STAC item, or
a registered PostGIS table — replacing those with a file would sever the
binding that keeps them refreshable. Use geolens refresh
for those instead.
After a successful file replacement or service refresh of a vector dataset,
GeoLens keeps the replaced table as a previous version. It keeps the last three
by default; an admin sets the number under
Settings > Storage.
POST /api/datasets/{id}/previous-versions/{version_number}/restore publishes
one again. Registered PostGIS refreshes, partitioned tables, rasters, mosaics,
tilesets and point clouds keep no previous version, so getting their earlier
data back takes a backup or a re-import.
Inspect a dataset
Section titled “Inspect a dataset”geolens status <dataset_id> prints a dataset’s catalog status alongside its
source origin, freshness, health, and last refresh:
geolens status <dataset_id>geolens --json status <dataset_id> # machine-readable payloadScan a directory
Section titled “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-exportsgeolens scan ./gis-exports --include-ext .gpkg,.tif --max-depth 2geolens scan ./gis-exports --json # machine-readable outputscan classifies by file extension only. It recognizes GeoJSON, GeoPackage,
FlatGeobuf, KML, KMZ, GeoParquet (.parquet), shapefiles (grouped with their
sidecars, and flagged when .dbf or .shx is missing), and GeoTIFF, and reports everything else
as unsupported — except
orphaned sidecars (a stray .prj, .dbf, .shx, .cpg, .tfw and the like
with no dataset beside them), which it skips without a row. A .json
file counts as GeoJSON only if its first kilobyte looks like one. Read the
report as an inventory of the obvious candidates, not a capability check — its
extension list and the server’s upload allowlist are not the same list, as
Bulk import spells out.
Bulk import
Section titled “Bulk import”There is no bulk-upload command. geolens publish takes exactly one file, and
geolens apply never uploads from your
machine. The supported way to import a directory of local files is a shell loop
over publish:
for f in ./gis-exports/*.geojson ./gis-exports/*.gpkg; do [ -e "$f" ] || continue name=$(basename "$f") geolens publish "$f" --name "${name%.*}" || exit 1doneEach iteration runs the whole ingest flow for that one file — upload, preview,
commit — so 40 files means 40 uploads and 40 ingest jobs queued on the server.
Keep the default --wait and the loop stays serialized instead of flooding the
queue; --tags and --collection require it anyway, since both are applied
after the commit resolves the dataset id.
publish is not idempotent, so re-running the loop publishes a second copy of
every file. Track what succeeded, or delete the earlier datasets first.
Manifests: repeatable catalogs
Section titled “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 (errors if it already exists)geolens init --force # overwrite an existing manifestgeolens init catalog.yaml # scaffold at a custom pathgeolens validate geolens.yaml # local schema check, no API callgeolens apply geolens.yaml # validate + apply via the GeoLens APIgeolens apply geolens.yaml --dry-run # preview apply outcomes without writesEach dataset carries a stable key, so re-applying an edited manifest updates
the matching datasets instead of creating duplicates. The server matches each
entry to an existing dataset by key and fingerprints the rest, then answers
create (new key), update (known key, changed entry), or skip (unchanged
entry) per dataset. An unchanged manifest is therefore safe to apply on every
push. --dry-run returns the same verdicts without writing, but the server
evaluates it, so it needs a credential like a real apply.
Apply reconciles the declaration rather than the bytes behind it: a source URL
that serves new content under an unchanged entry still skips.
geolens refresh <dataset_id> is the manual refresh from
the dataset page, for datasets with an upstream to re-pull (Service, registered
PostGIS table, STAC). A source the server downloaded for a manifest is an
ordinary upload once ingested, so refresh refuses it. See Where Your Data Lives.
geolens apply --wait follows each queued job to its end. The result table
gains a STATUS column (complete, failed, blocked, cancelled or timed_out), and
with --json each result gains final_status and run_id.
An update that removes or retypes a column, or otherwise needs review, ends
blocked. Applying that entry again unchanged does not queue it a second time:
the entry comes back blocked with the run to accept and its reasons, apply
prints geolens refresh <dataset_id> --accept-blocked-run <run_id>, and the
exit code is 6. A changed entry is queued as usual.
Manifest schema (v1)
Section titled “Manifest schema (v1)”The top level requires manifest_version: "1", a catalog block, and a
datasets array of 1 to 100 entries. Split a larger catalog across several
manifests.
Print the packaged JSON Schema for geolens.yaml — for editor validation or
CI schema checks — without contacting an API:
geolens schema # print to stdoutgeolens schema -o geolens.schema.json # write to a filecatalog: required title; optional description, organization, and a
contact object (name, email, url).
datasets[]
| Field | Required | Notes |
|---|---|---|
key | Yes | Stable identity for idempotent apply. Must start with a lowercase letter or digit, then a-z 0-9 . _ -; up to 128 chars. |
title | Yes | Human-readable dataset title. |
description | No | Longer description. |
sources | Yes | Exactly one source object (below); the schema caps the array at one entry. |
metadata | No | Tags, CRS, license, bbox (below). |
publication | Yes | Publication intent (below). |
sources[]
| Field | Required | Notes |
|---|---|---|
type | Yes | One of vector, raster_cog. |
uri | Yes | Relative path, http(s):// URL, or s3:// URI. Must end in an extension the ingest path recognizes: zip, gpkg, geojson, json, csv, xlsx, xls, fgb, kml, kmz, or parquet (GeoParquet) for vector; tif or tiff for raster_cog. A .zip covers a zipped File Geodatabase as well as a Shapefile bundle; the two are told apart by content, not by the manifest. A query string or fragment may follow. |
format | No | Driver hint, e.g. geojson, gpkg. |
layer | No | Layer name for multi-layer sources. |
title / description | No | Per-source overrides. |
checksum | No | sha256:<64 lowercase hex characters>. A declared digest of the source bytes, folded into apply’s change-detection fingerprint alongside the rest of the entry — it is not verified against the fetched bytes. Bump it when the file under a stable URI changes, to force a vector entry to reclassify as an update instead of skipping as unchanged. Do not set or change it on a raster_cog source: manifest raster updates aren’t supported, so a changed checksum there makes apply report that entry as an error rather than a skip. |
metadata (all optional): tags (string array), organization, crs
(EPSG:NNNN), license, attribution, bbox ([minx, miny, maxx, maxy] in
WGS84).
From 1.19.1, license, organization and tags reach the dataset, both when
the manifest creates it and on a later apply that answers update for the
entry (an unchanged entry skips, and a skip writes nothing). license and
organization overwrite the stored value whenever the entry carries one; an
entry that omits a field leaves the dataset’s value alone. tags are added to
the dataset’s keywords (the Tags field on the dataset page), compared
without regard to case against the keywords already there and stored in lower
case; a tag the dataset already has is not added again, and a tag dropped
from the manifest stays on the dataset, so removing one is a dataset edit.
crs must be an EPSG code the instance knows: one that neither PROJ nor
PostGIS has is reported as an error for that entry, by --dry-run as well as
by a real apply, before anything is staged.
publication: required intent. The schema does not fix the values; they
come from the workflow statuses your deployment defines, and the server
validates them at apply time. The default set is draft, ready,
internal, published, which is why geolens validate can accept an intent
your instance then rejects.
Example manifest
Section titled “Example manifest”manifest_version: "1"catalog: title: Regional Open Data description: Public datasets published by the Regional Data Office. organization: Regional Open Data Officedatasets: - 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: readyRun an analysis
Section titled “Run an analysis”geolens analysis preview computes an operation and writes the resulting
GeoJSON to stdout without creating anything. The result is capped at the
server’s preview limit, and the cap is announced on stderr so stdout stays a
valid GeoJSON document:
geolens analysis preview <dataset_id> --operation buffer --distance 500 > ring.geojsongeolens analysis preview <dataset_id> --operation centroid --compact | jq .geolens analysis materialize runs the operation over the whole dataset and
saves the result as a new dataset:
geolens analysis materialize <dataset_id> \ --operation buffer --distance 500 --title "500 m ring"geolens analysis materialize <dataset_id> \ --operation dissolve --by-field region \ --title "By region" --no-waitBoth accept buffer, centroid, clip, spatial_join, measure,
select_by_location, and intersect; dissolve is materialize-only.
Per-operation flags are --distance (buffer, in metres), --mask-dataset
(required for clip, select_by_location and intersect — the CLI has no
drawn-mask option, so omitting it is a server 422, exit 1), --by-field
(dissolve), and --join-dataset-id / --join-fields (spatial_join).
materialize waits for the job by default. Analysis is queued below uploads, so
that wait has no upper bound — pass --timeout <seconds> to bound it, or
--no-wait to return the job id immediately.
Export STAC metadata
Section titled “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 stdoutgeolens export stac <dataset_id> -o item.json # write to a filegeolens export stac <dataset_id> --compact # single line, for piping to jqArcGIS migration
Section titled “ArcGIS migration”Three commands move an ArcGIS Online organization or a Portal for ArcGIS into
GeoLens: inventory reads the portal, plan turns the inventory into a plan you
review and edit, and migrate runs the plan.
Inventory
Section titled “Inventory”geolens arcgis inventory lists an ArcGIS Online or Portal for ArcGIS
organization’s content and reports what would carry over to GeoLens. It is
read-only: it changes nothing on the portal, needs no GeoLens instance or
sign-in, and talks only to the portal URL you give it. It never contacts the
services an item points at. To migrate a whole organization, run it as an
organization administrator: a portal search returns only items shared with the
caller.
export ARCGIS_TOKEN=... # or --token-stdin, --username with a password prompt, or --client-idgeolens arcgis inventory --portal-url https://<org>.maps.arcgis.com -o ./inventorygeolens arcgis inventory --portal-url https://gis.example.com/portal --scope orggeolens --json arcgis inventory --portal-url https://<org>.maps.arcgis.com > inventory.jsonunset ARCGIS_TOKEN # --client-id refuses to run with a token setgeolens arcgis inventory --portal-url https://gis.example.com/portal --client-id <client-id>Each item is classified as one of:
supported: hosted feature layers and views, and feature and map services GeoLens can reach.partial: web maps (their layers import, but styling and popups need translation), hosted tile layers, OGC services and data files.unsupported: apps, dashboards, StoryMaps, scenes, image and vector tile services, and anything the CLI does not recognize. GeoLens has its own stories and dashboards, butmigratedoes not convert ArcGIS StoryMaps or Dashboards into them. The report says what to rebuild: for a dashboard with no map widget, a GeoLens dashboard with the map hidden; for one with several maps, a single-map dashboard or a split.
Web AppBuilder apps and classic Esri Story Maps are flagged with Esri’s
retirement dates. Web maps and apps are read to record which layers and maps
they depend on, and a dependency is marked external when it belongs to
another organization, such as Living Atlas content. Hosted views, hosted layers
and Survey123 forms also record their source service, source file or results
service, at one extra request each.
Every item records its snippet, description, tags, credits, license, extent,
thumbnail name, spatial reference, folder, the groups it is shared with, and
its owner’s name and email. Folder titles, owner names and group lists come
back null where the portal does not let the signed-in account read them, and
the group list holds only the groups that account can see. An anonymous run
skips group reads, and --no-groups skips the one-request-per-item group read.
Scope and credentials
Section titled “Scope and credentials”--scope user(the default) lists the signed-in user’s folders.--scope orglists every organization item the account can see. Without credentials only--scope orgworks, and it lists public items.- Bring an existing token through
ARCGIS_TOKENor--token-stdin. A value passed as--token <value>is visible in the process list and usually lands in shell history, so avoid it. Or use--usernamefor a built-in account. The password comes fromARCGIS_PASSWORD,--password-stdinor a prompt, and mints a 60-minute token bound to the portal URL as its referer. The password stays in memory for the run, so when the portal rejects the token as expired the command mints a new one and retries the failed read. A token you bring is sent without aReferer. SAML and OpenID Connect accounts have no password, so they sign in through the browser with--client-idor bring a token. - Sign in through the browser with
--client-id <client-id>, or setGEOLENS_ARCGIS_CLIENT_ID. Use it when your accounts sign in through SAML or OpenID Connect, or when a migration will outlast a pasted token, which cannot be renewed. It cannot be combined with a token, including one inARCGIS_TOKEN, or with--username. See Sign in through the browser. - The token travels in the
X-Esri-Authorizationheader, never in a URL, and the command does not write it to the report or to disk. Redirects are refused.--allow-insecure-httppermits anhttp://portal URL, for test portals.
Sign in through the browser
Section titled “Sign in through the browser”--client-id signs in with OAuth 2.0 on the portal’s own login page, so it
works for accounts that use SAML or OpenID Connect. It applies to inventory and
migrate, from 1.32.0.
Set it up once. In your organization, register an OAuth 2.0 credentials item
(Content, New item, Developer credentials) and add http://127.0.0.1 as a
redirect URL. Write 127.0.0.1, not localhost: the portal treats them as
different hosts. A redirect URL without a port matches any free port. If you
register a port or a path, register exactly http://127.0.0.1:<port>/callback
and pass --redirect-port <port>.
geolens arcgis inventory --portal-url https://<org>.maps.arcgis.com \ --client-id <client-id> -o ./inventoryThe first run prints a sign-in link and opens it in your browser. After you sign
in, the portal sends the browser back to a listener on 127.0.0.1 and the
command carries on. The refresh token is saved for that portal and client ID in
the OS keyring, or in credentials.toml when there is no keyring, so later runs
sign in without opening a browser. The access token is renewed during a long
migrate. If the portal stops accepting the saved sign-in, the command opens the
browser again.
A saved sign-in has a fixed lifetime, two weeks on ArcGIS Online’s defaults. The CLI renews it without the browser once it is past half of that lifetime, so it stays valid as long as a command runs at least once within the lifetime.
To forget a saved sign-in:
geolens arcgis logout --portal-url https://<org>.maps.arcgis.com --client-id <client-id>Output and limits
Section titled “Output and limits”Output is Markdown on stdout, JSON with the global --json, or two files
(arcgis-inventory.json and arcgis-inventory.md, mode 0600) with
-o/--output-dir. The JSON schema ships in the package as
geolens_cli/manifest/schemas/arcgis-inventory-v2.schema.json.
With -o, each web map’s configuration is also saved as
webmaps/<item id>.json and each app’s as apps/<item id>.json (StoryMaps,
Experiences, Dashboards, Hub sites and pages, Web Scenes, Notebooks and the
other app types), mode 0600. Before writing, the value under any key named
like a credential (token, password, apiKey, secret, clientSecret,
credentials, customParameters) becomes [REDACTED] at any depth. Other
strings are also scrubbed by pattern: credential parameters in URLs, URL
userinfo, authorization and cookie headers, bearer-style values, JWTs, private
keys and AWS access key ids. Redaction is best effort. A secret under an
unrecognized key or in an unusual shape can remain, so treat the output as
sensitive and review it before sharing.
--read-all-item-data reads the data of every other item too, and records any
item ids it names.
--max-itemsstops listing after that many items (default 10,000).--concurrencysets parallel item reads, 1 to 4. Requests are capped at ten a second, with backoff and retry on 429 and 502 to 504.- ArcGIS search returns only the first 10,000 results of a query, so a
--scope orglisting that reaches that limit is marked truncated (search_ceiling) whatever--max-itemsis.
Exit codes for inventory: 0 when the report is complete, even if some items
could not be read (they are listed under errors, and --strict makes that exit
1); 2 for usage errors or a redirecting portal; 3 when the token is
rejected; 4 for network errors; 5 for portal server errors. If a token you
brought expires mid-run, or a new one cannot be minted, the partial report is
still written and marked "complete": false. Rerun with a fresh token.
Plan the migration
Section titled “Plan the migration”geolens arcgis plan turns an inventory into an editable plan. It reads only
the inventory file, so it needs no portal or GeoLens access.
geolens arcgis inventory --portal-url https://<org>.maps.arcgis.com -o ./inventorygeolens arcgis plan ./inventory/arcgis-inventory.jsongeolens arcgis plan ./inventory/arcgis-inventory.json --owner-map owners.jsonIt writes arcgis-migration-plan.json (mode 0600) next to the inventory, or
into -o/--output-dir, and prints how many items each action covers and which
dependencies point at items that are not in the inventory. It refuses a v1
inventory and tells you to rerun the inventory. The plan file uses schema v2
(arcgis-migration-plan-v2.schema.json in the package).
Run plan again on a newer inventory to merge it into the existing plan: values
you edited stay, values you left alone take the new defaults, and new portal
items are added with defaults. An item gone from the portal is kept with
"removed": true and not run again, but only a complete --scope org
inventory read by an organization administrator marks items removed. Any other
inventory marks the items it doesn’t list "unlisted": true, and migrate
leaves those pending until a merge lists them again. To leave an item out, set
its action to skip; an item you delete from the plan comes back on the next
merge. --force discards your edits and writes a fresh plan.
These are the fields you are expected to edit:
items[].actionis one ofimport_layers,import_file,import_map,export_onlyorskip. The default follows the inventory: supported feature and map services import as layers, data files import as files, web maps import as maps, and apps, scenes and unsupported types areexport_only. Setskipfor anything you do not want. A web map whose data could not be read defaults toexport_onlyand the plan warns, because its layer dependencies are unknown.items[].targetholds thevisibility(ArcGIS private, org and public become private, internal and public, and an item shared only with groups becomesrestricted, shared with the GeoLens groups its ArcGIS groups map to, or private when none maps), thecollections(the item’s folder), thegroups(the ArcGIS group ids it is shared with,nullwhen the inventory did not read group sharing), thetitleand thetags.target.ownerisnullto useowner_map, or a GeoLens username or email to override it for one item.owner_maplists every ArcGIS owner with an empty value to fill in with the GeoLens user who should end up owning the item.--owner-map file.jsonfills it from a prepared{"arcgis_user": "geolens_user"}object.group_maplists every group seen. Itsgeolens_grouppicks the sharing group for items shared with that ArcGIS group:nullmakesmigratecreate a group named after the ArcGIS group and add the members it can resolve, the exact name of an existing GeoLens group shares with that group and leaves its members alone, and an empty string maps to no group.collectionholds the group’s title, used to name a created group only when the inventory has none, andvisibilityrecords the group’s ArcGIS access;migratedoesn’t read it.basemap_maplists every basemap URL used by a web map, to fill in with the GeoLens basemap that replaces it.items[].alias_ofis set by hand, with actionskip, on a hosted view that filters nothing, so web maps using it point at the parent’s dataset. The inventory cannot tell, because a view’s filter lives in the service, which the inventory never contacts.
depends_on lists the items to migrate first. An id that is not among the
plan’s items is not in the inventory. Items from other organizations, such as
Living Atlas layers, get no row and never appear in depends_on. A data file
that a hosted layer was published from is export_only with superseded_by
naming the layer, so its rows are not imported twice.
The plan and the sidecar files go through the same redaction as the inventory, with the same limits. Review them before sharing.
Run the migration
Section titled “Run the migration”geolens arcgis migrate runs the plan one item at a time, in dependency order.
It needs a GeoLens admin session (geolens login as an admin), because it reads
the user list and hands each item to the owner the plan names. Items are
imported as you, then transferred. The owner needs a role with upload for
datasets or edit_metadata for maps, and must already be a GeoLens user;
geolens admin users import creates them.
geolens arcgis migrate ./inventory/arcgis-migration-plan.json --dry-rungeolens arcgis migrate ./inventory/arcgis-migration-plan.json --username <arcgis-admin>--dry-runchecks the plan and owners and lists what would run, importing nothing. With--usernameit also makes the ArcGIS sign-in, so a refused password exits3before the real run.- Credentials work as for
inventory:ARCGIS_TOKEN,--token-stdin,--usernamewith the password fromARCGIS_PASSWORD,--password-stdinor a prompt, or--client-idto sign in through the browser. A token made from a password or a browser sign-in is renewed; a pasted token is not, and the run stops and saves its state when it expires. A private service on a federated ArcGIS Server with another host gets the token only when you name that host with--trust-service-host <host>. A private service import also needsREDIS_URLset on the GeoLens instance. import_layersitems are imported by GeoLens from the service,import_fileitems are downloaded from the portal and uploaded (within the upload size limit), andimport_mapitems go through the server’s web map translator once their layers are imported.export_onlyitems are saved underexport/<type>/<item id>/next to the state file, listed inexport/INDEX.md, with each item capped at--export-cap-mb(default 200).--unmapped-owner <user>takes items whose plan owner can’t own them yet (no mapping, not signed in yet, inactive or without the permission). A later run hands them over once the owner can take them.- Items shared only with ArcGIS groups are shared with GeoLens groups as
group_mapsays. The run adds each group’s members that resolve to GeoLens users; members without an account stay pending until a later run.
Progress is saved after every item in arcgis-migration-state.json (mode
0600) beside the plan, or at --state. Run the same command again to resume:
failed items are retried (--no-retry leaves them), nothing is imported twice,
and items migrated before are brought up to date from the portal. A rerun never
overwrites a dataset changed in GeoLens since the last run; it reports it
instead. This includes a title you changed in GeoLens when the rerun picks up an
item that stopped before its handover; the run notes each title it keeps, and
later refreshes keep it too. Where the state file has no record of the title an
import gave its dataset, a title that differs from the plan’s is kept. --only <item id> runs one item and the unfinished items it depends
on. A run that finds no state file while GeoLens already holds datasets from the
plan’s items stops and exits 2; point --state at the earlier file, or pass
--start-fresh to import them again.
Each run that reaches the items writes arcgis-migration-report.md and .json
next to the state file, with the follow-ups to handle by hand. Exit codes: 0
when no item failed or was left waiting; 1 when an item failed, waits, or
couldn’t be updated or handed over, or when a group membership change failed;
2 for an unusable plan, state file, owner mapping or credentials, a
non-admin GeoLens session or a taken group or collection name; 3 for
authentication failures; 4 for network errors; 5 for a GeoLens server error
before any item ran; 130 when interrupted.
Cutover. After the portal stops changing, run inventory --scope org and
plan again, then migrate --dry-run --cutover, then migrate --cutover. The
cutover run refuses (exit 1) while anything would not carry over, unless you
accept each loss with its flag: --accept-unfinished-items,
--accept-incomplete-inventory, --accept-attachment-loss (GeoLens doesn’t
import attachments), --accept-unresolved-users or --accept-under-sharing.
The report records the cutover and what you accepted. --cutover can’t be
combined with --only.
Import users
Section titled “Import users”geolens admin users import creates GeoLens users in bulk and skips anyone who
already exists with the same username and email. It needs an admin session and
exits 3 without one.
geolens admin users import users.csv --print-passwordsgeolens admin users import --from-inventory ./inventory/arcgis-inventory.json --seed-csv users.csv- The CSV has a header row naming
username,emailandrole(admin,editororviewer; empty meansviewer). A row that clashes with another account’s username or email isn’t created, and the run exits1. --from-inventorytakes users from an ArcGIS inventory: item owners as editors, members of groups that items are shared with as viewers. Add--seed-csv <file>to write those rows to a new CSV for review and create nothing.--dry-runsays what would be created.- Each new user gets a generated 72-character password.
--print-passwordsshows each one once on standard output; nothing else records them, so without it you set passwords through the admin password reset. - On an instance that signs in through an identity provider, users are created
at their first sign-in, so the import creates nobody unless you pass
--link-by-email. That creates them with a password nobody is shown, so their first sign-in links by email, which needs the provider to sendemail_verified. GeoLens treats an email an admin enters as verified, so whoever signs in through the provider with that address gets the account: check every email before importing with--link-by-email.
CI integration
Section titled “CI integration”The CLI is built for pipelines: authenticate through the environment, validate
offline, preview with --dry-run on a pull request, apply on a push to main.
--json is a global option and goes before the subcommand (geolens --json apply geolens.yaml). Only geolens scan also accepts --json after the
subcommand; for every other command a trailing --json is a “No such option”
error.
Exit codes
Section titled “Exit codes”Every command returns a non-zero exit code on failure, and the code says what kind of failure it was:
| Code | Meaning | What produces it |
|---|---|---|
0 | Success | The command did what you asked. |
1 | Failed | A request the server answered with a status that is neither auth nor 5xx — a 404 for an unknown dataset, a 400, a 422 the CLI did not catch first. Also a job that finished failed, an apply whose response reported per-dataset errors, and a re-commit of an upload that was already committed. |
2 | Usage error | An unknown flag or a malformed argument, plus the checks below. apply also maps a server 422 here. |
3 | Auth | A 401 or 403 on a request, with the one exception noted below. Also “no instance configured”, but only from publish, whoami, analysis preview and analysis materialize — they check for an instance themselves. status, refresh, export stac, apply and logout treat a missing instance as a usage error and exit 2 instead. whoami also uses 3 for a session it could not refresh. |
4 | Network | The request timed out or the instance was unreachable — DNS, TLS, connection refused. |
5 | Server | A 5xx from the API, or an apply response that was not the JSON it should have been. |
6 | Blocked for review | replace --wait, refresh --wait or apply --wait ended with a run waiting for review. For apply --wait, a failure in any entry takes precedence and the exit is 1. |
Two collapses are worth knowing before you branch on these. 401 and 403
both exit 3, so a rejected credential and a permission you do not hold look
identical — the distinguishing sentence is on stderr. And every 5xx exits
5, so a 500 and a 503 behind a proxy are the same code.
The exception to 3: a 401 or 403 raised while applying --tags or
--collection after a publish commits becomes a warning line on a dataset that
now exists, and the command exits 1. That is deliberate — re-running would
publish a duplicate, so the failure is not presented as retryable.
That leaves three codes a credential problem can arrive under, so branching on
the code alone is not enough: 3 for an ordinary rejection, 2 when a command
that resolves its own instance finds none configured, and 1 for the
post-commit case above. Read stderr to tell them apart — and treat 1 from
publish as “the dataset exists, the extras did not apply”, never as a signal
to retry the publish.
Several commands exit 2 for a flag combination rather than a typo, and all
but one of them decide it locally, before any request goes out:
publish --tagsor--collectiontogether with--no-wait, since both are applied after the commit resolves the dataset id.refresh --timeoutwithout--wait, and any--timeoutthat is not a finite number greater than zero.analysis materialize --timeoutenforces the same finite bound.export stacagainst a vector dataset: a pre-flightGET /datasets/{id}reads the record type and rejects a non-raster one before the STAC endpoint is touched. This is the one that does make a request — and if that pre-flight404s on an unknown id, the exit is1, not2.analysiswithspatial_joinand no--join-dataset-id. Other bad operation/flag pairings are only caught by the server, which makes them a422and therefore exit1.validateon a manifest that fails the schema, andinitagainst a manifest that already exists without--force.
The examples repo has a ready-made GitHub Actions workflow that splits validate, preview, and apply into three jobs so the write token never reaches a pull request, and a walkthrough of the secrets and environment it expects.
Global options
Section titled “Global options”These apply to every command and go before the subcommand:
| 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. |
Next steps
Section titled “Next steps”- Client SDKs: call the API from Python or TypeScript.
- Importing data: the same imports from the app.
- Authentication: API keys the CLI can use.