qapu-cli 0.1.0__tar.gz

qapu_cli-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: qapu-cli
+Version: 0.1.0
+Summary: CLI client for the Qapu API - built for the Hermes agent, but usable by anyone talking to api.ovoo.com.tr from outside the Swarm.
+Author: OVOO Technology
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer<1.0,>=0.12
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: rich<16.0,>=13.0
+
+# Qapu CLI
+
+A thin command-line client for the Qapu API (`api.ovoo.com.tr`), built for the Hermes agent (runs outside this Swarm, in a separate datacenter, and only ever talks to Qapu through this public API) - but usable by anything else that needs to script against Qapu from outside the private network.
+
+**Status: early development.** Gated by a temporary shared-secret header, not real auth yet - see "Auth (current placeholder)" below before using this against production.
+
+## Why a separate `tools/` project, not a `services/`
+
+This isn't a deployed backend service - it's a distributable client tool, installed wherever Hermes (or anyone else) runs. Kept in the same monorepo (per `CLAUDE.md`'s ADR-0001 - one repo, low context-switching for a 2-person team) rather than its own repo, since it's small and needs to stay in sync with the API it calls.
+
+## Install
+
+**Anyone with GitHub access to this (private) repo - no local clone needed**, `pip` installs straight from the `tools/cli` subdirectory over git:
+
+```bash
+pip install "git+ssh://git@github.com/ovoo-tech/qapu.git#subdirectory=tools/cli"
+```
+
+(needs an SSH key already authorized on your GitHub account for this repo - the usual case for anyone on the team. No SSH key set up? Use an HTTPS Personal Access Token instead: `pip install "git+https://<PAT>@github.com/ovoo-tech/qapu.git#subdirectory=tools/cli"`.)
+
+**Working on the CLI itself** (this repo already checked out) - editable install so local edits take effect immediately:
+
+```bash
+cd tools/cli
+pip install -e .
+```
+
+Either way installs a `qapu` command (see `pyproject.toml`'s `[project.scripts]`). This package has no dependency on the rest of the monorepo (`qapu_common` etc.) - it only ever talks to Qapu over HTTP, never imports it directly - which is exactly what makes the git-subdirectory install above work without cloning anything else.
+
+## Configuration
+
+| Env var | Purpose |
+|---|---|
+| `QAPU_API_URL` | Base URL. Defaults to `https://api.ovoo.com.tr`. Point at `http://localhost:8000` or an internal IP for local/dev testing. |
+| `QAPU_HERMES_KEY` | Shared-secret value for the `X-Hermes-Key` header - see "Auth" below. Required for every command except `qapu health`. |
+
+## Commands
+
+```bash
+qapu health                          # GET /health - no auth, quick connectivity check
+qapu device list                     # GET /hermes/devices - every device, bulk, as a table
+qapu device list --json              # same data, raw JSON
+qapu device list --status online     # only devices whose Update_Time moved in the last 30 min (see ONLINE_THRESHOLD_MINUTES in main.py - there's no real online/offline field, this is a heuristic)
+qapu device list --status offline
+qapu device list --model B107AA_R5   # case-insensitive substring match on Hardware.Model.Name
+qapu device list --limit 100
+qapu device get <device_id>          # GET /hermes/devices/{device_id} - one device, human-readable summary
+qapu device get <device_id> --json   # same data, raw JSON
+```
+
+Filtering (`--status`/`--model`/`--limit`) happens client-side in the CLI, not on the server - fine at the current fleet size, worth moving server-side (`GET /hermes/devices?status=...`) if it ever grows large enough to matter.
+
+## Auth (current placeholder - read this before pointing at production)
+
+`api.ovoo.com.tr` is genuinely public on the internet. The Hermes endpoints (`services/api/src/routers/hermes.py`) are gated by `require_hermes_key` (`services/api/src/dependencies.py`) - a single shared-secret string compared against the `X-Hermes-Key` header, checked via the `HERMES_SHARED_SECRET` env var on the API side. This is **deliberately temporary**: it exists only so the CLI/API plumbing could be built and tested end-to-end before the real auth design was ready, not because a shared secret is considered good enough long-term.
+
+**Real plan** (not built yet - phase 2, along with the score/comment table Hermes will eventually write to): an admin-role `hermes-qapu` account in the `users` table, with the CLI gaining a `qapu login` command that authenticates through the existing `JWT_Auth` flow every other Qapu client already uses, storing a short-lived token instead of a static shared secret. `client.py` is written so only it needs to change when that lands - nothing in `main.py` should need to know how auth works under the hood.
+
+Until then: `HERMES_SHARED_SECRET` fails closed (unset = every Hermes request rejected, never silently open), but a leaked shared-secret string is a much blunter credential than a scoped, revocable JWT - don't treat this as production-grade access control.
+
+## Running locally
+
+```bash
+QAPU_API_URL=http://localhost:8000 QAPU_HERMES_KEY=dev-secret python -m qapu_cli.main device list
+```
+
+(or, once installed via `pip install -e .`: just `qapu devices list` with the same env vars set.)

qapu_cli-0.1.0/README.md

@@ -0,0 +1,67 @@
+# Qapu CLI
+
+A thin command-line client for the Qapu API (`api.ovoo.com.tr`), built for the Hermes agent (runs outside this Swarm, in a separate datacenter, and only ever talks to Qapu through this public API) - but usable by anything else that needs to script against Qapu from outside the private network.
+
+**Status: early development.** Gated by a temporary shared-secret header, not real auth yet - see "Auth (current placeholder)" below before using this against production.
+
+## Why a separate `tools/` project, not a `services/`
+
+This isn't a deployed backend service - it's a distributable client tool, installed wherever Hermes (or anyone else) runs. Kept in the same monorepo (per `CLAUDE.md`'s ADR-0001 - one repo, low context-switching for a 2-person team) rather than its own repo, since it's small and needs to stay in sync with the API it calls.
+
+## Install
+
+**Anyone with GitHub access to this (private) repo - no local clone needed**, `pip` installs straight from the `tools/cli` subdirectory over git:
+
+```bash
+pip install "git+ssh://git@github.com/ovoo-tech/qapu.git#subdirectory=tools/cli"
+```
+
+(needs an SSH key already authorized on your GitHub account for this repo - the usual case for anyone on the team. No SSH key set up? Use an HTTPS Personal Access Token instead: `pip install "git+https://<PAT>@github.com/ovoo-tech/qapu.git#subdirectory=tools/cli"`.)
+
+**Working on the CLI itself** (this repo already checked out) - editable install so local edits take effect immediately:
+
+```bash
+cd tools/cli
+pip install -e .
+```
+
+Either way installs a `qapu` command (see `pyproject.toml`'s `[project.scripts]`). This package has no dependency on the rest of the monorepo (`qapu_common` etc.) - it only ever talks to Qapu over HTTP, never imports it directly - which is exactly what makes the git-subdirectory install above work without cloning anything else.
+
+## Configuration
+
+| Env var | Purpose |
+|---|---|
+| `QAPU_API_URL` | Base URL. Defaults to `https://api.ovoo.com.tr`. Point at `http://localhost:8000` or an internal IP for local/dev testing. |
+| `QAPU_HERMES_KEY` | Shared-secret value for the `X-Hermes-Key` header - see "Auth" below. Required for every command except `qapu health`. |
+
+## Commands
+
+```bash
+qapu health                          # GET /health - no auth, quick connectivity check
+qapu device list                     # GET /hermes/devices - every device, bulk, as a table
+qapu device list --json              # same data, raw JSON
+qapu device list --status online     # only devices whose Update_Time moved in the last 30 min (see ONLINE_THRESHOLD_MINUTES in main.py - there's no real online/offline field, this is a heuristic)
+qapu device list --status offline
+qapu device list --model B107AA_R5   # case-insensitive substring match on Hardware.Model.Name
+qapu device list --limit 100
+qapu device get <device_id>          # GET /hermes/devices/{device_id} - one device, human-readable summary
+qapu device get <device_id> --json   # same data, raw JSON
+```
+
+Filtering (`--status`/`--model`/`--limit`) happens client-side in the CLI, not on the server - fine at the current fleet size, worth moving server-side (`GET /hermes/devices?status=...`) if it ever grows large enough to matter.
+
+## Auth (current placeholder - read this before pointing at production)
+
+`api.ovoo.com.tr` is genuinely public on the internet. The Hermes endpoints (`services/api/src/routers/hermes.py`) are gated by `require_hermes_key` (`services/api/src/dependencies.py`) - a single shared-secret string compared against the `X-Hermes-Key` header, checked via the `HERMES_SHARED_SECRET` env var on the API side. This is **deliberately temporary**: it exists only so the CLI/API plumbing could be built and tested end-to-end before the real auth design was ready, not because a shared secret is considered good enough long-term.
+
+**Real plan** (not built yet - phase 2, along with the score/comment table Hermes will eventually write to): an admin-role `hermes-qapu` account in the `users` table, with the CLI gaining a `qapu login` command that authenticates through the existing `JWT_Auth` flow every other Qapu client already uses, storing a short-lived token instead of a static shared secret. `client.py` is written so only it needs to change when that lands - nothing in `main.py` should need to know how auth works under the hood.
+
+Until then: `HERMES_SHARED_SECRET` fails closed (unset = every Hermes request rejected, never silently open), but a leaked shared-secret string is a much blunter credential than a scoped, revocable JWT - don't treat this as production-grade access control.
+
+## Running locally
+
+```bash
+QAPU_API_URL=http://localhost:8000 QAPU_HERMES_KEY=dev-secret python -m qapu_cli.main device list
+```
+
+(or, once installed via `pip install -e .`: just `qapu devices list` with the same env vars set.)

qapu_cli-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "qapu-cli"
+version = "0.1.0"
+description = "CLI client for the Qapu API - built for the Hermes agent, but usable by anyone talking to api.ovoo.com.tr from outside the Swarm."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "OVOO Technology" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "typer>=0.12,<1.0",
+    "httpx>=0.27,<1.0",
+    "rich>=13.0,<16.0",
+]
+
+[project.scripts]
+qapu = "qapu_cli.main:app"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["qapu_cli*"]

qapu_cli-0.1.0/qapu_cli/client.py

@@ -0,0 +1,71 @@
+# Thin HTTP client wrapping calls to the Qapu API (api.ovoo.com.tr) -
+# every command in main.py goes through this, so there's exactly one place
+# that knows about base URLs, headers, and error handling.
+#
+# Auth is a placeholder for now (X-Hermes-Key shared-secret header, see
+# services/api/src/dependencies.py's require_hermes_key) - this file is
+# where a real login/JWT flow will go once the "hermes-qapu" admin account
+# exists. Callers elsewhere in this package shouldn't need to change when
+# that happens, only this file.
+
+import os
+import sys
+from typing import Any
+
+import httpx
+
+# Config - env vars, no config file yet (keep it simple until there's a
+# real reason not to: multiple environments, saved credentials, etc.)
+DEFAULT_BASE_URL = "https://api.ovoo.com.tr"
+
+
+def _base_url() -> str:
+
+	# Resolve Base URL from Environment, Falling Back to Production
+	return os.getenv("QAPU_API_URL", DEFAULT_BASE_URL).rstrip("/")
+
+
+def _headers() -> dict[str, str]:
+
+	# Resolve the Shared-Secret Header - Required for Every Hermes Endpoint
+	key = os.getenv("QAPU_HERMES_KEY")
+
+	# Fail Clearly, Not with a Confusing 401 from the Server
+	if not key:
+		print("Error: QAPU_HERMES_KEY environment variable is not set.", file=sys.stderr)
+		raise SystemExit(1)
+
+	# Return Headers
+	return {"X-Hermes-Key": key}
+
+
+def get(path: str, params: dict[str, Any] | None = None) -> Any:
+
+	# Build Full URL
+	url = f"{_base_url()}{path}"
+
+	# Try the Request
+	try:
+
+		# Issue the GET Request
+		response = httpx.get(url, headers=_headers(), params=params, timeout=30)
+
+		# Raise on a Non-2xx Status
+		response.raise_for_status()
+
+		# Return Decoded JSON
+		return response.json()
+
+	# Catch and Re-Report HTTP Errors Clearly
+	except httpx.HTTPStatusError as e:
+
+		# Print a Clear Error and Exit
+		print(f"Error: {e.response.status_code} from {url} - {e.response.text}", file=sys.stderr)
+		raise SystemExit(1)
+
+	# Catch and Re-Report Connection Errors Clearly
+	except httpx.RequestError as e:
+
+		# Print a Clear Error and Exit
+		print(f"Error: could not reach {url} - {e}", file=sys.stderr)
+		raise SystemExit(1)

qapu_cli-0.1.0/qapu_cli/main.py

@@ -0,0 +1,296 @@
+# Qapu CLI - built for the Hermes agent's hourly per-device pull, but
+# usable by anyone who needs to talk to the Qapu API (api.ovoo.com.tr)
+# from outside the Swarm. See client.py for the HTTP layer, README.md for
+# setup and the auth placeholder this currently relies on.
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+import httpx
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from qapu_cli import client
+
+app = typer.Typer(no_args_is_help=True, help="Qapu API client CLI.")
+device_app = typer.Typer(no_args_is_help=True, help="Device-related commands.")
+app.add_typer(device_app, name="device")
+
+console = Console()
+
+# There Is No Real "Online/Offline" Field on a Device - Derived Here from
+# How Recently `Update_Time` Moved, Since `data`'s process_message() Calls
+# Device.update() on Every Packet a Device Sends (Confirmed via
+# database/models.py's `onupdate=func.now()` on that column). A device
+# whose metadata was hand-edited recently would also count as "Online" by
+# this measure - an accepted, minor false positive, not a real signal.
+ONLINE_THRESHOLD_MINUTES = 30
+
+
+# Quick, No-Auth Connectivity Check - Confirms the CLI can Reach the API
+# at all, Independent of the Hermes Key, Before Debugging Anything Else
+@app.command()
+def health():
+	"""Check that the configured Qapu API is reachable (GET /health, no auth required)."""
+
+	# Build the Health URL Directly - This One Endpoint Genuinely Has no Auth
+	url = f"{client._base_url()}/health"
+
+	# Try the Request
+	try:
+
+		# Issue the GET Request
+		response = httpx.get(url, timeout=10)
+
+		# Raise on a Non-2xx Status
+		response.raise_for_status()
+
+		# Print the Result
+		typer.echo(json.dumps(response.json(), indent=2))
+
+	# Catch and Report Any Failure
+	except httpx.HTTPError as e:
+
+		# Print a Clear Error and Exit
+		typer.echo(f"Error: {e}", err=True)
+		raise typer.Exit(code=1)
+
+
+# Resolve Whether a Device Counts as "Online" by the Update_Time Heuristic
+def _is_online(device: dict[str, Any]) -> bool:
+
+	# Resolve the Raw Timestamp String
+	update_time_raw = device.get("Update_Time")
+
+	# No Timestamp at all - Treat as Offline
+	if not update_time_raw:
+		return False
+
+	# Try to Parse and Compare
+	try:
+
+		# Parse ISO Timestamp
+		update_time = datetime.fromisoformat(update_time_raw)
+
+		# Compare Against the Threshold
+		age_minutes = (datetime.now(timezone.utc) - update_time.astimezone(timezone.utc)).total_seconds() / 60
+		return age_minutes <= ONLINE_THRESHOLD_MINUTES
+
+	# Unparseable Timestamp - Treat as Offline Rather than Guessing
+	except (ValueError, TypeError):
+		return False
+
+
+# Render Update_Time as a Human-Friendly Relative String ("Last Connection")
+def _relative_time(raw: Optional[str]) -> str:
+
+	# No Timestamp at all
+	if not raw:
+		return "-"
+
+	# Try to Parse and Format
+	try:
+
+		# Parse ISO Timestamp
+		update_time = datetime.fromisoformat(raw).astimezone(timezone.utc)
+
+		# Compute Elapsed Seconds
+		elapsed = (datetime.now(timezone.utc) - update_time).total_seconds()
+
+		# Format the Largest Sensible Unit - Always Minutes-or-Coarser, No
+		# "Just Now" Bucket (a Fresh Connection Shows as "0 dk önce")
+		if elapsed < 3600:
+			return f"{int(elapsed // 60)} dk önce"
+		if elapsed < 86400:
+			return f"{int(elapsed // 3600)} sa önce"
+		return f"{int(elapsed // 86400)} gün önce"
+
+	# Unparseable Timestamp
+	except (ValueError, TypeError):
+		return "-"
+
+
+# List Every Device (Bulk, No Ownership Scoping) - the Endpoint Hermes'
+# Hourly Pull Actually Uses
+# Default Page Size for the Interactive Table View - Only Applies When the
+# Caller Didn't Pass an Explicit --limit (an Explicit Limit Means They
+# Already Know How Many They Want, no Need to Also Paginate That)
+DEFAULT_PAGE_SIZE = 20
+
+
+# Render One Page of Devices as a Rich Table
+def _build_device_table(devices: list[dict[str, Any]]) -> Table:
+
+	# Build the Table
+	table = Table(show_header=True, header_style="bold")
+	table.add_column("DEVICE ID")
+	table.add_column("NAME")
+	table.add_column("STATUS")
+	table.add_column("FIRMWARE")
+	table.add_column("LAST CONNECTION")
+
+	# Populate Rows
+	for d in devices:
+
+		# Resolve Each Column, Defensively - Any of These Can Be Missing
+		device_id = d.get("ID") or "-"
+		name = d.get("Name") or "-"
+		online = _is_online(d)
+		status_label = "[green]Online[/green]" if online else "[red]Offline[/red]"
+		firmware = d.get("Version") or "-"
+		last_connection = _relative_time(d.get("Update_Time"))
+
+		# Add the Row
+		table.add_row(device_id, name, status_label, firmware, last_connection)
+
+	# Return the Table
+	return table
+
+
+@device_app.command("list")
+def device_list(
+	as_json: bool = typer.Option(False, "--json", help="Print raw JSON instead of a table. Always prints everything at once, no pagination - meant for scripting/Hermes, not a human terminal."),
+	status: Optional[str] = typer.Option(None, "--status", help="Filter by connectivity: 'online' or 'offline' (see ONLINE_THRESHOLD_MINUTES)."),
+	model: Optional[str] = typer.Option(None, "--model", help="Filter by hardware model name (case-insensitive substring match)."),
+	limit: Optional[int] = typer.Option(None, "--limit", help="Cap the number of devices shown. Given explicitly, this replaces the default interactive pagination - you get exactly this many, once, no prompt."),
+):
+	"""List every device Qapu knows about (GET /hermes/devices)."""
+
+	# Fetch the Full Device List
+	devices: list[dict[str, Any]] = client.get("/hermes/devices")
+
+	# Apply the Status Filter, if Any
+	if status:
+
+		# Normalize the Requested Value
+		wanted_online = status.strip().lower() == "online"
+
+		# Filter the List
+		devices = [d for d in devices if _is_online(d) == wanted_online]
+
+	# Apply the Model Filter, if Any
+	if model:
+
+		# Filter by Case-Insensitive Substring Match on the Model Name
+		needle = model.strip().lower()
+		devices = [d for d in devices if needle in ((d.get("Hardware") or {}).get("Model") or {}).get("Name", "").lower()]
+
+	# Apply an Explicit Limit, if Any - Caps the List Outright, no Pagination
+	if limit is not None:
+		devices = devices[:limit]
+
+	# JSON Output - Everything at Once, Never Paginated (Scripting/Hermes Use)
+	if as_json:
+
+		# Print Raw JSON
+		typer.echo(json.dumps(devices, indent=2))
+		return
+
+	# An Explicit --limit Already Capped the List Above - Print it in One Go
+	if limit is not None:
+
+		# Print the Table
+		console.print(_build_device_table(devices))
+
+		# Print the Summary Line
+		console.print(f"\nToplam: {len(devices)} cihaz")
+		return
+
+	# No Explicit Limit - Paginate Interactively, DEFAULT_PAGE_SIZE at a Time
+	total = len(devices)
+	offset = 0
+
+	# Loop Until Every Device Has Been Shown or the User Quits
+	while offset < total:
+
+		# Slice Out This Page
+		page = devices[offset:offset + DEFAULT_PAGE_SIZE]
+		offset += len(page)
+
+		# Print This Page's Table
+		console.print(_build_device_table(page))
+
+		# Print Where We Are
+		console.print(f"\n{offset}/{total} cihaz gösterildi.")
+
+		# Stop if That Was the Last Page - no Prompt Needed
+		if offset >= total:
+			break
+
+		# Ask Whether to Continue
+		answer = typer.prompt("Devam etmek için Enter'a bas (çıkmak için q)", default="", show_default=False)
+
+		# Stop on 'q'/'quit'/'exit'
+		if answer.strip().lower() in ("q", "quit", "exit"):
+			break
+
+
+# Get One Device's Full Detail
+@device_app.command("get")
+def device_get(
+	device_id: str = typer.Argument(..., help="Device ID."),
+	as_json: bool = typer.Option(False, "--json", help="Print raw JSON instead of a human-readable summary."),
+):
+	"""Get one device's detail (GET /hermes/devices/{device_id})."""
+
+	# Fetch the Device Detail
+	d: dict[str, Any] = client.get(f"/hermes/devices/{device_id}")
+
+	# JSON Output - Nothing Further to Format
+	if as_json:
+
+		# Print Raw JSON
+		typer.echo(json.dumps(d, indent=2))
+		return
+
+	# Resolve Nested Fields Defensively - Any of These Can Be Missing
+	owner = d.get("Owner") or {}
+	project = d.get("Project") or {}
+	device_status = d.get("Status") or {}
+	hardware = d.get("Hardware") or {}
+	manufacturer = hardware.get("Manufacturer") or {}
+	model = hardware.get("Model") or {}
+	modem = hardware.get("Modem") or {}
+	sim = d.get("SIM") or {}
+	register = d.get("Register") or {}
+	online = _is_online(d)
+	status_label = "[green]Online[/green]" if online else "[red]Offline[/red]"
+
+	# Build a Two-Column FIELD/VALUE Table - Cleaner for a Single Nested
+	# Object than Trying to Force it into the List Table's Row Shape
+	table = Table(show_header=False, box=None)
+	table.add_column("FIELD", style="bold")
+	table.add_column("VALUE")
+
+	rows = [
+		("Device ID", d.get("ID") or "-"),
+		("Name", d.get("Name") or "-"),
+		("Description", d.get("Description") or "-"),
+		("Status", status_label),
+		("Firmware", d.get("Version") or "-"),
+		("Last Connection", _relative_time(d.get("Update_Time"))),
+		("Owner", owner.get("Name") or (str(owner.get("ID")) if owner.get("ID") is not None else "-")),
+		("Project", project.get("Name") or "-"),
+		("Device Status", device_status.get("Name") or "-"),
+		("Manufacturer", manufacturer.get("Name") or "-"),
+		("Model", model.get("Name") or "-"),
+		("IMEI", modem.get("IMEI") or "-"),
+		("SIM ICCID", sim.get("ICCID") or "-"),
+		("Register (Status/Stop/Publish)", f"{register.get('Status', '-')} / {register.get('Stop', '-')} / {register.get('Publish', '-')}"),
+		("Created", d.get("Creation_Time") or "-"),
+	]
+
+	# Populate Rows
+	for field, value in rows:
+		table.add_row(field, str(value))
+
+	# Print the Table
+	console.print(table)
+
+
+if __name__ == "__main__":
+
+	# Run the Typer App
+	app()

qapu_cli-0.1.0/qapu_cli.egg-info/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: qapu-cli
+Version: 0.1.0
+Summary: CLI client for the Qapu API - built for the Hermes agent, but usable by anyone talking to api.ovoo.com.tr from outside the Swarm.
+Author: OVOO Technology
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer<1.0,>=0.12
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: rich<16.0,>=13.0
+
+# Qapu CLI
+
+A thin command-line client for the Qapu API (`api.ovoo.com.tr`), built for the Hermes agent (runs outside this Swarm, in a separate datacenter, and only ever talks to Qapu through this public API) - but usable by anything else that needs to script against Qapu from outside the private network.
+
+**Status: early development.** Gated by a temporary shared-secret header, not real auth yet - see "Auth (current placeholder)" below before using this against production.
+
+## Why a separate `tools/` project, not a `services/`
+
+This isn't a deployed backend service - it's a distributable client tool, installed wherever Hermes (or anyone else) runs. Kept in the same monorepo (per `CLAUDE.md`'s ADR-0001 - one repo, low context-switching for a 2-person team) rather than its own repo, since it's small and needs to stay in sync with the API it calls.
+
+## Install
+
+**Anyone with GitHub access to this (private) repo - no local clone needed**, `pip` installs straight from the `tools/cli` subdirectory over git:
+
+```bash
+pip install "git+ssh://git@github.com/ovoo-tech/qapu.git#subdirectory=tools/cli"
+```
+
+(needs an SSH key already authorized on your GitHub account for this repo - the usual case for anyone on the team. No SSH key set up? Use an HTTPS Personal Access Token instead: `pip install "git+https://<PAT>@github.com/ovoo-tech/qapu.git#subdirectory=tools/cli"`.)
+
+**Working on the CLI itself** (this repo already checked out) - editable install so local edits take effect immediately:
+
+```bash
+cd tools/cli
+pip install -e .
+```
+
+Either way installs a `qapu` command (see `pyproject.toml`'s `[project.scripts]`). This package has no dependency on the rest of the monorepo (`qapu_common` etc.) - it only ever talks to Qapu over HTTP, never imports it directly - which is exactly what makes the git-subdirectory install above work without cloning anything else.
+
+## Configuration
+
+| Env var | Purpose |
+|---|---|
+| `QAPU_API_URL` | Base URL. Defaults to `https://api.ovoo.com.tr`. Point at `http://localhost:8000` or an internal IP for local/dev testing. |
+| `QAPU_HERMES_KEY` | Shared-secret value for the `X-Hermes-Key` header - see "Auth" below. Required for every command except `qapu health`. |
+
+## Commands
+
+```bash
+qapu health                          # GET /health - no auth, quick connectivity check
+qapu device list                     # GET /hermes/devices - every device, bulk, as a table
+qapu device list --json              # same data, raw JSON
+qapu device list --status online     # only devices whose Update_Time moved in the last 30 min (see ONLINE_THRESHOLD_MINUTES in main.py - there's no real online/offline field, this is a heuristic)
+qapu device list --status offline
+qapu device list --model B107AA_R5   # case-insensitive substring match on Hardware.Model.Name
+qapu device list --limit 100
+qapu device get <device_id>          # GET /hermes/devices/{device_id} - one device, human-readable summary
+qapu device get <device_id> --json   # same data, raw JSON
+```
+
+Filtering (`--status`/`--model`/`--limit`) happens client-side in the CLI, not on the server - fine at the current fleet size, worth moving server-side (`GET /hermes/devices?status=...`) if it ever grows large enough to matter.
+
+## Auth (current placeholder - read this before pointing at production)
+
+`api.ovoo.com.tr` is genuinely public on the internet. The Hermes endpoints (`services/api/src/routers/hermes.py`) are gated by `require_hermes_key` (`services/api/src/dependencies.py`) - a single shared-secret string compared against the `X-Hermes-Key` header, checked via the `HERMES_SHARED_SECRET` env var on the API side. This is **deliberately temporary**: it exists only so the CLI/API plumbing could be built and tested end-to-end before the real auth design was ready, not because a shared secret is considered good enough long-term.
+
+**Real plan** (not built yet - phase 2, along with the score/comment table Hermes will eventually write to): an admin-role `hermes-qapu` account in the `users` table, with the CLI gaining a `qapu login` command that authenticates through the existing `JWT_Auth` flow every other Qapu client already uses, storing a short-lived token instead of a static shared secret. `client.py` is written so only it needs to change when that lands - nothing in `main.py` should need to know how auth works under the hood.
+
+Until then: `HERMES_SHARED_SECRET` fails closed (unset = every Hermes request rejected, never silently open), but a leaked shared-secret string is a much blunter credential than a scoped, revocable JWT - don't treat this as production-grade access control.
+
+## Running locally
+
+```bash
+QAPU_API_URL=http://localhost:8000 QAPU_HERMES_KEY=dev-secret python -m qapu_cli.main device list
+```
+
+(or, once installed via `pip install -e .`: just `qapu devices list` with the same env vars set.)

qapu_cli-0.1.0/qapu_cli.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+qapu_cli/__init__.py
+qapu_cli/client.py
+qapu_cli/main.py
+qapu_cli.egg-info/PKG-INFO
+qapu_cli.egg-info/SOURCES.txt
+qapu_cli.egg-info/dependency_links.txt
+qapu_cli.egg-info/entry_points.txt
+qapu_cli.egg-info/requires.txt
+qapu_cli.egg-info/top_level.txt

qapu_cli-0.1.0/qapu_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

qapu_cli-0.1.0/qapu_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+qapu = qapu_cli.main:app

qapu_cli-0.1.0/qapu_cli.egg-info/requires.txt

@@ -0,0 +1,3 @@
+typer<1.0,>=0.12
+httpx<1.0,>=0.27
+rich<16.0,>=13.0

qapu_cli-0.1.0/qapu_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+qapu_cli

qapu_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+