CLI

The eocube command-line tool is installed with the cli extra (pip install "eocube[cli]"). Every command and sub-command supports --help; this page is an overview of the command tree.

Global options

Option	Meaning
--context <name>	Use a specific context; defaults to context.primary.
--log-level <level>	DEBUG, INFO, WARNING (default), ERROR, CRITICAL.
--version	Print the version and build commit, then exit.

bash

eocube --context=eocube.ro services stac collection list

eocube setup

Initialise and edit the configuration file (see Configuration).

Command	Description
setup init [--force]	Reset the config to the built-in ROCS defaults.
setup auth add --name <n> oidc --discovery-url <url>	Add an OIDC authentication source.
setup storage add --name <n> --endpoint <url> [--auth-ref <name> \| --auth-oidc]	Add a storage definition.
setup stac add --name <n> --endpoint <url> [--auth <ref>]	Add a STAC endpoint.
setup processes add --name <n> --endpoint <url> [--auth <ref>]	Add an OGC API - Processes endpoint.
setup context add --name <n> --auth <a> --stac <s> [--processes <p>] [--storage <s>] [--user-storage <s>] [--primary]	Add a context.

eocube auth

Authentication and credential helpers.

Command	Description
auth login [--device-flow]	Log in (browser by default, or OAuth device flow).
auth logout	Revoke and clear the stored tokens.
auth info	Show the decoded claims of the current token.
auth get-access-token	Print a valid OIDC access token to stdout.
auth get-storage-credentials [--endpoint <url>] [--duration <s>] [--as-json]	Obtain temporary S3 credentials via STS.
auth get-storage-credentials-with-token --token <jwt> [--endpoint <url>]	The same, using a token you supply.

auth login writes your refresh token into the active context in eocube.yml; subsequent commands re-mint access tokens from it automatically. In containers / CI, set the environment variables instead of logging in.

eocube services

services stac

CRUD, search, and endpoint management for the STAC catalog. See STAC Catalog Authorization for the ownership and visibility rules that apply when you publish.

Command	Description
stac collection create \| list \| get \| update \| delete	Manage collections.
stac item add \| get \| update \| delete	Manage items within a collection.
stac search	Search the catalog (by collection, bbox, datetime, ...).
stac download <dataset.json>	Download the assets of a saved search into a local directory.
stac endpoint get-default \| set-default	Show or set the default STAC endpoint.
stac endpoint alias add \| remove \| list	Manage STAC endpoint aliases.

Downloading a search result

stac search writes JSON only with --json; without it you get the table meant for reading. Save a result, then fetch its assets:

bash

eocube services stac search --county Arad \
    --collections sentinel-2-burn-scars-terramind-fire --json > dataset.json
eocube services stac download dataset.json --destination ./data

Files land under <destination>/<collection>/<item-id>/, next to an <item-id>.json whose asset hrefs point at the downloaded files, so the directory opens in any STAC-aware tool. The two commands also pipe directly:

bash

eocube services stac search --collections my-collection --json \
    | eocube services stac download --destination ./data

Useful options: --assets/--roles to fetch a subset (for example --roles data), --workers for parallel transfers, --dry-run to see the plan first, --flat to drop the per-item directory and --force to re-fetch files that already exist. A re-run skips assets whose local size already matches the size declared in the catalog, so an interrupted download resumes cheaply. Public collections can be fetched without logging in; add --anonymous to skip the credential exchange entirely.

Always check the plan first

--dry-run prints every file, its destination and its size without transferring anything. On collections with large or numerous assets this is the cheapest way to find out what a search is about to pull.

Example: Sentinel-2 L2A

An L2A item carries more than 70 assets (all bands at every resolution, the per-band quality masks, the scene classification and the previews) and runs to roughly 270 MB. Downloading whole items is rarely what you want, so select the bands you actually need. Red, near-infrared and the scene classification, enough for an NDVI plus cloud masking, come to about 90 MB per item:

bash

eocube services stac search --county Arad --collections sentinel-2-l2a \
    --start 2026-09-01 --end 2026-09-16 --json > l2a.json

eocube services stac download l2a.json --destination ./data \
    --assets B04_10m,B08_10m,SCL_20m

Asset keys carry the resolution, so B04_10m and B04_20m are different assets. Use --dry-run to list the keys a collection actually publishes. To pull a full item instead, drop --assets; to fetch only the imagery and leave the masks and metadata behind, use --roles data.

Example: Sentinel-1 RTC

RTC assets are much larger: a single gamma0-vv raster is around 475 MB, so a dual-polarisation scene is close to a gigabyte. Fetch one polarisation at a time when that is all the analysis needs:

bash

eocube services stac search --county Arad --collections sentinel-1-rtc \
    --start 2026-09-01 --end 2026-09-16 --json > rtc.json

eocube services stac download rtc.json --destination ./data --dry-run

eocube services stac download rtc.json --destination ./data \
    --assets gamma0-vv,mask,processing-metadata --workers 2

A two-week county search is easily tens of gigabytes across every asset, which is why the dry-run comes first: it reports the exact total before anything transfers.

Terrain correction needs the incidence angle too; add local-incidence-angle when you intend to normalize further. The quick-look image sits under the thumbnail role and is published as a plain URL rather than an object, which the command handles transparently:

bash

eocube services stac download rtc.json --destination ./previews \
    --roles thumbnail

Asset locations

Both s3:// objects and http(s):// URLs are downloaded. No credentials are ever attached to a plain-URL asset, since its host need not be part of this platform, so assets published behind a login must be fetched by other means. Anything under another scheme is reported as skipped and the rest of the batch continues.

services processes

Run processing jobs on the platform through its OGC API - Processes service. A process is deployed from an OGC Application Package, whose executionUnit is the container image that does the work, so managing execution units means deploying, replacing and undeploying processes. Every command takes --endpoint <url|name>; the default comes from the active context (see Configuration).

Command	Description
processes list [--fields f1,f2] [--json]	List the deployed processes.
processes describe <id>	Show a process description (inputs, outputs); its ETag goes to stderr.
processes package <id> [--output FILE]	Show the application package of a mutable process.
processes deploy [--file FILE \| --data JSON] [--idempotency-key K]	Deploy a process from an application package (or stdin).
processes replace <id> --file FILE [--if-match ETAG]	Replace a mutable process.
processes undeploy <id> [--yes] [--if-match ETAG]	Remove a mutable process; jobs already created keep running.
processes execute <id> [--input k=v ...] [--input-json k=JSON ...] [--output ID[=value\|reference] ...] [--wait] [--results]	Execute a process; prints the new job's status.
processes jobs list [--process ID] [--status S] [--all]	List your jobs, newest first.
processes jobs status <job> / jobs wait <job>	Show or follow a job.
processes jobs results <job> [--download DIR] [--raw-output FILE]	Show the results; download the outputs given by reference.
processes jobs logs <job> [--stream stdout\|stderr]	Show the captured logs (only for the user who submitted the job).
processes jobs notifications <job>	Show the delivery state of the job's events and callbacks.
processes jobs dismiss <job> [--yes]	Dismiss a job: stop it and remove its results.

add, get, delete and remove also work as aliases of deploy, describe and undeploy. jobs results --download DIR saves a single-valued output as DIR/<output><ext> and each item of a multi-valued one as DIR/<output>/<index><ext>; --raw-output is for jobs executed with --response raw, whose body is the output itself (even when it is JSON).

Execution is always asynchronous: execute returns at once with a job id. --input values are always strings; use --input-json for numbers, arrays and objects, and repeat a key to pass several values. --file takes a complete execute request instead.

bash

eocube services processes describe echo
eocube services processes execute echo --input message=hello --wait --results
eocube services processes jobs list --process echo --status successful
eocube services processes jobs results <job-id> --download ./out

With --wait, progress goes to stderr and the final status to stdout; the command exits with status 1 when the job failed, was dismissed, or --timeout expired (the job itself keeps running).

Permissions

Every request needs a login (eocube auth login). Listing and reading work for any authenticated user; deploying, executing and dismissing need membership of a processing tenant, which the platform administrators grant. Replacing and undeploying are reserved to the process owner.

Errors

Errors are reported from the service's problem document: the title, the HTTP status and problem type, the detail, the offending field or reason, each validation issue as path: message [keyword], and a correlation id to quote when asking for help. Rate limits and transient "retry later" answers are retried automatically a few times.

services geospatialorg

Look up Romanian administrative units and counties from geo-spatial.org.

Command	Description
geospatialorg get-county-by-name --name <name>	County by name.
geospatialorg get-county-by-mnemonic --name <code>	County by mnemonic (e.g. TM).
geospatialorg get-administrative-unit-by-name --name <name>	Administrative unit by name.
geospatialorg get-administrative-unit-by-code --code <siruta>	Administrative unit by SIRUTA code.

Requires the services extra

These commands need geopandas / owslib. Install them with pip install "eocube[services]". A command run without them fails with a clear hint rather than crashing the CLI.

services proxy

Run a local authenticating reverse proxy to an EOCube service. It injects your OIDC token into every forwarded request, so a tool that can't speak OIDC (a browser, curl, QGIS, a notebook) can reach the service through the local URL.

bash

eocube services proxy --endpoint https://stac.eocube.ro --port 9112
curl http://127.0.0.1:9112/collections

Option	Default	Meaning
--endpoint <url>	(required)	Upstream service to proxy to.
--port <n>	9112	Local port.
--bind <addr>	127.0.0.1	Local bind address (see the security note in --help).
--anonymous	off	Do not inject a token.

eocube mcp serve

Run a Model Context Protocol (MCP) server that exposes the EOCube toolset to LLM agents. Runs over stdio by default, or streamable HTTP with --http. Defaults (host, port, stateless, allow-destructive) come from the mcp section of the configuration; flags override them. Needs the mcp extra.

bash

eocube mcp serve                       # stdio
eocube mcp serve --http --host 0.0.0.0 --port 8002

--endpoint sets the default STAC endpoint of the tools and --processes-endpoint the default OGC API - Processes endpoint of the processes_* tools. processes_undeploy and processes_dismiss_job are only registered with --allow-destructive.

eocube tools

Offline helpers that need no API access -- for example tools stac create-item, which builds a STAC Item from raster files.