geopera-cli 0.1.0__tar.gz

geopera_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: Publish CLI (geopera-cli)
+
+# Publishes geopera-cli to PyPI on a tag like `v0.1.0`.
+# Uses PyPI Trusted Publishing (OIDC) — no stored token.
+#
+# One-time PyPI setup: pypi.org -> the geopera-cli project -> Publishing -> add a GitHub
+# Actions publisher (repo geo-pera/geopera-cli, workflow publish.yml, environment "pypi").
+# First publish may use PyPI's "pending publisher" flow.
+#
+# NOTE: geopera-cli depends on the `geopera` SDK, so publish `geopera` to PyPI first —
+# otherwise `pip install geopera-cli` can't resolve its dependency for end users.
+#
+# Release: bump `version` in pyproject.toml, then:
+#   git tag vX.Y.Z && git push origin vX.Y.Z
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          twine check dist/*
+
+      - name: Sanity-check the package metadata + entry point
+        # Doesn't install runtime deps (the `geopera` SDK may not be on PyPI yet) — just
+        # confirms the wheel declares the `geopera` console script.
+        run: |
+          python - <<'PY'
+          import zipfile, glob, sys
+          whl = glob.glob("dist/*.whl")[0]
+          names = zipfile.ZipFile(whl).namelist()
+          entry = [n for n in names if n.endswith("entry_points.txt")]
+          txt = zipfile.ZipFile(whl).read(entry[0]).decode() if entry else ""
+          assert "geopera" in txt and "geopera_cli" in txt, f"missing console_scripts entry: {txt!r}"
+          print("ok: wheel declares the `geopera` console script")
+          PY
+
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

geopera_cli-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.eggs/
+build/
+dist/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Local credentials must NEVER be committed (they live in ~/.config/geopera).
+credentials.json
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

geopera_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geopera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geopera_cli-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: geopera-cli
+Version: 0.1.0
+Summary: Command-line interface for the Geopera geospatial data platform
+Project-URL: Homepage, https://docs.geopera.com
+Project-URL: Documentation, https://docs.geopera.com/cli
+Project-URL: Source, https://github.com/geo-pera/geopera-cli
+Author-email: Geopera <support@geopera.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,earth-observation,geopera,geospatial,satellite,stac
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: geopera>=2.0.0
+Requires-Dist: httpx<0.29.0,>=0.23.1
+Requires-Dist: typer[all]>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# geopera-cli
+
+Command-line interface for the [Geopera](https://docs.geopera.com) geospatial
+data platform.
+
+`geopera-cli` is a **thin auth + dispatch shell** over the published
+[`geopera` Python SDK](https://github.com/geo-pera/geopera-python). The only
+logic that lives in the CLI is authentication — the OAuth device flow, token
+refresh, and the choice between a `Bearer` token and an `X-API-Key` header.
+Every actual capability is reached through the generic API endpoint
+`POST /v1/op/{operation_id}`, so any of the ~227 operations is callable with no
+per-command code, and a new backend operation is instantly usable as
+`geopera op <new.op>` with zero CLI changes.
+
+## Install
+
+```bash
+pip install geopera-cli
+```
+
+This pulls in the `geopera` SDK, `typer`, and `httpx`.
+
+## Quick start
+
+```bash
+# Sign in (opens your browser; RFC 8628 device flow)
+geopera login
+
+# Who am I?
+geopera whoami
+
+# Price-preview an order (generic op dispatch)
+geopera op orders.estimate '{"aoi": {...}, "product": "..."}'
+
+# Search across every registered public data source
+geopera op catalog.federated_search '{"bbox": [...], "datetime": "..."}'
+
+# List every available operation id
+geopera op --list
+
+# Curated alias with table output
+geopera orders list
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `geopera login` | Device-flow login (default). `--api-key KEY` stores a key instead (`-` reads from stdin). `--api-url URL`, `--no-browser`, `--scope`. |
+| `geopera logout` | Clear the active profile's stored credentials (best-effort OAuth logout). |
+| `geopera whoami` | Show principal / org / scope (validates the session). `--json` for raw output. |
+| `geopera op OPERATION_ID [JSON]` | Generic operation dispatch. Body from positional arg, `--file`, or `-` (stdin). `--list` enumerates operations. |
+| `geopera orders list` | Curated alias over `op orders.list` with table formatting. |
+
+Global flags `--profile NAME` (env `GEOPERA_PROFILE`) and `--api-url URL`
+(env `GEOPERA_API_URL`) are accepted on every command.
+
+## Authentication
+
+### Device flow (default)
+
+`geopera login` performs the OAuth 2.0 Device Authorization Grant
+([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)) with PKCE:
+
+1. Requests a device + user code from
+   `{api_url}/realms/public/protocol/openid-connect/auth/device`.
+2. Prints the user code and opens the verification URL in your browser
+   (skip with `--no-browser`).
+3. Polls the token endpoint until you approve, then stores the access and
+   refresh tokens.
+
+Access tokens are refreshed automatically — proactively when within 30s of
+expiry, and reactively on any `401` — using the stored refresh token. The
+backend rotates the refresh token, so both tokens are rewritten on each
+refresh.
+
+### API key (headless)
+
+```bash
+geopera login --api-key gpra_xxxxxxxx
+# or, keeping the key out of shell history:
+printf '%s' "$GEOPERA_KEY" | geopera login --api-key -
+```
+
+API keys are sent as `X-API-Key`, which the Geopera API accepts on every
+authenticated endpoint.
+
+### Profiles
+
+Multiple identities are namespaced by profile:
+
+```bash
+geopera login --profile staging --api-url https://staging.api.geopera.com
+geopera --help                      # default profile
+GEOPERA_PROFILE=staging geopera whoami
+geopera whoami --profile staging
+```
+
+## Credential store
+
+Credentials live in `~/.config/geopera/credentials.json` (directory `0700`,
+file `0600`). Each top-level key is a profile:
+
+```json
+{
+  "default": {
+    "api_url": "https://api.geopera.com",
+    "auth": {
+      "type": "oauth",
+      "access_token": "...",
+      "refresh_token": "...",
+      "expires_at": 1750000000,
+      "scope": "openid profile",
+      "issuer": "https://api.geopera.com"
+    }
+  }
+}
+```
+
+For an API key profile the `auth` block is
+`{"type": "api_key", "api_key": "gpra_..."}`.
+
+### Environment overrides
+
+- `GEOPERA_API_URL` — base URL override (below `--api-url`, above the stored value).
+- `GEOPERA_PROFILE` — active profile name.
+- `GEOPERA_API_TOKEN` — opaque bearer/API-key for ephemeral (e.g. CI) use,
+  bypassing the store. A value starting with `gpra_` is treated as an API key.
+
+## Configuration precedence
+
+API base URL: `--api-url` flag → `GEOPERA_API_URL` → stored `api_url` →
+`https://api.geopera.com`.
+
+## License
+
+[MIT](./LICENSE)

geopera_cli-0.1.0/README.md

@@ -0,0 +1,137 @@
+# geopera-cli
+
+Command-line interface for the [Geopera](https://docs.geopera.com) geospatial
+data platform.
+
+`geopera-cli` is a **thin auth + dispatch shell** over the published
+[`geopera` Python SDK](https://github.com/geo-pera/geopera-python). The only
+logic that lives in the CLI is authentication — the OAuth device flow, token
+refresh, and the choice between a `Bearer` token and an `X-API-Key` header.
+Every actual capability is reached through the generic API endpoint
+`POST /v1/op/{operation_id}`, so any of the ~227 operations is callable with no
+per-command code, and a new backend operation is instantly usable as
+`geopera op <new.op>` with zero CLI changes.
+
+## Install
+
+```bash
+pip install geopera-cli
+```
+
+This pulls in the `geopera` SDK, `typer`, and `httpx`.
+
+## Quick start
+
+```bash
+# Sign in (opens your browser; RFC 8628 device flow)
+geopera login
+
+# Who am I?
+geopera whoami
+
+# Price-preview an order (generic op dispatch)
+geopera op orders.estimate '{"aoi": {...}, "product": "..."}'
+
+# Search across every registered public data source
+geopera op catalog.federated_search '{"bbox": [...], "datetime": "..."}'
+
+# List every available operation id
+geopera op --list
+
+# Curated alias with table output
+geopera orders list
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `geopera login` | Device-flow login (default). `--api-key KEY` stores a key instead (`-` reads from stdin). `--api-url URL`, `--no-browser`, `--scope`. |
+| `geopera logout` | Clear the active profile's stored credentials (best-effort OAuth logout). |
+| `geopera whoami` | Show principal / org / scope (validates the session). `--json` for raw output. |
+| `geopera op OPERATION_ID [JSON]` | Generic operation dispatch. Body from positional arg, `--file`, or `-` (stdin). `--list` enumerates operations. |
+| `geopera orders list` | Curated alias over `op orders.list` with table formatting. |
+
+Global flags `--profile NAME` (env `GEOPERA_PROFILE`) and `--api-url URL`
+(env `GEOPERA_API_URL`) are accepted on every command.
+
+## Authentication
+
+### Device flow (default)
+
+`geopera login` performs the OAuth 2.0 Device Authorization Grant
+([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)) with PKCE:
+
+1. Requests a device + user code from
+   `{api_url}/realms/public/protocol/openid-connect/auth/device`.
+2. Prints the user code and opens the verification URL in your browser
+   (skip with `--no-browser`).
+3. Polls the token endpoint until you approve, then stores the access and
+   refresh tokens.
+
+Access tokens are refreshed automatically — proactively when within 30s of
+expiry, and reactively on any `401` — using the stored refresh token. The
+backend rotates the refresh token, so both tokens are rewritten on each
+refresh.
+
+### API key (headless)
+
+```bash
+geopera login --api-key gpra_xxxxxxxx
+# or, keeping the key out of shell history:
+printf '%s' "$GEOPERA_KEY" | geopera login --api-key -
+```
+
+API keys are sent as `X-API-Key`, which the Geopera API accepts on every
+authenticated endpoint.
+
+### Profiles
+
+Multiple identities are namespaced by profile:
+
+```bash
+geopera login --profile staging --api-url https://staging.api.geopera.com
+geopera --help                      # default profile
+GEOPERA_PROFILE=staging geopera whoami
+geopera whoami --profile staging
+```
+
+## Credential store
+
+Credentials live in `~/.config/geopera/credentials.json` (directory `0700`,
+file `0600`). Each top-level key is a profile:
+
+```json
+{
+  "default": {
+    "api_url": "https://api.geopera.com",
+    "auth": {
+      "type": "oauth",
+      "access_token": "...",
+      "refresh_token": "...",
+      "expires_at": 1750000000,
+      "scope": "openid profile",
+      "issuer": "https://api.geopera.com"
+    }
+  }
+}
+```
+
+For an API key profile the `auth` block is
+`{"type": "api_key", "api_key": "gpra_..."}`.
+
+### Environment overrides
+
+- `GEOPERA_API_URL` — base URL override (below `--api-url`, above the stored value).
+- `GEOPERA_PROFILE` — active profile name.
+- `GEOPERA_API_TOKEN` — opaque bearer/API-key for ephemeral (e.g. CI) use,
+  bypassing the store. A value starting with `gpra_` is treated as an API key.
+
+## Configuration precedence
+
+API base URL: `--api-url` flag → `GEOPERA_API_URL` → stored `api_url` →
+`https://api.geopera.com`.
+
+## License
+
+[MIT](./LICENSE)

geopera_cli-0.1.0/geopera_cli/__init__.py

@@ -0,0 +1,8 @@
+"""geopera-cli — command-line interface for the Geopera platform.
+
+A thin auth + dispatch shell over the published `geopera` SDK. Every capability
+is reached through /v1/op/{operation_id}; the only CLI-resident logic is auth
+(device flow, token refresh, and the Bearer / X-API-Key choice).
+"""
+
+__version__ = "0.1.0"