CLI - Implement MVP

[j08lue]

In our CCN1 proposal, we described the need for a CLI / Python client library:

2.19 User Client BB: CLI and Python library

2.19.1 Understanding of feature

The EOEPCA+ Command-Line Interface (CLI) and Python Client Library feature enhances the usability, accessibility, and automation potential of the EOEPCA+ ecosystem by providing lightweight, developer-oriented tools for interacting with the platform’s APIs. These tools will enable both interactive users and automated systems to seamlessly discover, access, and process Earth Observation data within EOEPCA+, without requiring deep familiarity with the underlying service endpoints or manual management of authentication tokens.

The feature comprises two closely related components — a Python client library and a command-line interface (CLI) — both designed to simplify interaction with EOEPCA+’s federated services. The Python library will serve as the foundational layer, exposing a unified, object-oriented interface that wraps all EOEPCA+ APIs, including those for authentication, data discovery, catalogue search, data access, processing, and user management. By installing the package via a simple command (e.g., pip install eoepca-client), users will gain programmatic access to the platform’s full functionality within Python environments, including Jupyter notebooks and automated pipelines.

The CLI will build directly upon this Python library, providing terminal-based commands for performing the same operations from the command line. It will support actions such as authenticating a user, querying catalogues, ordering data, submitting processing jobs, monitoring progress, and managing resources. The CLI will handle authentication transparently, automatically invoking the EOEPCA Identity and Access Management (IAM) services to obtain, refresh, and apply OAuth2 or OpenID Connect tokens. This removes the need for users to manually manage access tokens or client credentials, significantly reducing entry barriers and potential configuration errors.

Together, these tools serve two complementary user groups. The CLI is targeted at power users and operators, who require a fast and consistent interface for scripting tasks or managing services directly from the terminal. The Python client library, on the other hand, targets developers, data scientists, and integrators, enabling them to embed EOEPCA+ functionality within their own applications, notebooks, and workflows. Both components will follow the same design principles and codebase, ensuring consistency in behavior, error handling, and authentication across interfaces.

To support user adoption and reproducibility, the Python package will include example notebooks demonstrating common workflows such as data search and retrieval, on-demand ordering, and processing job submission. These examples will illustrate how to integrate EOEPCA+ capabilities into custom scripts and pipelines, promoting uptake among research and operations communities.

2.19.2 Use cases for feature

• As a platform user, I want to use a single library or command line tool to interact with the platform ser-vices.
• As an operator, I want to provide easy-to-use tools for platform users to interact with the platform ser-vices that especially hides the complexity of authentication workflows as well as REST-based APIs.
• As a registered platform user, I need to complete authentication and authorisation flows as part of my interactive Python-based data analysis, so I can access restricted or user-private resources.
• As a platform user, I would like to get an overview of available platform services, such that I can find the resources I need.

2.19.3 Implementation of feature

A review of the existing EOEPCA demo notebooks and docs will reveal the tasks around platform services that are repetitive, cumbersome, and can be classified as boilerplate. Together with building block developer teams and potentially with champion users from existing platforms, we will design and develop an EOEPCA Python client library that eases or automates these tasks, while not replicating existing community-maintained clients.

Tasks:

• Documentation of common platform-specific tasks in user code workflows and prioritised list of tasks to include in CLI/client
• Concept and initial development of eoepca-client library and CLI
• CLI subcommands for resource discovery client - Integration with OWSLib
• CLI subcommands for resource registration client
• Showcase how Python library can be integrated into own platform-specific library

In the last quarter, we refined the use cases further, informed by the user needs on DLR's terrabyte platform:

• CLI - Feature requirements from terrabyte platform #9 (comment)

Acceptance criteria

• Identified priority features (MVP)
• Implemented MVP
• Prepared docs and demo

[j08lue]

Note from @james-hinton during Technical Progress Review: The Canadian steering group member also gathered use cases for this client library – joint review with @pantierra to be organised by @james-hinton.

[pantierra]

I checked the Canadian input and the demo notebooks and wrote up the following proposal:

EOEPCA+ Python Client Library and CLI proposal

Single, installable Python package, eoepca-client (PyPI name), that exposes the EOEPCA+ platform as:

1. A Python library (import eoepca_client) usable from notebooks, pipelines, and downstream apps.
2. A CLI (eoepca …) built directly on top of the library with Typer, for scripting and interactive terminal use.

Both interfaces integrate with EOEPCA+'s public APIs:

• Hide token management (Keycloak OIDC: device, password, refresh, client-credentials).
• Provide a consistent, object-oriented surface over the heterogeneous EOEPCA+ building-block APIs (REST, OGC API, STAC, S3, BPMN).
• Behave the same way whether called from Python or the shell (same models, same error handling, same config).

Reuse community libraries where they already exist (no rewrite of STAC/OWS/openEO clients), where a mature library exists the client configures and returns it rather than wrapping it. Where no client exists (Workspace API, Registration API, Harvester engine), we may ship a small first-class wrapper.

Note: this is not a replacement for kubectl, ArgoCD, or Helm. It does not talk to Kubernetes. It talks to the public APIs that EOEPCA+ building blocks expose to authenticated end users.

Out-of-scope

Being explicit avoids scope creep and clarifies the boundary with other tools:

• No admin. Administration tasks on EOEPCA. Deferred to a separate package.
• No Kubernetes / ArgoCD / Helm. Installing, upgrading, or configuring building blocks stays with helm, argocd, and the EOEPCA deployment-guide. The client assumes BBs are already running.
• No workflow authoring UI or CWL editor. It deploys and runs CWL / BPMN, but does not generate them. Same stance as the UI proposal (csa_requirements_ui.md §2.7 Development Environment Access).
• No heavy data analytics. Downloads, simple subsetting, and conversion are in scope; xarray/dask pipelines are user code. The library can be used inside such pipelines.
• Limited offline behaviour. Capability discovery and most commands require the platform to be reachable. We will not maintain a stale local cache of catalogue contents.
• Notifications / pub-sub, MLflow. deferred to later milestones; surfaces designed but not implemented in v1.

Proposed design choices:

• Layered. auth, platform discovery, and the shared HTTPX client are foundational and used by every other module. The each BB module is independent.
• CLI = thin shell over the library. With subcommands that call library methods and render the result.
• Typer for the CLI. Type hints become argument parsing for free, which keeps subcommand modules small and consistent with the library's typed signatures.
• HTTPX behind a synchronous façade. So if needed async surface can be added later without an entire rewrite.

Scope of MVP

• Hardcoded platform information (local config file)
• Ship pip install eoepca-client such that a new user can, in under a minute, run:

eoepca login
eoepca stac search --collection <id> --bbox -10,40,5,55 --limit 5
eoepca stac item add <collection> ./item.geojson
eoepca stac item rm  <collection> <item-id>

[pantierra]

And while doing a discovery I think, if there haven't been plans, already, it would be worth considering to add some platform discovery capabilities to EOEPCA. Like .well-known/eoepca.json. To avoid hard-coding of URLs of the endpoints of services deployed. The file ideally should be dynamically generated at deploy time from the active Helm/ArgoCD values (so it always reflects what is actually installed) and is overwritable by the operator for edge cases (custom hostnames, externally hosted BBs, disabled services). eoepca platform info <domain> fetches and prints this.

I probably would go with something defined already, maybe https://datatracker.ietf.org/doc/rfc9727/

[pantierra]

Came up with a first draft proposal for an api-catalog discovery: #16

This is relying on RFC9727 (api-catalog), RFC9264 (linkset) and JSON format, proposing some flexible rel structure to fit EOEPCA. You may want to directly check on the example file.