CLI

Unealta de linie de comandă eocube se instalează cu extra-ul cli (pip install "eocube[cli]"). Fiecare comandă și sub-comandă acceptă --help; această pagină este o privire de ansamblu asupra arborelui de comenzi.

Opțiuni globale

Opțiune	Semnificație
--context <nume>	Folosește un anumit context; implicit context.primary.
--log-level <nivel>	DEBUG, INFO, WARNING (implicit), ERROR, CRITICAL.
--version	Afișează versiunea și commit-ul de build, apoi iese.

bash

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

eocube setup

Inițializează și editează fișierul de configurare (vezi Configurare).

Comandă	Descriere
setup init [--force]	Resetează configurația la valorile implicite ROCS.
setup auth add --name <n> oidc --discovery-url <url>	Adaugă o sursă de autentificare OIDC.
setup storage add --name <n> --endpoint <url> [--auth-ref <nume> \| --auth-oidc]	Adaugă o definiție de stocare.
setup stac add --name <n> --endpoint <url> [--auth <ref>]	Adaugă un endpoint STAC.
setup processes add --name <n> --endpoint <url> [--auth <ref>]	Adaugă un endpoint OGC API - Processes.
setup context add --name <n> --auth <a> --stac <s> [--processes <p>] [--storage <s>] [--user-storage <s>] [--primary]	Adaugă un context.

eocube auth

Autentificare și funcții pentru credențiale.

Comandă	Descriere
auth login [--device-flow]	Autentificare (implicit în browser, sau prin OAuth device flow).
auth logout	Revocă și șterge token-urile stocate.
auth info	Afișează claim-urile decodate ale token-ului curent.
auth get-access-token	Afișează un token de acces OIDC valid la stdout.
auth get-storage-credentials [--endpoint <url>] [--duration <s>] [--as-json]	Obține credențiale S3 temporare prin STS.
auth get-storage-credentials-with-token --token <jwt> [--endpoint <url>]	La fel, folosind un token furnizat de tine.

auth login scrie refresh token-ul tău în contextul activ din eocube.yml; comenzile ulterioare regenerează automat token-uri de acces din el. În container / CI, setează variabilele de mediu în loc să te autentifici.

eocube services

services stac

CRUD, căutare și gestionarea endpoint-urilor pentru catalogul STAC. Vezi Autorizarea catalogului STAC pentru regulile de proprietate și vizibilitate care se aplică la publicare.

Comandă	Descriere
stac collection create \| list \| get \| update \| delete	Gestionează colecții.
stac item add \| get \| update \| delete	Gestionează item-uri într-o colecție.
stac search	Caută în catalog (după colecție, bbox, datetime, ...).
stac download <dataset.json>	Descarcă activele unei căutări salvate într-un director local.
stac endpoint get-default \| set-default	Afișează sau setează endpoint-ul STAC implicit.
stac endpoint alias add \| remove \| list	Gestionează alias-uri de endpoint STAC.

Descărcarea unui rezultat de căutare

stac search scrie JSON doar cu --json; fără el obții tabelul destinat citirii. Salvează un rezultat, apoi descarcă-i activele:

bash

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

Fișierele ajung în <destinatie>/<colectie>/<id-element>/, lângă un <id-element>.json ale cărui href-uri indică fișierele descărcate, astfel încât directorul se deschide în orice unealtă care înțelege STAC. Cele două comenzi se pot și înlănțui:

bash

eocube services stac search --collections colectia-mea --json \
    | eocube services stac download --destination ./date

Opțiuni utile: --assets/--roles pentru un subset (de exemplu --roles data), --workers pentru transferuri paralele, --dry-run pentru a vedea întâi planul, --flat pentru a renunța la directorul per element și --force pentru a redescărca fișierele existente. O reluare omite activele a căror dimensiune locală se potrivește deja cu cea declarată în catalog, deci o descărcare întreruptă se reia ieftin. Colecțiile publice pot fi descărcate fără autentificare; adaugă --anonymous pentru a sări complet peste schimbul de credențiale.

Verifică întâi planul

--dry-run afișează fiecare fișier, destinația și dimensiunea lui, fără a transfera nimic. Pe colecțiile cu active mari sau numeroase este cea mai ieftină metodă de a afla ce urmează să descarce o căutare.

Exemplu: Sentinel-2 L2A

Un element L2A conține peste 70 de active (toate benzile la fiecare rezoluție, măștile de calitate per bandă, clasificarea scenei și previzualizările) și ajunge la circa 270 MB. Descărcarea elementelor întregi este rareori ceea ce vrei, deci selectează benzile de care ai nevoie. Roșu, infraroșu apropiat și clasificarea scenei, suficiente pentru un NDVI plus mascarea norilor, înseamnă aproximativ 90 MB per element:

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 ./date \
    --assets B04_10m,B08_10m,SCL_20m

Cheile activelor includ rezoluția, deci B04_10m și B04_20m sunt active diferite. Folosește --dry-run pentru a lista cheile publicate efectiv de o colecție. Pentru a descărca un element complet, omite --assets; pentru doar imagini, fără măști și metadate, folosește --roles data.

Exemplu: Sentinel-1 RTC

Activele RTC sunt mult mai mari: un singur raster gamma0-vv are circa 475 MB, deci o scenă cu polarizare duală se apropie de un gigabyte. Descarcă o singură polarizare atunci când analiza are nevoie doar de ea:

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 ./date --dry-run

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

O căutare pe județ pe două săptămâni ajunge ușor la zeci de gigabytes pe toate activele, motiv pentru care rulezi întâi --dry-run: raportează totalul exact înainte de a transfera ceva.

Corecția de teren are nevoie și de unghiul de incidență; adaugă local-incidence-angle dacă intenționezi să normalizezi mai departe. Imaginea de previzualizare se află sub rolul thumbnail și este publicată ca URL simplu, nu ca obiect, lucru tratat transparent de comandă:

bash

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

Locația activelor

Se descarcă atât obiecte s3://, cât și URL-uri http(s)://. Niciodată nu se atașează credențiale unui activ de tip URL simplu, fiindcă gazda lui nu face neapărat parte din această platformă, deci activele publicate în spatele unei autentificări trebuie obținute pe altă cale. Orice altă schemă este raportată ca omisă, iar restul lotului continuă.

services processes

Rulează joburi de procesare pe platformă prin serviciul său OGC API - Processes. Un proces se publică dintr-un OGC Application Package, al cărui executionUnit este imaginea de container care face prelucrarea, deci gestionarea unităților de execuție înseamnă publicarea, înlocuirea și retragerea proceselor. Fiecare comandă acceptă --endpoint <url|nume>; implicit se folosește cel al contextului activ (vezi Configurare).

Comandă	Descriere
processes list [--fields f1,f2] [--json]	Listează procesele publicate.
processes describe <id>	Afișează descrierea unui proces (intrări, ieșiri); ETag-ul merge la stderr.
processes package <id> [--output FIȘIER]	Afișează pachetul de aplicație al unui proces modificabil.
processes deploy [--file FIȘIER \| --data JSON] [--idempotency-key K]	Publică un proces dintr-un pachet de aplicație (sau din stdin).
processes replace <id> --file FIȘIER [--if-match ETAG]	Înlocuiește un proces modificabil.
processes undeploy <id> [--yes] [--if-match ETAG]	Retrage un proces modificabil; joburile deja create continuă.
processes execute <id> [--input k=v ...] [--input-json k=JSON ...] [--output ID[=value\|reference] ...] [--wait] [--results]	Execută un proces; afișează starea noului job.
processes jobs list [--process ID] [--status S] [--all]	Listează joburile tale, cele mai noi primele.
processes jobs status <job> / jobs wait <job>	Afișează sau urmărește un job.
processes jobs results <job> [--download DIR] [--raw-output FIȘIER]	Afișează rezultatele; descarcă ieșirile date prin referință.
processes jobs logs <job> [--stream stdout\|stderr]	Afișează logurile capturate (doar pentru utilizatorul care a trimis jobul).
processes jobs notifications <job>	Afișează starea livrării evenimentelor și callback-urilor jobului.
processes jobs dismiss <job> [--yes]	Anulează un job: îl oprește și îi elimină rezultatele.

add, get, delete și remove funcționează și ca alias-uri pentru deploy, describe și undeploy. jobs results --download DIR salvează o ieșire cu o singură valoare ca DIR/<ieșire><ext> și fiecare element al unei ieșiri cu mai multe valori ca DIR/<ieșire>/<index><ext>; --raw-output este pentru joburile executate cu --response raw, al căror corp este chiar ieșirea (chiar și când este JSON).

Execuția este mereu asincronă: execute revine imediat cu un id de job. Valorile --input sunt mereu șiruri; folosește --input-json pentru numere, liste și obiecte și repetă o cheie pentru mai multe valori. --file primește în schimb o cerere de execuție completă.

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

Cu --wait, progresul merge la stderr iar starea finală la stdout; comanda se încheie cu codul 1 când jobul a eșuat, a fost anulat sau a expirat --timeout (jobul continuă să ruleze).

Permisiuni

Fiecare cerere necesită autentificare (eocube auth login). Listarea și citirea funcționează pentru orice utilizator autentificat; publicarea, execuția și anularea necesită apartenența la un tenant de procesare, acordată de administratorii platformei. Înlocuirea și retragerea sunt rezervate proprietarului procesului.

Erori

Erorile sunt raportate din documentul de problemă al serviciului: titlul, statusul HTTP și tipul problemei, detaliul, câmpul sau motivul în cauză, fiecare problemă de validare ca cale: mesaj [cuvânt-cheie] și un ID de corelare de menționat când ceri ajutor. Limitele de rată și răspunsurile temporare de tip "reîncearcă mai târziu" sunt reîncercate automat de câteva ori.

services geospatialorg

Caută unități administrative și județe din România de la geo-spatial.org.

Comandă	Descriere
geospatialorg get-county-by-name --name <nume>	Județ după nume.
geospatialorg get-county-by-mnemonic --name <cod>	Județ după mnemonic (ex. TM).
geospatialorg get-administrative-unit-by-name --name <nume>	Unitate administrativă după nume.
geospatialorg get-administrative-unit-by-code --code <siruta>	Unitate administrativă după cod SIRUTA.

Necesită extra-ul services

Aceste comenzi au nevoie de geopandas / owslib. Instalează-le cu pip install "eocube[services]". O comandă rulată fără ele eșuează cu un mesaj clar, fără a bloca CLI-ul.

services proxy

Pornește un proxy invers local, autentificat, către un serviciu EOCube. Acesta injectează token-ul tău OIDC în fiecare cerere transmisă, astfel încât o unealtă care nu "vorbește" OIDC (un browser, curl, QGIS, un notebook) poate accesa serviciul prin URL-ul local.

bash

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

Opțiune	Implicit	Semnificație
--endpoint <url>	(obligatoriu)	Serviciul upstream către care se face proxy.
--port <n>	9112	Portul local.
--bind <adresă>	127.0.0.1	Adresa locală de legare (vezi nota de securitate din --help).
--anonymous	dezactivat	Nu injecta un token.

eocube mcp serve

Pornește un server Model Context Protocol (MCP) care expune setul de unelte EOCube agenților LLM. Rulează implicit pe stdio, sau pe streamable HTTP cu --http. Valorile implicite (host, port, stateless, allow-destructive) provin din secțiunea mcp a configurației; opțiunile le suprascriu. Necesită extra-ul mcp.

bash

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

--endpoint setează endpoint-ul STAC implicit al uneltelor, iar --processes-endpoint endpoint-ul OGC API - Processes implicit al uneltelor processes_*. processes_undeploy și processes_dismiss_job sunt înregistrate doar cu --allow-destructive.

eocube tools

Funcții offline care nu necesită acces la API -- de exemplu tools stac create-item, care construiește un Item STAC din fișiere raster.