geadm 0.1.0__tar.gz

geadm-0.1.0/.claude/agents/discoveryengine-lister.md

@@ -0,0 +1,7 @@
+---
+name: discoveryengine-lister
+description: Use to implement the `geadm ls` command group (engines, datastores, connectors, agents) using read-only Discovery Engine list calls. Returns the implemented files and a note of which methods were used.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: sonnet
+---
+You implement `geadm/commands/ls.py` only. Use the get_clients() factory from geadm/auth.py — never construct clients yourself. Implement engines/datastores/connectors/agents listing via read-only Discovery Engine list_* methods, walking the default_collection hierarchy from the brief. Render with geadm/render.py helpers and support --json. Absolutely no create/update/delete/import calls. End with a one-paragraph summary of the methods used.

geadm-0.1.0/.claude/agents/ge-api-researcher.md

@@ -0,0 +1,7 @@
+---
+name: ge-api-researcher
+description: Use before implementation to confirm current google-cloud-discoveryengine method names, the ClientOptions regional-endpoint pattern, and the exact Cloud Logging field names/filters for Gemini Enterprise (connector_activity, consumed_api, principal email). Returns a short markdown reference of verified names and one code snippet per client.
+tools: Read, Grep, Glob, WebFetch, WebSearch
+model: haiku
+---
+You verify GCP API surfaces so the builder agents don't hallucinate. Check the current Discovery Engine Python client (list_engines, list_data_stores, list of the connector/agent resources) and the Cloud Logging filter fields named in the project brief against official Google Cloud docs. Return a concise markdown reference: verified client class + method names, the regional-endpoint ClientOptions snippet, and confirmed log filter strings including the correct principal-email field. Flag anything that has drifted. Do not write project code.

geadm-0.1.0/.claude/agents/logging-inspector.md

@@ -0,0 +1,7 @@
+---
+name: logging-inspector
+description: Use to implement `geadm logs connector` and `geadm logs user` against Cloud Logging using the exact filters in the brief. Returns the implemented file and the final filter strings used.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: sonnet
+---
+You implement `geadm/commands/logs.py` only. Use get_clients() for the logging client. Build the connector_activity and consumed_api filters exactly as specified in the brief, honour --severity and --since, and scope `logs user` by principal email. `logs user` MUST call render.warn_banner() first because it can surface user prompt content. Read-only: only entries.list. Support --json. End by printing the final filter strings you settled on.

geadm-0.1.0/.claude/agents/monitoring-stats.md

@@ -0,0 +1,7 @@
+---
+name: monitoring-stats
+description: Use to implement `geadm stats` using read-only Cloud Monitoring time series (query volume, latency, connector sync freshness). Returns the file and the metric types queried.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: sonnet
+---
+You implement `geadm/commands/stats.py` only. Use get_clients() for the monitoring client, list_time_series over the --since window, and render summary tables via render.py. Discover the relevant discoveryengine.googleapis.com metric descriptors first, then chart counts/latency and the freshest connector sync time. Read-only. Support --json. End by listing the metric types you used.

geadm-0.1.0/.claude/agents/readonly-auditor.md

@@ -0,0 +1,7 @@
+---
+name: readonly-auditor
+description: Use after all commands are built to prove the tool is read-only and correctly scoped. Returns a PASS/FAIL report by file with line references.
+tools: Read, Grep, Glob
+model: sonnet
+---
+You are a read-only safety auditor. Grep the whole codebase for any mutating client calls (create, update, patch, delete, import, purge, set, write-style RPCs) and fail if any exist outside comments. Confirm clients are only ever built in geadm/auth.py, that `logs user` calls warn_banner() before output, and that --help text names the viewer roles. Produce a PASS/FAIL table per file with file:line references. You cannot edit files — report only.

geadm-0.1.0/.claude/skills/ge-api-drift/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: ge-api-drift
+description: Reconcile every Gemini Enterprise / Discovery Engine API surface geadm uses against the installed google-cloud-discoveryengine client and current Google Cloud docs, highlighting new or deprecated calls. Use after upgrading the client dependency, before a release, or when a command misbehaves against a live project.
+---
+
+# GE API drift check
+
+Verify that the API surfaces geadm depends on are still consistent with the
+Discovery Engine product, and report anything new or deprecated. Do not change
+behaviour in this skill — produce a report; fixes happen in a follow-up PR via
+the owning subagent.
+
+## Step 1 — inventory what geadm uses
+
+Build the "used surface" list from the code (don't work from memory):
+
+- **Python client calls**: `grep -n "discoveryengine\|list_\|get_" geadm/commands/*.py geadm/auth.py` — collect every client class passed to `Clients.discoveryengine()` and every method invoked on it, plus `logging.list_entries`, `monitoring.list_time_series`, `list_metric_descriptors`.
+- **REST paths**: every `rest_get(...)` call — note the API version segment (`v1alpha/...`) and resource shape (collections list, `dataConnector` singleton, `assistants/default_assistant/agents`, logging `v2/projects/{p}/logs`).
+- **Log names & filter fields**: from `geadm/commands/logs.py` — `connector_activity`, `gemini_enterprise_user_activity`, `jsonPayload.userIamPrincipal`, `jsonPayload.LogMetadata.name` / `logMetadata`, `serviceTextReply`, `request.query.text|parts|userPromptData`.
+- **Metric filters**: from `geadm/commands/stats.py` — the `starts_with("discoveryengine.googleapis.com/")` discovery filter and the `quota/<name>/{usage,limit,exceeded}` pattern.
+
+## Step 2 — check against the installed client
+
+Introspect the environment, not the docs, for the Python surface:
+
+```sh
+uv run python - <<'EOF'
+import inspect
+from google.cloud import discoveryengine_v1, discoveryengine_v1alpha
+for mod in (discoveryengine_v1, discoveryengine_v1alpha):
+    clients = [n for n in dir(mod) if n.endswith("ServiceClient")]
+    print(mod.__name__, "->", clients)
+EOF
+```
+
+- Confirm every used class/method still exists and emits no `DeprecationWarning` on import/call signature inspection.
+- Flag **new** service clients relevant to geadm's scope (e.g. a real
+  `DataConnectorServiceClient` or agent-listing client appearing would let the
+  v1alpha REST fallbacks in `ls.py` be replaced).
+- Note the installed package version (`uv run python -c "import google.cloud.discoveryengine as d; print(d.__version__)"`) and the latest on PyPI.
+
+## Step 3 — verify REST/logging/metric surfaces against docs
+
+Use the `ge-api-researcher` subagent ("Use the ge-api-researcher subagent to
+…") to confirm, from official Google Cloud documentation:
+
+- the v1alpha REST resources geadm GETs still exist at those paths, and whether
+  any have been promoted to v1/v1beta (promotion = update the path);
+- the Cloud Logging log names and payload fields (especially
+  `jsonPayload.userIamPrincipal` and `serviceTextReply`) are still documented/
+  current;
+- any newly documented `discoveryengine.googleapis.com` metrics or quota
+  metrics worth surfacing in `stats`/`quota`.
+
+If docs and verified live behaviour (see memory / tests) disagree, trust the
+live shape but flag the discrepancy.
+
+## Step 4 — report
+
+Produce a drift report with three sections:
+
+1. **Consistent** — used surfaces confirmed current (one line each).
+2. **Deprecated / changed** — anything removed, renamed, promoted to a newer
+   API version, or emitting deprecation warnings; include the geadm file:line
+   that uses it and the recommended replacement.
+3. **New / unused opportunities** — newly available clients, methods, log
+   fields or metrics geadm could adopt.
+
+End with a verdict: `NO DRIFT`, or `DRIFT FOUND` plus which subagent should
+implement each fix. Read-only throughout — this skill never edits geadm code.

geadm-0.1.0/.github/workflows/release-please.yml

@@ -0,0 +1,25 @@
+name: release-please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          # Runs with the default Actions token: the egen org forbids classic
+          # PATs and fine-grained PATs are not enabled, so release PRs do not
+          # trigger the required `test` checks on their own. To release:
+          #   gh pr close <release-pr> && gh pr reopen <release-pr>
+          # (close/reopen re-delivers the pull_request event and CI runs).
+          # If a RELEASE_PLEASE_TOKEN secret is ever added, it takes over and
+          # the workaround becomes unnecessary.
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN || github.token }}
+          release-type: python

geadm-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Required for PyPI Trusted Publishing (OIDC) — no API tokens.
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

geadm-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: CLI smoke test
+        run: uv run geadm --help

geadm-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+.claude/settings.local.json
+dist/

geadm-0.1.0/AGENTS.md

@@ -0,0 +1,57 @@
+# Agent instructions for geadm
+
+This repository is built and maintained with AI coding agents. If you are an
+agent working here, follow these rules.
+
+## Use the project subagents
+
+Definitions live in `.claude/agents/`. Delegate explicitly ("Use the X
+subagent to …") rather than doing everything in the main session:
+
+| Subagent | When to use |
+|---|---|
+| `ge-api-researcher` | **Before** touching any API surface: verifies current google-cloud-discoveryengine method names, Cloud Logging field names/filters, and metric types against official docs so nothing is hallucinated. |
+| `discoveryengine-lister` | Changes to `geadm/commands/ls.py` (inventory listing). |
+| `logging-inspector` | Changes to `geadm/commands/logs.py` (log filters, tailing, normalization). |
+| `monitoring-stats` | Changes to `geadm/commands/stats.py` (metrics, quotas). |
+| `readonly-auditor` | **After** any change that touches API calls: greps the tree for mutating calls and confirms the read-only guarantees still hold. |
+
+The main session owns the shared contracts (`geadm/auth.py`, `geadm/render.py`,
+`geadm/duration.py`, `geadm/main.py`, `geadm/commands/doctor.py`) and the final
+wiring; builders must not edit files outside their charter.
+
+## Skills
+
+Run `/ge-api-drift` (defined in `.claude/skills/ge-api-drift/`) whenever the
+google-cloud-discoveryengine dependency is upgraded, before a release, or when
+a command misbehaves against a live project — it reconciles every API surface
+geadm uses against the installed client and current docs, and highlights new
+or deprecated calls.
+
+## Hard constraints
+
+- **Read-only.** geadm must never call a mutating RPC (create/update/patch/
+  delete/import/purge). Only `list_*`, `get_*`, `entries.list`,
+  `list_time_series` / `list_metric_descriptors`, and GET-only REST via
+  `Clients.rest_get`. `tests/test_readonly.py` enforces this — keep it passing.
+- **Clients are constructed only in `geadm/auth.py`** (ADC only, no key files).
+- `geadm logs user` must call `render.warn_banner()` before any other output.
+- Every command supports `--json`; progress/warnings go to stderr, data to stdout.
+
+## Workflow
+
+`main` is protected: changes go through a feature branch and PR, and the
+`test (3.11/3.12/3.13)` checks must pass. Run `uv run pytest -q` locally before
+pushing. Verified live behaviour beats documentation — when docs and a live
+log/metric disagree, trust the live shape and record it in a test.
+
+### Commit messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+`<type>(<scope>): <imperative summary>` — e.g. `feat(logs): add gen_ai
+content stream`, `fix(stats): humanize aggregate numbers`. Types: `feat`,
+`fix`, `docs`, `test`, `refactor`, `perf`, `chore`, `ci`. Scope is the
+command group or module (`ls`, `logs`, `stats`, `quota`, `doctor`, `auth`,
+`render`, `agents`, `ci`). PR titles follow the same convention — they become
+the squash-merge subject. Keep the body explaining *why*, and end agent
+commits with the Co-Authored-By trailer.

geadm-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.1.0 (2026-07-03)
+
+
+### Features
+
+* **info:** add project overview with per-engine cards ([#8](https://github.com/egen/geadm/issues/8)) ([49b92e2](https://github.com/egen/geadm/commit/49b92e27eff310ba33428bcdbe320c2006f35d6e))
+* **info:** show engine feature toggles and app type on cards ([#10](https://github.com/egen/geadm/issues/10)) ([fad2b5b](https://github.com/egen/geadm/commit/fad2b5b8651a8915af34eb6ac0f7a230dcb9f8a6))
+* **logs:** add gen_ai prompt/response content stream ([#4](https://github.com/egen/geadm/issues/4)) ([432c1c8](https://github.com/egen/geadm/commit/432c1c8bf01b613e72d84dbf81239dcda21b7f7e))
+* **ls:** add user license inventory ([#3](https://github.com/egen/geadm/issues/3)) ([708c173](https://github.com/egen/geadm/commit/708c173af1fcf1a283bc1a49712317362f46a926))
+* **release:** add MIT license, packaging metadata and release pipeline ([#11](https://github.com/egen/geadm/issues/11)) ([308fe11](https://github.com/egen/geadm/commit/308fe11abecafca8daae6d5d853b0323efff9f3e))
+
+
+### Bug Fixes
+
+* **logs:** parse structured gen_ai content payloads ([#6](https://github.com/egen/geadm/issues/6)) ([fa2662c](https://github.com/egen/geadm/commit/fa2662c0b3ee2a6b96d71d938fec10142168c061))
+* **logs:** use non-markup prefixes for gen_ai tool/thought parts ([#7](https://github.com/egen/geadm/issues/7)) ([e40ec55](https://github.com/egen/geadm/commit/e40ec556ac38befa94881276ecc24b3e97a1a519))
+
+
+### Documentation
+
+* **agents:** adopt Conventional Commits ([#5](https://github.com/egen/geadm/issues/5)) ([514a710](https://github.com/egen/geadm/commit/514a710cf82fe863e254c7e223a6a3d15606efb6))
+* **readme:** document geadm info ([#9](https://github.com/egen/geadm/issues/9)) ([4494f56](https://github.com/egen/geadm/commit/4494f5646ea323ca6f16d04d01eac38423c9e99a))

geadm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Egen
+
+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.

geadm-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: geadm
+Version: 0.1.0
+Summary: CLI for Google Gemini Enterprise
+Project-URL: Homepage, https://github.com/egen/geadm
+Project-URL: Repository, https://github.com/egen/geadm
+Project-URL: Issues, https://github.com/egen/geadm/issues
+Project-URL: Changelog, https://github.com/egen/geadm/blob/main/CHANGELOG.md
+Author: Egen
+Maintainer: Andrew McKinney
+License: MIT
+License-File: LICENSE
+Keywords: agentspace,cli,discovery-engine,gemini-enterprise,google-cloud,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: google-cloud-discoveryengine>=0.13
+Requires-Dist: google-cloud-logging>=3.10
+Requires-Dist: google-cloud-monitoring>=2.21
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# geadm
+
+[![Gemini Enterprise](https://img.shields.io/badge/Gemini%20Enterprise-Discovery%20Engine-4285F4?logo=googlecloud&logoColor=white)](https://cloud.google.com/gemini/enterprise)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Python](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+
+**geadm** is a command-line companion for operating **Google Gemini Enterprise**.
+It gives platform teams fast answers to the questions that come up daily while
+running a Gemini Enterprise deployment: What's deployed? Are the connectors
+syncing? What are users asking, and what is Model Armor flagging? How close are
+we to a quota ceiling? Is everything healthy?
+
+It inventories engines, data stores, connectors and agents; inspects and tails
+the platform's Cloud Logging streams; summarises Cloud Monitoring metrics and
+quota utilisation; and runs a one-shot health check across all of it.
+
+By design, the current release is strictly read-only — every command works with
+viewer roles alone, so it can be handed to anyone on the team without change-risk.
+It may grow administrative verbs (e.g. triggering connector syncs, managing
+agents) in a future release.
+
+Contributing with an AI coding agent? Read [AGENTS.md](AGENTS.md) — it maps
+the project subagents, skills and hard constraints.
+
+## Install
+
+```sh
+uv tool install geadm      # or: pipx install geadm / pip install geadm
+```
+
+From a checkout:
+
+```sh
+uv tool install .
+# or for development:
+uv sync && uv run geadm --help
+```
+
+## Authentication & roles
+
+geadm uses Application Default Credentials (`gcloud auth application-default login`);
+it never reads or writes key files.
+
+| Role | Used by |
+|---|---|
+| `roles/discoveryengine.viewer` | `geadm ls …`, `geadm doctor` |
+| `roles/logging.viewer` | `geadm logs …`, `geadm doctor` |
+| `roles/monitoring.viewer` | `geadm stats`, `geadm quota`, `geadm doctor` |
+
+User credentials (as opposed to service accounts) also need a quota project:
+geadm uses the target project automatically, which requires
+`serviceusage.services.use` there. If you don't have it, pass
+`--quota-project <other-project>` (or set `GOOGLE_CLOUD_QUOTA_PROJECT`) to bill
+a project you can use.
+
+Enabling connector/observability *logging* on a project is a one-time setup
+step requiring `roles/discoveryengine.agentspaceAdmin`; geadm only ever reads
+what's there.
+
+## Commands
+
+Global options: `--project` (defaults to the ADC project), `--location`
+(default `global`; regional locations are routed to
+`{location}-discoveryengine.googleapis.com`). Every command supports `--json`
+for machine-readable output, and time-windowed commands take `--since`
+(`30m`, `1h`, `24h`, `7d`).
+
+### Overview — `geadm info`
+
+```sh
+geadm info
+```
+
+Project-wide dashboard: summary tiles (engines, data stores, connector
+health, agents, license seats/activation/unmet demand) plus a card per
+engine showing its data stores with their connector sources and its agents
+("My Agent" user defaults are grouped into a single ×N line).
+
+### Inventory — `geadm ls`
+
+```sh
+geadm ls engines|datastores|connectors|agents|licenses
+```
+
+Walks the collection hierarchy: engines and data stores under
+`default_collection`, data connectors across *all* collections (each
+connector-backed source lives in its own), agents per engine, and user
+licenses in the project's `default_user_store`.
+
+### Logs — `geadm logs`
+
+```sh
+geadm logs connector [--datastore ID] [--severity ERROR] [--since 1h]
+geadm logs user [email] [--since 24h] [--follow]
+geadm logs ai [--since 24h] [--follow]
+```
+
+`logs connector` shows data-connector sync activity. `logs user` shows
+end-user Gemini Enterprise activity — prompts, assistant replies, searches and
+Model Armor screening events — for one user, or all users when the email is
+omitted. `logs ai` streams the raw `gen_ai.user.message`/`gen_ai.choice`
+content logs (prompt and reply text with no identity field, so it cannot be
+scoped per user — use `logs user` for that). `--follow`/`-f` tails either
+stream live (newline-delimited JSON with `--json`). When a log turns out to be
+empty, geadm tells you whether logging simply isn't enabled on the project or
+nothing matched your filter.
+
+> ⚠ **Sensitive output**: `geadm logs user` and `geadm logs ai` can surface
+> end-user prompt and response content when prompt/response logging is
+> enabled on the project, and print a warning banner before any output.
+
+### Metrics — `geadm stats`
+
+```sh
+geadm stats [--engine ID] [--since 24h]
+```
+
+Discovers the project's `discoveryengine.googleapis.com` metrics at runtime and
+summarises query volume, latency and connector sync freshness over the window.
+
+### Quotas — `geadm quota`
+
+```sh
+geadm quota [--since 24h]
+```
+
+Pairs each Discovery Engine quota's latest usage with its limit per location:
+percent used (highlighted at ≥75% / ≥90%), byte quotas in human units, and
+counts of quota-exceeded events over the window — the quickest way to spot the
+next capacity ceiling before ingestion hits it.
+
+### Health check — `geadm doctor`
+
+```sh
+geadm doctor [--since 24h]
+```
+
+Runs the whole suite concurrently — inventory reachability, connector states
+and sync freshness, connector/API error logs, metric availability — and renders
+a live PASS/WARN/FAIL table. Exits non-zero if any check fails, so it drops
+straight into CI or cron.

geadm-0.1.0/README.md

@@ -0,0 +1,141 @@
+# geadm
+
+[![Gemini Enterprise](https://img.shields.io/badge/Gemini%20Enterprise-Discovery%20Engine-4285F4?logo=googlecloud&logoColor=white)](https://cloud.google.com/gemini/enterprise)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Python](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+
+**geadm** is a command-line companion for operating **Google Gemini Enterprise**.
+It gives platform teams fast answers to the questions that come up daily while
+running a Gemini Enterprise deployment: What's deployed? Are the connectors
+syncing? What are users asking, and what is Model Armor flagging? How close are
+we to a quota ceiling? Is everything healthy?
+
+It inventories engines, data stores, connectors and agents; inspects and tails
+the platform's Cloud Logging streams; summarises Cloud Monitoring metrics and
+quota utilisation; and runs a one-shot health check across all of it.
+
+By design, the current release is strictly read-only — every command works with
+viewer roles alone, so it can be handed to anyone on the team without change-risk.
+It may grow administrative verbs (e.g. triggering connector syncs, managing
+agents) in a future release.
+
+Contributing with an AI coding agent? Read [AGENTS.md](AGENTS.md) — it maps
+the project subagents, skills and hard constraints.
+
+## Install
+
+```sh
+uv tool install geadm      # or: pipx install geadm / pip install geadm
+```
+
+From a checkout:
+
+```sh
+uv tool install .
+# or for development:
+uv sync && uv run geadm --help
+```
+
+## Authentication & roles
+
+geadm uses Application Default Credentials (`gcloud auth application-default login`);
+it never reads or writes key files.
+
+| Role | Used by |
+|---|---|
+| `roles/discoveryengine.viewer` | `geadm ls …`, `geadm doctor` |
+| `roles/logging.viewer` | `geadm logs …`, `geadm doctor` |
+| `roles/monitoring.viewer` | `geadm stats`, `geadm quota`, `geadm doctor` |
+
+User credentials (as opposed to service accounts) also need a quota project:
+geadm uses the target project automatically, which requires
+`serviceusage.services.use` there. If you don't have it, pass
+`--quota-project <other-project>` (or set `GOOGLE_CLOUD_QUOTA_PROJECT`) to bill
+a project you can use.
+
+Enabling connector/observability *logging* on a project is a one-time setup
+step requiring `roles/discoveryengine.agentspaceAdmin`; geadm only ever reads
+what's there.
+
+## Commands
+
+Global options: `--project` (defaults to the ADC project), `--location`
+(default `global`; regional locations are routed to
+`{location}-discoveryengine.googleapis.com`). Every command supports `--json`
+for machine-readable output, and time-windowed commands take `--since`
+(`30m`, `1h`, `24h`, `7d`).
+
+### Overview — `geadm info`
+
+```sh
+geadm info
+```
+
+Project-wide dashboard: summary tiles (engines, data stores, connector
+health, agents, license seats/activation/unmet demand) plus a card per
+engine showing its data stores with their connector sources and its agents
+("My Agent" user defaults are grouped into a single ×N line).
+
+### Inventory — `geadm ls`
+
+```sh
+geadm ls engines|datastores|connectors|agents|licenses
+```
+
+Walks the collection hierarchy: engines and data stores under
+`default_collection`, data connectors across *all* collections (each
+connector-backed source lives in its own), agents per engine, and user
+licenses in the project's `default_user_store`.
+
+### Logs — `geadm logs`
+
+```sh
+geadm logs connector [--datastore ID] [--severity ERROR] [--since 1h]
+geadm logs user [email] [--since 24h] [--follow]
+geadm logs ai [--since 24h] [--follow]
+```
+
+`logs connector` shows data-connector sync activity. `logs user` shows
+end-user Gemini Enterprise activity — prompts, assistant replies, searches and
+Model Armor screening events — for one user, or all users when the email is
+omitted. `logs ai` streams the raw `gen_ai.user.message`/`gen_ai.choice`
+content logs (prompt and reply text with no identity field, so it cannot be
+scoped per user — use `logs user` for that). `--follow`/`-f` tails either
+stream live (newline-delimited JSON with `--json`). When a log turns out to be
+empty, geadm tells you whether logging simply isn't enabled on the project or
+nothing matched your filter.
+
+> ⚠ **Sensitive output**: `geadm logs user` and `geadm logs ai` can surface
+> end-user prompt and response content when prompt/response logging is
+> enabled on the project, and print a warning banner before any output.
+
+### Metrics — `geadm stats`
+
+```sh
+geadm stats [--engine ID] [--since 24h]
+```
+
+Discovers the project's `discoveryengine.googleapis.com` metrics at runtime and
+summarises query volume, latency and connector sync freshness over the window.
+
+### Quotas — `geadm quota`
+
+```sh
+geadm quota [--since 24h]
+```
+
+Pairs each Discovery Engine quota's latest usage with its limit per location:
+percent used (highlighted at ≥75% / ≥90%), byte quotas in human units, and
+counts of quota-exceeded events over the window — the quickest way to spot the
+next capacity ceiling before ingestion hits it.
+
+### Health check — `geadm doctor`
+
+```sh
+geadm doctor [--since 24h]
+```
+
+Runs the whole suite concurrently — inventory reachability, connector states
+and sync freshness, connector/API error logs, metric availability — and renders
+a live PASS/WARN/FAIL table. Exits non-zero if any check fails, so it drops
+straight into CI or cron.

geadm-0.1.0/geadm/__init__.py

@@ -0,0 +1,3 @@
+"""geadm — read-only troubleshooting CLI for Google Gemini Enterprise (Discovery Engine)."""
+
+__version__ = "0.1.0"