feat: adding cli for tools (#123)

* feat: adding cli for tools

* fix: hashes

* feat: update cli and docs

* chore: update docs

* fix: per copilot and make json output prettyified

* fix: per copilot recommendations

* fix: docs

Author: venkatamutyala

.ai/AGENTS.md

@@ -6,6 +6,8 @@ This file provides guidance to AI coding assistants when working with code in th
 
 tools-api is a FastAPI service providing internal REST APIs for GlueOps platform engineers. It manages AWS accounts, cloud storage (MinIO), Hetzner infrastructure (Chisel load balancers), GitHub organization setup, Kubernetes/ArgoCD manifest generation, and Opsgenie alerting.
 
+A companion Go CLI (`cli/`) allows engineers to interact with the API from headless Linux machines. See [`cli/.ai/AGENTS.md`](../cli/.ai/AGENTS.md) for CLI-specific guidance.
+
 ## Development Setup
 
 ```bash
@@ -35,9 +37,10 @@ The Dockerfile uses `python:3.14-slim` as base, installs dependencies via pipenv
 ## Architecture
 
 - **`app/main.py`** — FastAPI app entry point. Defines all API routes, global exception handler, health/version endpoints. Routes redirect `/` to `/docs`.
-- **`app/schemas/schemas.py`** — Pydantic request/response models for all endpoints.
+- **`app/schemas/schemas.py`** — Pydantic request/response models for all endpoints (including `VersionResponse` for `/version`). Examples and descriptions defined here are the single source of truth — the CLI reads them from the embedded OpenAPI spec at compile time.
 - **`app/util/`** — Business logic modules, one per domain: `storage.py` (MinIO), `github.py`, `hetzner.py`, `aws_setup_test_account_credentials.py`, `chisel.py`, `captain_manifests.py`, `opsgenie.py`.
 - **`app/templates/captain_manifests/`** — Jinja2 templates (`.yaml.j2`) for generating Kubernetes manifests (Namespace, AppProject, ApplicationSet).
+- **`cli/`** — Go CLI binary. See [`cli/.ai/AGENTS.md`](../cli/.ai/AGENTS.md).
 
 All routes are defined directly in `main.py` (no router separation). Each route delegates to a corresponding util module.
 
@@ -52,4 +55,5 @@ GitHub workflow endpoints (`github.py`) dispatch workflows via the GitHub API an
 
 ## CI/CD
 
-GitHub Actions workflow (`.github/workflows/container_image.yaml`) builds and pushes Docker images to GHCR on any push.
+- **`.github/workflows/container_image.yaml`** — Builds and pushes Docker images to GHCR on any push.
+- **`.github/workflows/cli_release.yaml`** — Builds CLI binaries on every push, uploads as workflow artifacts, and creates a GitHub Release tagged with `github.ref_name`. Cross-compiles for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64.

.github/workflows/cli_release.yaml

@@ -0,0 +1,61 @@
+name: CLI Release
+
+on:
+  push:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Set build variables
+        id: vars
+        run: |
+          echo "version=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT
+          echo "short_sha=${GITHUB_SHA::7}" >> $GITHUB_OUTPUT
+          echo "build_timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")" >> $GITHUB_OUTPUT
+
+      - name: Build CLI binaries
+        working-directory: cli
+        run: |
+          make build-all \
+            VERSION=${{ steps.vars.outputs.version }} \
+            COMMIT_SHA=${{ github.sha }} \
+            SHORT_SHA=${{ steps.vars.outputs.short_sha }} \
+            BUILD_TIMESTAMP=${{ steps.vars.outputs.build_timestamp }} \
+            GIT_REF=${{ github.ref_name }}
+
+      - name: Upload workflow artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: tools-cli-binaries
+          path: |
+            cli/tools-linux-amd64
+            cli/tools-linux-arm64
+            cli/tools-darwin-amd64
+            cli/tools-darwin-arm64
+
+      - name: Delete existing release for this ref
+        run: gh release delete "${{ github.ref_name }}" --yes 2>/dev/null || true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@1853d73993c8ca1b2c9c1a7fede39682d0ab5c2a # v2.5.3
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          prerelease: ${{ !startsWith(github.ref, 'refs/tags/v') }}
+          files: |
+            cli/tools-linux-amd64
+            cli/tools-linux-arm64
+            cli/tools-darwin-amd64
+            cli/tools-darwin-arm64
+          body: |
+            CLI binaries built from `${{ github.sha }}` on `${{ github.ref_name }}`.

.gitignore

@@ -163,3 +163,8 @@ cython_debug/
 
 # ignore devbox
 .devbox
+
+# Go CLI build artifacts
+cli/tools
+cli/tools-linux-*
+cli/tools-darwin-*

README.md

@@ -1,7 +1,24 @@
 # tools-api
 This FastAPI app has various utilities to help streamline local development for Platform Engineers that are working on the GlueOps Platform. This tool is not meant for customers or any end users of the GlueOps Platform.
 
-## Setup
+## CLI
+
+The `tools` CLI lets you interact with the API from the command line. Download the latest binary for your platform from [GitHub Releases](https://github.com/GlueOps/tools-api/releases).
+
+```bash
+# Authenticate
+tools login
+
+# Example: create storage buckets
+tools storage-buckets create --captain-domain nonprod.foobar.onglueops.rocks
+
+# See all commands
+tools --help
+```
+
+The CLI self-updates automatically when the API version changes. See [`cli/`](cli/) for development details.
+
+## API Setup
 
 1. Launch codespace
 2. Configure environment variables (see below)

app/main.py

@@ -5,7 +5,7 @@
 from pydantic import BaseModel, Field
 from contextlib import asynccontextmanager
 import os, glueops.setup_logging, traceback, base64, yaml, tempfile, json
-from schemas.schemas import Message, AwsCredentialsRequest, StorageBucketsRequest, AwsNukeAccountRequest, CaptainDomainNukeDataAndBackupsRequest, ChiselNodesRequest, ChiselNodesDeleteRequest, ResetGitHubOrganizationRequest, OpsgenieAlertsManifestRequest, CaptainManifestsRequest, GitHubWorkflowRunStatusRequest
+from schemas.schemas import Message, AwsCredentialsRequest, StorageBucketsRequest, AwsNukeAccountRequest, CaptainDomainNukeDataAndBackupsRequest, ChiselNodesRequest, ChiselNodesDeleteRequest, ResetGitHubOrganizationRequest, OpsgenieAlertsManifestRequest, CaptainManifestsRequest, GitHubWorkflowRunStatusRequest, VersionResponse
 from util import storage, aws_setup_test_account_credentials, github, hetzner, opsgenie, captain_manifests
 from fastapi.responses import RedirectResponse
 
@@ -53,7 +53,7 @@ async def hello(request: StorageBucketsRequest):
     return storage.create_all_buckets(request.captain_domain)
 
 
-@app.post("/v1/setup-aws-account-credentials", response_class=PlainTextResponse, summary="Wether it's to create an EKS cluster or to test other things out in an isolated AWS account. These creds will give you Admin level access to the requested account.")
+@app.post("/v1/setup-aws-account-credentials", response_class=PlainTextResponse, summary="Whether it's to create an EKS cluster or to test other things out in an isolated AWS account. These creds will give you Admin level access to the requested account.")
 async def create_credentials_for_aws_captain_account(request: AwsCredentialsRequest):
     """
     If you are testing in AWS/EKS you will need an AWS account to test with. This request will provide you with admin level credentials to the sub account you specify.
@@ -88,7 +88,7 @@ async def reset_github_organization(request: ResetGitHubOrganizationRequest):
      
      This will reset your deployment-configurations repository, it'll bring over a working regcred, and application repos with working github actions so that you can quickly work on the GlueOps stack.
 
-     WARNING: By default delete_all_existing_repos = True. Please set it to False or make a manual backup if you are concerned about any dataloss within your tenant org (e.g. github.com/development-tenant-*)
+     WARNING: By default delete_all_existing_repos = True. Please set it to False or make a manual backup if you are concerned about any data loss within your tenant org (e.g. github.com/development-tenant-*)
 
     """
     return github.reset_tenant_github_organization(request.captain_domain, request.delete_all_existing_repos, request.custom_domain, request.enable_custom_domain)
@@ -153,12 +153,12 @@ async def health():
     return {"status": "healthy"}
 
 
-@app.get("/version", summary="Contains version information about this tools-api")
+@app.get("/version", response_model=VersionResponse, summary="Contains version information about this tools-api")
 async def version():
-    return {
-        "version": os.getenv("VERSION", "UNKNOWN"),
-        "commit_sha": os.getenv("COMMIT_SHA", "UNKNOWN"),
-        "short_sha": os.getenv("SHORT_SHA", "UNKNOWN"),
-        "build_timestamp": os.getenv("BUILD_TIMESTAMP", "UNKNOWN"),
-        "git_ref": os.getenv("GIT_REF", "UNKNOWN")
-    }
+    return VersionResponse(
+        version=os.getenv("VERSION", "UNKNOWN"),
+        commit_sha=os.getenv("COMMIT_SHA", "UNKNOWN"),
+        short_sha=os.getenv("SHORT_SHA", "UNKNOWN"),
+        build_timestamp=os.getenv("BUILD_TIMESTAMP", "UNKNOWN"),
+        git_ref=os.getenv("GIT_REF", "UNKNOWN"),
+    )

app/schemas/schemas.py

@@ -4,6 +4,13 @@
 class Message(BaseModel):
     message: str = Field(...,example = 'Success')
 
+class VersionResponse(BaseModel):
+    version: str = Field(..., example='v1.0.0')
+    commit_sha: str = Field(..., example='abc1234567890def1234567890abcdef12345678')
+    short_sha: str = Field(..., example='abc1234')
+    build_timestamp: str = Field(..., example='2026-01-01T00:00:00Z')
+    git_ref: str = Field(..., example='main')
+
 class ChiselNodesRequest(BaseModel):
     captain_domain: str = Field(..., example='nonprod.foobar.onglueops.rocks')
     node_count: int = Field(

cli/.ai/AGENTS.md

@@ -0,0 +1,123 @@
+# AGENTS.md — CLI
+
+This file provides guidance to AI coding assistants when working with the `tools` CLI.
+
+## Overview
+
+`tools` is a Go CLI that wraps the GlueOps Tools API. It authenticates via Dex device code flow through oauth2-proxy and self-updates when the API version changes.
+
+All Go builds use Docker (`golang:1.24-alpine`, pinned by digest in the Makefile) — no local Go toolchain is required.
+
+## Build
+
+```bash
+cd cli
+
+# Build for current platform
+make build
+
+# Build for all release platforms (linux/darwin × amd64/arm64)
+make build-all
+
+# Regenerate OpenAPI client after API changes
+make generate
+
+# Clean build artifacts
+make clean
+```
+
+## Regenerating the API Client
+
+When the API changes (new endpoints, schema changes, updated descriptions/examples), run:
+
+```bash
+cd cli
+make generate
+```
+
+This does three things:
+1. Builds the tools-api Docker image and exports the OpenAPI spec to `openapi.json`
+2. Runs `oapi-codegen` (pinned to v2.6.0) via Docker to regenerate `api/generated.go`
+3. Copies `openapi.json` to `internal/spec/openapi.json` for embedding
+
+The generated client (`api/generated.go`) and both copies of `openapi.json` are committed to the repo.
+
+## Architecture
+
+### File Structure
+
+```
+cli/
+├── main.go                         # Entry point
+├── go.mod / go.sum                 # Go module (github.com/GlueOps/tools-api/cli)
+├── Makefile                        # Docker-based build targets
+├── openapi.json                    # Exported OpenAPI spec from FastAPI
+├── oapi-codegen.yaml               # oapi-codegen config (generates types + client)
+├── api/
+│   └── generated.go                # Auto-generated typed client — DO NOT EDIT
+├── cmd/
+│   ├── root.go                     # Root command, persistent flags, auth/update pre-run
+│   ├── client.go                   # Authenticated API client helper + response handler (pretty-prints JSON)
+│   ├── version.go                  # tools version
+│   ├── login.go                    # tools login (device code flow)
+│   ├── logout.go                   # tools logout
+│   ├── storage_buckets.go          # tools storage-buckets create
+│   ├── aws.go                      # tools aws setup-credentials, aws nuke-account
+│   ├── nuke.go                     # tools nuke captain-domain-data
+│   ├── github.go                   # tools github reset-org, github workflow-status
+│   ├── chisel.go                   # tools chisel create, chisel delete
+│   ├── opsgenie.go                 # tools opsgenie create
+│   └── captain_manifests.go        # tools captain-manifests generate
+└── internal/
+    ├── auth/
+    │   ├── device_flow.go          # Dex device code flow (issuer: dex.toolshosted.com)
+    │   └── token.go                # Token storage/refresh (~/.config/glueops/tools-cli/tokens.json)
+    ├── config/
+    │   └── config.go               # Config dir management (~/.config/glueops/tools-cli/)
+    ├── spec/
+    │   ├── spec.go                 # Embedded OpenAPI spec parser (examples, summaries, descriptions)
+    │   └── openapi.json            # Embedded copy of OpenAPI spec (go:embed)
+    ├── updater/
+    │   └── updater.go              # Self-update from GitHub releases when API version changes
+    └── version/
+        └── version.go              # Build-time injected version vars (ldflags)
+```
+
+### Key Design Decisions
+
+- **OpenAPI as single source of truth** — CLI flag descriptions, command summaries, and long descriptions are all read from the embedded `openapi.json` at compile time via `internal/spec`. When API docstrings or schema examples change, `make generate` + rebuild picks them up automatically without editing Go code.
+- **Auto-generated API client** — `api/generated.go` is produced by `oapi-codegen` from the OpenAPI spec. Each command file in `cmd/` constructs requests using generated types and calls generated client methods.
+- **Auth via PersistentPreRunE** — `root.go` checks for a valid token before every command except `login`, `logout`, `version`, `completion`, `help`, and the root command itself (so `tools --help` works without login). Expired tokens are automatically refreshed.
+- **Self-update** — On every invocation, the CLI checks `GET /version` on the API. If the version differs (and isn't a placeholder like `UNKNOWN` or `dev`), it downloads the matching binary from GitHub releases and replaces itself.
+- **Config directory** — `~/.config/glueops/tools-cli/` stores `tokens.json`.
+
+### Adding a New Command
+
+1. Add the endpoint to `app/main.py` and schema to `app/schemas/schemas.py`
+2. Run `cd cli && make generate` to update the client and spec
+3. Create `cli/cmd/<command>.go`:
+   - Use `spec.Summary()` and `spec.Description()` for `Short`/`Long`
+   - Use `spec.FlagDesc()` for flag descriptions
+   - Use `newClient()` from `client.go` to get an authenticated client
+   - Use `handleResponse()` to print the response
+4. Register the command with `rootCmd` in `init()`
+
+### Key Dependencies
+
+- **`github.com/spf13/cobra`** — CLI framework
+- **`github.com/oapi-codegen/runtime`** — Runtime helpers for the generated client
+
+### Auth Details
+
+- Dex issuer: `https://dex.toolshosted.com`
+- Client ID: `tools-cli`
+- Scopes: `openid email profile offline_access`
+- Default API URL: `https://tools.toolshosted.rocks` (overridable via `--api-url`)
+
+## CI/CD
+
+`.github/workflows/cli_release.yaml` builds CLI binaries on every push:
+- Cross-compiles for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64 via Docker
+- Uploads binaries as workflow artifacts
+- Creates a GitHub Release tagged with `github.ref_name` (rolling `main` release for branch pushes, versioned releases for tag pushes)
+- Version is injected via ldflags from the git ref

cli/CLAUDE.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+See [.ai/AGENTS.md](.ai/AGENTS.md) for AI coding assistant guidance for this CLI.

cli/Makefile

@@ -0,0 +1,46 @@
+GO_IMAGE := golang:1.24-alpine@sha256:8bee1901f1e530bfb4a7850aa7a479d17ae3a18beb6e09064ed54cfd245b7191
+TOOLS_API_IMAGE := tools-api-spec
+MODULE := github.com/GlueOps/tools-api/cli
+VERSION ?= dev
+COMMIT_SHA ?= $(shell git rev-parse HEAD 2>/dev/null || echo unknown)
+SHORT_SHA ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo unknown)
+BUILD_TIMESTAMP ?= $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
+GIT_REF ?= $(shell git describe --tags --always 2>/dev/null || echo unknown)
+
+LDFLAGS := -s -w \
+	-X $(MODULE)/internal/version.Version=$(VERSION) \
+	-X $(MODULE)/internal/version.CommitSHA=$(COMMIT_SHA) \
+	-X $(MODULE)/internal/version.ShortSHA=$(SHORT_SHA) \
+	-X $(MODULE)/internal/version.BuildTimestamp=$(BUILD_TIMESTAMP) \
+	-X $(MODULE)/internal/version.GitRef=$(GIT_REF)
+
+.PHONY: generate build build-all clean
+
+# Export OpenAPI spec from FastAPI and regenerate Go client
+generate:
+	docker build -t $(TOOLS_API_IMAGE) ..
+	docker run --rm $(TOOLS_API_IMAGE) python -c \
+		"import sys; sys.path.insert(0, 'app'); from main import app; import json; print(json.dumps(app.openapi(), indent=2))" \
+		> openapi.json
+	docker run --rm -v "$$(pwd):/app" -w /app $(GO_IMAGE) sh -c \
+		"go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@v2.6.0 && oapi-codegen -config oapi-codegen.yaml openapi.json"
+	cp openapi.json internal/spec/openapi.json
+
+# Build for current platform
+build:
+	docker run --rm -v "$$(pwd):/app" -w /app \
+		-e CGO_ENABLED=0 \
+		$(GO_IMAGE) go build -ldflags '$(LDFLAGS)' -o tools .
+
+# Build for all release platforms
+build-all:
+	@for platform in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64; do \
+		os=$${platform%/*}; arch=$${platform#*/}; \
+		echo "Building tools-$$os-$$arch..."; \
+		docker run --rm -v "$$(pwd):/app" -w /app \
+			-e CGO_ENABLED=0 -e GOOS=$$os -e GOARCH=$$arch \
+			$(GO_IMAGE) go build -ldflags '$(LDFLAGS)' -o "tools-$$os-$$arch" .; \
+	done
+
+clean:
+	rm -f tools tools-linux-amd64 tools-linux-arm64 tools-darwin-amd64 tools-darwin-arm64