cloudclerk 0.1.0__tar.gz

cloudclerk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/ tests/

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

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

cloudclerk-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build artifacts
+*.whl
+*.tar.gz

cloudclerk-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: cloudclerk
+Version: 0.1.0
+Summary: CLI for CloudClerk - BigQuery cost optimization from the terminal
+Project-URL: Homepage, https://cloudclerk.io
+Project-URL: Documentation, https://github.com/cloud-clerk/cloud-clerk-cli#readme
+Project-URL: Repository, https://github.com/cloud-clerk/cloud-clerk-cli
+Project-URL: Issues, https://github.com/cloud-clerk/cloud-clerk-cli/issues
+Project-URL: Changelog, https://github.com/cloud-clerk/cloud-clerk-cli/releases
+Author-email: CloudClerk <team@cloudclerk.ai>
+License-Expression: MIT
+Keywords: bigquery,cli,cloud,cost-optimization,gcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CloudClerk CLI
+
+BigQuery cost optimization from the terminal. Analyze your most expensive queries and get actionable recommendations to reduce costs.
+
+## Install
+
+```bash
+pipx install cloudclerk
+```
+
+Or with `uv`:
+
+```bash
+uv tool install cloudclerk
+```
+
+## Quick Start
+
+```bash
+# 1. Configure with your API key (from the CloudClerk dashboard)
+cloudclerk configure
+
+# 2. See your most expensive queries
+cloudclerk queries top
+
+# 3. Get details and recommendations for a specific query
+cloudclerk queries show <query_sha>
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `cloudclerk configure` | Set API key and server URL |
+| `cloudclerk queries top` | List most expensive queries by cost |
+| `cloudclerk queries show <sha>` | Full analysis: context, recommendations, issues |
+
+## Options
+
+```bash
+cloudclerk queries top --limit 20          # Show top 20
+cloudclerk queries top --priority high     # Filter by priority (high/medium/low)
+cloudclerk queries top --json              # Raw JSON for piping
+cloudclerk queries show <sha> --json       # Raw JSON for piping
+cloudclerk --version                       # Show version
+```
+
+## What You Get
+
+**`queries top`** - A ranked table of your most expensive queries with cost, savings potential, and priority.
+
+**`queries show`** - Full detail for a single query:
+- Query context (executions, bytes billed, referenced tables, date range)
+- The actual SQL pattern
+- Actionable recommendations with estimated savings and SQL examples
+- Issues found with severity ratings
+
+## Authentication
+
+API keys are generated from the CloudClerk dashboard. Keys are prefixed with `cc_live_` and scoped to your organization.
+
+Configuration is stored in `~/.cloudclerk/config.toml`.
+
+## Requirements
+
+- Python 3.10+
+- A CloudClerk account with API key access
+
+## Development
+
+```bash
+git clone https://github.com/numia-xyz/cloudclerk-cli.git
+cd cloudclerk-cli
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+pytest -v
+```
+
+## License
+
+MIT

cloudclerk-0.1.0/README.md

@@ -0,0 +1,81 @@
+# CloudClerk CLI
+
+BigQuery cost optimization from the terminal. Analyze your most expensive queries and get actionable recommendations to reduce costs.
+
+## Install
+
+```bash
+pipx install cloudclerk
+```
+
+Or with `uv`:
+
+```bash
+uv tool install cloudclerk
+```
+
+## Quick Start
+
+```bash
+# 1. Configure with your API key (from the CloudClerk dashboard)
+cloudclerk configure
+
+# 2. See your most expensive queries
+cloudclerk queries top
+
+# 3. Get details and recommendations for a specific query
+cloudclerk queries show <query_sha>
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `cloudclerk configure` | Set API key and server URL |
+| `cloudclerk queries top` | List most expensive queries by cost |
+| `cloudclerk queries show <sha>` | Full analysis: context, recommendations, issues |
+
+## Options
+
+```bash
+cloudclerk queries top --limit 20          # Show top 20
+cloudclerk queries top --priority high     # Filter by priority (high/medium/low)
+cloudclerk queries top --json              # Raw JSON for piping
+cloudclerk queries show <sha> --json       # Raw JSON for piping
+cloudclerk --version                       # Show version
+```
+
+## What You Get
+
+**`queries top`** - A ranked table of your most expensive queries with cost, savings potential, and priority.
+
+**`queries show`** - Full detail for a single query:
+- Query context (executions, bytes billed, referenced tables, date range)
+- The actual SQL pattern
+- Actionable recommendations with estimated savings and SQL examples
+- Issues found with severity ratings
+
+## Authentication
+
+API keys are generated from the CloudClerk dashboard. Keys are prefixed with `cc_live_` and scoped to your organization.
+
+Configuration is stored in `~/.cloudclerk/config.toml`.
+
+## Requirements
+
+- Python 3.10+
+- A CloudClerk account with API key access
+
+## Development
+
+```bash
+git clone https://github.com/numia-xyz/cloudclerk-cli.git
+cd cloudclerk-cli
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+pytest -v
+```
+
+## License
+
+MIT

cloudclerk-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cloudclerk"
+version = "0.1.0"
+description = "CLI for CloudClerk - BigQuery cost optimization from the terminal"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "CloudClerk", email = "team@cloudclerk.ai" }]
+keywords = ["bigquery", "cost-optimization", "cli", "cloud", "gcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "typer>=0.9.0",
+    "httpx>=0.27.0",
+    "rich>=13.0.0",
+    "tomli>=2.0.0;python_version<'3.11'",
+    "tomli-w>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "ruff>=0.4.0",
+]
+
+[project.scripts]
+cloudclerk = "cloudclerk.cli:app"
+
+[project.urls]
+Homepage = "https://cloudclerk.io"
+Documentation = "https://github.com/cloud-clerk/cloud-clerk-cli#readme"
+Repository = "https://github.com/cloud-clerk/cloud-clerk-cli"
+Issues = "https://github.com/cloud-clerk/cloud-clerk-cli/issues"
+Changelog = "https://github.com/cloud-clerk/cloud-clerk-cli/releases"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cloudclerk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120

cloudclerk-0.1.0/src/cloudclerk/__init__.py

@@ -0,0 +1,3 @@
+"""CloudClerk CLI — BigQuery cost optimization from the terminal."""
+
+__version__ = "0.1.0"

cloudclerk-0.1.0/src/cloudclerk/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m cloudclerk"""
+
+from cloudclerk.cli import app
+
+app()

cloudclerk-0.1.0/src/cloudclerk/cli.py

@@ -0,0 +1,29 @@
+"""CloudClerk CLI — BigQuery cost optimization from the terminal."""
+
+import typer
+
+from cloudclerk import __version__
+from cloudclerk.commands.configure import configure
+from cloudclerk.commands.queries import queries_app
+
+app = typer.Typer(
+    name="cloudclerk",
+    help="CloudClerk CLI — BigQuery cost optimization from the terminal.",
+    no_args_is_help=True,
+)
+
+app.command()(configure)
+app.add_typer(queries_app, name="queries", help="Query cost analysis")
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"cloudclerk {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(False, "--version", "-v", callback=version_callback, is_eager=True, help="Show version"),
+) -> None:
+    """CloudClerk CLI — BigQuery cost optimization from the terminal."""

cloudclerk-0.1.0/src/cloudclerk/client.py

@@ -0,0 +1,93 @@
+"""HTTP client for the CloudClerk API."""
+
+import sys
+
+import httpx
+
+from cloudclerk.config import require_config
+
+
+class APIError(Exception):
+    """Raised when the CloudClerk API returns an error."""
+
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+class CloudClerkClient:
+    """Thin wrapper around httpx for CloudClerk API calls."""
+
+    def __init__(self, api_key: str | None = None, server_url: str | None = None):
+        if api_key and server_url:
+            self._api_key = api_key
+            self._base_url = server_url.rstrip("/")
+        else:
+            config = require_config()
+            self._api_key = config["auth"]["api_key"]
+            self._base_url = config["server"]["url"].rstrip("/")
+
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Bearer {self._api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=30.0,
+        )
+
+    def _request(self, method: str, path: str, **kwargs) -> dict:
+        """Make a request and return the JSON body. Raises APIError on failure."""
+        try:
+            response = self._client.request(method, path, **kwargs)
+        except httpx.ConnectError:
+            from rich.console import Console
+
+            Console(stderr=True).print(
+                f"[red]Connection failed.[/red] Could not reach [bold]{self._base_url}[/bold].\n"
+                "Check your server URL with [bold]cloudclerk configure[/bold]."
+            )
+            sys.exit(1)
+        except httpx.TimeoutException:
+            from rich.console import Console
+
+            Console(stderr=True).print("[red]Request timed out.[/red] The server took too long to respond.")
+            sys.exit(1)
+
+        if response.status_code == 401:
+            raise APIError(401, "Invalid or expired API key. Run 'cloudclerk configure' to update.")
+        if response.status_code == 403:
+            raise APIError(403, "Access denied. Your API key may not have permission for this resource.")
+        if response.status_code == 404:
+            raise APIError(404, "Resource not found.")
+        if response.status_code >= 400:
+            detail = response.json().get("detail", response.text) if response.text else "Unknown error"
+            raise APIError(response.status_code, detail)
+
+        return response.json()
+
+    def get(self, path: str, params: dict | None = None) -> dict:
+        return self._request("GET", path, params=params)
+
+    # -- Cost Optimization endpoints --
+
+    def list_queries(
+        self,
+        limit: int = 10,
+        priority: str | None = None,
+        ordering: str = "-estimated_cost_usd",
+    ) -> dict:
+        """List query analyses, ordered by cost (most expensive first by default)."""
+        params = {"page_size": limit, "ordering": ordering}
+        if priority:
+            params["priority"] = priority
+        return self.get("/api/v1/cost-optimization/analyses/", params=params)
+
+    def get_query(self, query_sha: str) -> dict:
+        """Get full details for a single query analysis."""
+        return self.get(f"/api/v1/cost-optimization/analyses/{query_sha}/")
+
+    def get_latest_run(self) -> dict:
+        """Get the most recent optimization run (used to verify connectivity)."""
+        return self.get("/api/v1/cost-optimization/runs/latest/")

cloudclerk-0.1.0/src/cloudclerk/commands/configure.py

@@ -0,0 +1,51 @@
+"""'cloudclerk configure' command — set up API key and server URL."""
+
+import typer
+from rich.console import Console
+
+from cloudclerk.config import DEFAULT_SERVER_URL, load_config, save_config
+
+console = Console()
+
+
+def configure() -> None:
+    """Configure CloudClerk CLI with your API key and server URL."""
+    console.print()
+    console.print("[bold]CloudClerk CLI Configuration[/bold]")
+    console.print()
+
+    existing = load_config()
+    existing_url = (existing or {}).get("server", {}).get("url", DEFAULT_SERVER_URL)
+
+    api_key = typer.prompt("API Key", hide_input=True)
+
+    if not api_key.startswith(("cc_live_", "cc_test_")):
+        console.print("[red]Invalid API key format.[/red] Keys start with 'cc_live_' or 'cc_test_'.")
+        raise typer.Exit(1)
+
+    server_url = typer.prompt("Server URL", default=existing_url)
+
+    path = save_config(api_key=api_key, server_url=server_url)
+    console.print()
+    console.print(f"[green]Configuration saved[/green] to [dim]{path}[/dim]")
+
+    # Test connectivity
+    console.print()
+    console.print("[dim]Testing connection...[/dim]", end=" ")
+
+    try:
+        from cloudclerk.client import CloudClerkClient
+
+        client = CloudClerkClient(api_key=api_key, server_url=server_url)
+        client.get_latest_run()
+        console.print("[green]OK[/green]")
+    except SystemExit:
+        # Connection error already printed by client
+        console.print()
+        console.print("[yellow]Configuration saved, but connection failed.[/yellow]")
+        console.print("You can still use the CLI — check your server URL and API key.")
+    except Exception as e:
+        console.print(f"[yellow]Warning:[/yellow] {e}")
+        console.print("Configuration saved, but could not verify the connection.")
+
+    console.print()

cloudclerk-0.1.0/src/cloudclerk/commands/queries.py

@@ -0,0 +1,62 @@
+"""'cloudclerk queries' commands — list and inspect expensive BigQuery queries."""
+
+import json
+import sys
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from cloudclerk.client import APIError, CloudClerkClient
+from cloudclerk.display import render_queries_table, render_query_detail
+
+console = Console(stderr=True)
+
+queries_app = typer.Typer(help="Query cost analysis", no_args_is_help=True)
+
+
+@queries_app.command("top")
+def queries_top(
+    limit: int = typer.Option(10, "--limit", "-n", help="Number of queries to show"),
+    priority: Optional[str] = typer.Option(None, "--priority", "-p", help="Filter by priority: high, medium, low"),
+    output_json: bool = typer.Option(False, "--json", "-j", help="Output raw JSON"),
+) -> None:
+    """Show the most expensive queries, ranked by cost."""
+    if priority and priority.lower() not in ("high", "medium", "low"):
+        console.print("[red]Invalid priority.[/red] Use: high, medium, low")
+        raise typer.Exit(1)
+
+    try:
+        client = CloudClerkClient()
+        data = client.list_queries(limit=limit, priority=priority)
+    except APIError as e:
+        console.print(f"[red]Error:[/red] {e.detail}")
+        raise typer.Exit(1)
+
+    if output_json:
+        typer.echo(json.dumps(data, indent=2))
+    else:
+        render_queries_table(data)
+
+
+@queries_app.command("show")
+def queries_show(
+    query_sha: str = typer.Argument(help="The query SHA to inspect (from 'queries top' output)"),
+    output_json: bool = typer.Option(False, "--json", "-j", help="Output raw JSON"),
+) -> None:
+    """Show full details and recommendations for a specific query."""
+    try:
+        client = CloudClerkClient()
+        data = client.get_query(query_sha)
+    except APIError as e:
+        if e.status_code == 404:
+            console.print(f"[red]Query not found:[/red] {query_sha}")
+            console.print("[dim]Use 'cloudclerk queries top' to see available query SHAs.[/dim]")
+        else:
+            console.print(f"[red]Error:[/red] {e.detail}")
+        raise typer.Exit(1)
+
+    if output_json:
+        typer.echo(json.dumps(data, indent=2))
+    else:
+        render_query_detail(data)

cloudclerk-0.1.0/src/cloudclerk/config.py

@@ -0,0 +1,85 @@
+"""Configuration management for CloudClerk CLI.
+
+Stores config in ~/.cloudclerk/config.toml:
+
+    [auth]
+    api_key = "cc_live_..."
+
+    [server]
+    url = "https://app.cloudclerk.io"
+"""
+
+import sys
+from pathlib import Path
+
+import tomli_w
+
+try:
+    import tomllib
+except ModuleNotFoundError:
+    import tomli as tomllib
+
+
+DEFAULT_SERVER_URL = "https://app.cloudclerk.io"
+CONFIG_DIR_NAME = ".cloudclerk"
+CONFIG_FILE_NAME = "config.toml"
+
+
+def get_config_dir() -> Path:
+    return Path.home() / CONFIG_DIR_NAME
+
+
+def get_config_path() -> Path:
+    return get_config_dir() / CONFIG_FILE_NAME
+
+
+def load_config() -> dict | None:
+    """Load config from disk. Returns None if file doesn't exist."""
+    path = get_config_path()
+    if not path.exists():
+        return None
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def save_config(api_key: str, server_url: str) -> Path:
+    """Save config to disk. Creates directory if needed. Returns the config path."""
+    config_dir = get_config_dir()
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    config = {
+        "auth": {"api_key": api_key},
+        "server": {"url": server_url},
+    }
+
+    path = get_config_path()
+    with open(path, "wb") as f:
+        tomli_w.dump(config, f)
+
+    return path
+
+
+def require_config() -> dict:
+    """Load config or exit with a helpful message."""
+    config = load_config()
+    if config is None:
+        from rich.console import Console
+
+        console = Console(stderr=True)
+        console.print("[red]Not configured.[/red] Run [bold]cloudclerk configure[/bold] first.")
+        sys.exit(1)
+
+    missing = []
+    if not config.get("auth", {}).get("api_key"):
+        missing.append("api_key")
+    if not config.get("server", {}).get("url"):
+        missing.append("server url")
+
+    if missing:
+        from rich.console import Console
+
+        console = Console(stderr=True)
+        console.print(f"[red]Config incomplete[/red] (missing: {', '.join(missing)}). Run [bold]cloudclerk configure[/bold].")
+        sys.exit(1)
+
+    return config

cloudclerk-0.1.0/src/cloudclerk/display.py

@@ -0,0 +1,259 @@
+"""Rich display helpers for CloudClerk CLI output."""
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+
+console = Console()
+
+PRIORITY_COLORS = {
+    "high": "red",
+    "medium": "yellow",
+    "low": "green",
+}
+
+
+def format_usd(value) -> str:
+    """Format a numeric value as USD."""
+    if value is None:
+        return "-"
+    return f"${float(value):,.2f}"
+
+
+def format_savings(min_val, max_val) -> str:
+    """Format a savings range as '$X - $Y'."""
+    if min_val is None and max_val is None:
+        return "-"
+    return f"{format_usd(min_val)} - {format_usd(max_val)}"
+
+
+def format_priority(priority: str | None) -> Text:
+    """Return a colored priority label."""
+    if not priority:
+        return Text("-")
+    color = PRIORITY_COLORS.get(priority.lower(), "white")
+    return Text(priority.upper(), style=f"bold {color}")
+
+
+def format_date(date_str: str | None) -> str:
+    """Format an ISO datetime string to a short date."""
+    if not date_str:
+        return "-"
+    return date_str[:10]
+
+
+def render_queries_table(data: dict) -> None:
+    """Render a table of query analyses."""
+    results = data.get("results", [])
+
+    if not results:
+        console.print("[dim]No query analyses found.[/dim]")
+        return
+
+    table = Table(title="Most Expensive Queries", show_lines=True, expand=False)
+    table.add_column("#", justify="right", width=3)
+    table.add_column("Priority", justify="center", width=8)
+    table.add_column("Cost", justify="right", width=12)
+    table.add_column("Savings", justify="right", width=18)
+    table.add_column("Run Date", width=10)
+
+    shas = []
+    for i, row in enumerate(results, 1):
+        sha = row.get("query_sha") or ""
+        shas.append(sha)
+        table.add_row(
+            str(i),
+            format_priority(row.get("priority")),
+            format_usd(row.get("estimated_cost_usd")),
+            format_savings(row.get("potential_savings_min_usd"), row.get("potential_savings_max_usd")),
+            format_date(row.get("run_created_at") or row.get("created_at")),
+        )
+
+    console.print(table)
+
+    # Print SHAs below the table so they're fully copy-pasteable
+    console.print()
+    console.print("[bold]Query SHAs[/bold] (use with [bold]cloudclerk queries show <sha>[/bold]):")
+    for i, sha in enumerate(shas, 1):
+        console.print(f"  {i}. {sha}")
+    console.print()
+
+
+def render_query_detail(data: dict) -> None:
+    """Render full details for a single query analysis."""
+    analysis = data.get("analysis", data)
+
+    query_sha = analysis.get("query_sha", "unknown")
+    priority = analysis.get("priority")
+    cost = analysis.get("estimated_cost_usd")
+    savings_min = analysis.get("potential_savings_min_usd")
+    savings_max = analysis.get("potential_savings_max_usd")
+    created = format_date(analysis.get("run_created_at") or analysis.get("created_at"))
+
+    # Header
+    console.print()
+    console.print(f"[bold]Query Analysis:[/bold] {query_sha}")
+    console.print("=" * 50)
+    console.print()
+
+    # Summary info
+    info_lines = [
+        f"[bold]Priority:[/bold]          {format_priority(priority)}",
+        f"[bold]Estimated Cost:[/bold]    {format_usd(cost)}",
+        f"[bold]Potential Savings:[/bold] {format_savings(savings_min, savings_max)}",
+        f"[bold]Analyzed:[/bold]          {created}",
+    ]
+    for line in info_lines:
+        console.print(line)
+
+    # Query execution context from query_data
+    query_data = analysis.get("query_data")
+    if query_data:
+        _render_query_context(query_data)
+
+    # Query pattern (the actual SQL)
+    if query_data:
+        _render_query_pattern(query_data)
+
+    # Recommendations from analysis_result
+    analysis_result = analysis.get("analysis_result")
+    if analysis_result:
+        _render_recommendations(analysis_result)
+        _render_issues(analysis_result)
+
+    console.print()
+
+
+def _format_bytes(num_bytes) -> str:
+    """Format bytes into a human-readable string."""
+    if num_bytes is None:
+        return "-"
+    num = float(num_bytes)
+    for unit in ("B", "KB", "MB", "GB", "TB", "PB"):
+        if abs(num) < 1024:
+            return f"{num:,.1f} {unit}"
+        num /= 1024
+    return f"{num:,.1f} EB"
+
+
+def _render_query_context(query_data: dict) -> None:
+    """Render execution context from query_data."""
+    lines = []
+
+    execution_count = query_data.get("execution_count")
+    if execution_count is not None:
+        lines.append(f"  [bold]Executions:[/bold]       {execution_count:,}")
+
+    statement_type = query_data.get("statement_type")
+    if statement_type:
+        lines.append(f"  [bold]Statement Type:[/bold]  {statement_type}")
+
+    distinct_users = query_data.get("distinct_users")
+    if distinct_users is not None:
+        lines.append(f"  [bold]Distinct Users:[/bold]  {distinct_users}")
+
+    bytes_billed = query_data.get("sum_bytes_billed")
+    if bytes_billed is not None:
+        lines.append(f"  [bold]Total Bytes Billed:[/bold] {_format_bytes(bytes_billed)}")
+
+    first_seen = query_data.get("first_seen")
+    last_seen = query_data.get("last_seen")
+    if first_seen and last_seen:
+        lines.append(f"  [bold]Observed:[/bold]        {first_seen} to {last_seen}")
+
+    tables = query_data.get("referenced_tables", [])
+    if tables:
+        lines.append(f"  [bold]Referenced Tables:[/bold]")
+        for t in tables:
+            lines.append(f"    - {t}")
+
+    dest = query_data.get("destination_table")
+    if dest:
+        lines.append(f"  [bold]Destination:[/bold]     {dest}")
+
+    if lines:
+        console.print()
+        console.print(Panel("\n".join(lines), title="Query Context", border_style="cyan"))
+
+
+def _render_recommendations(analysis_result: dict) -> None:
+    """Render the recommendations section."""
+    recommendations = analysis_result.get("recommendations", [])
+    if not recommendations:
+        return
+
+    console.print()
+    lines = []
+    for i, rec in enumerate(recommendations, 1):
+        if isinstance(rec, dict):
+            action = rec.get("action") or rec.get("title") or rec.get("recommendation", "")
+            description = rec.get("description", "")
+            savings = rec.get("estimated_savings_usd", "")
+            sql = rec.get("sql_example", "")
+
+            lines.append(f"  [bold green]{i}. {action}[/bold green]")
+            if description:
+                lines.append(f"     {description}")
+            if savings:
+                lines.append(f"     [dim]Estimated savings: {savings}[/dim]")
+            if sql:
+                lines.append(f"     [blue]SQL: {sql}[/blue]")
+            lines.append("")
+        else:
+            lines.append(f"  [bold]{i}.[/bold] {rec}")
+            lines.append("")
+
+    console.print(Panel("\n".join(lines).rstrip(), title="Recommendations", border_style="green"))
+
+
+def _render_issues(analysis_result: dict) -> None:
+    """Render the issues section."""
+    issues = analysis_result.get("issues", [])
+    if not issues:
+        return
+
+    lines = []
+    for i, issue in enumerate(issues, 1):
+        if isinstance(issue, dict):
+            issue_type = issue.get("type", "")
+            severity = issue.get("severity", "")
+            description = issue.get("description", "")
+            impact = issue.get("impact_estimate", "")
+
+            color = PRIORITY_COLORS.get(severity.lower(), "white")
+            label = f"[{color}][{severity.upper()}][/{color}]" if severity else ""
+            type_label = issue_type.replace("_", " ").title() if issue_type else "Issue"
+
+            lines.append(f"  [bold]{i}. {type_label}[/bold] {label}")
+            if description:
+                lines.append(f"     {description}")
+            if impact:
+                lines.append(f"     [dim]Impact: {impact}[/dim]")
+            lines.append("")
+        else:
+            lines.append(f"  [bold]{i}.[/bold] {issue}")
+            lines.append("")
+
+    console.print(Panel("\n".join(lines).rstrip(), title="Issues Found", border_style="yellow"))
+
+
+def _render_query_pattern(query_data: dict) -> None:
+    """Render the query pattern section."""
+    # query_data is a JSON blob from ClickHouse — try common field names
+    query_text = (
+        query_data.get("query")
+        or query_data.get("query_text")
+        or query_data.get("parameterized_query")
+        or query_data.get("query_pattern")
+    )
+    if not query_text:
+        return
+
+    # Truncate very long queries
+    if len(query_text) > 1000:
+        query_text = query_text[:1000] + "\n  ... (truncated)"
+
+    console.print()
+    console.print(Panel(query_text, title="Query Pattern", border_style="blue"))

cloudclerk-0.1.0/tests/test_client.py

@@ -0,0 +1,71 @@
+"""Tests for the HTTP client."""
+
+import json
+
+import httpx
+import pytest
+
+from cloudclerk.client import APIError, CloudClerkClient
+
+
+@pytest.fixture
+def mock_client(monkeypatch):
+    """Create a CloudClerkClient without loading config."""
+    monkeypatch.setattr(
+        "cloudclerk.client.require_config",
+        lambda: {"auth": {"api_key": "cc_live_test"}, "server": {"url": "https://test.cloudclerk.io"}},
+    )
+    return CloudClerkClient()
+
+
+def test_client_sets_auth_header(mock_client):
+    assert mock_client._client.headers["authorization"] == "Bearer cc_live_test"
+
+
+def test_client_sets_base_url(mock_client):
+    assert str(mock_client._client.base_url) == "https://test.cloudclerk.io"
+
+
+def test_client_strips_trailing_slash(monkeypatch):
+    monkeypatch.setattr(
+        "cloudclerk.client.require_config",
+        lambda: {"auth": {"api_key": "cc_live_test"}, "server": {"url": "https://test.cloudclerk.io/"}},
+    )
+    client = CloudClerkClient()
+    assert str(client._client.base_url) == "https://test.cloudclerk.io"
+
+
+def test_client_explicit_params():
+    client = CloudClerkClient(api_key="cc_live_abc", server_url="https://my.server.io")
+    assert client._api_key == "cc_live_abc"
+    assert client._base_url == "https://my.server.io"
+
+
+def test_list_queries_params(mock_client, monkeypatch):
+    captured = {}
+
+    def mock_get(self, path, params=None):
+        captured["path"] = path
+        captured["params"] = params
+        return {"results": []}
+
+    monkeypatch.setattr(CloudClerkClient, "get", mock_get)
+
+    mock_client.list_queries(limit=5, priority="high")
+    assert captured["path"] == "/api/v1/cost-optimization/analyses/"
+    assert captured["params"]["page_size"] == 5
+    assert captured["params"]["priority"] == "high"
+    assert captured["params"]["ordering"] == "-estimated_cost_usd"
+
+
+def test_get_query_path(mock_client, monkeypatch):
+    captured = {}
+
+    def mock_get(self, path, params=None):
+        captured["path"] = path
+        return {"analysis": {}}
+
+    monkeypatch.setattr(CloudClerkClient, "get", mock_get)
+
+    mock_client.get_query("abc123def456")
+    assert captured["path"] == "/api/v1/cost-optimization/analyses/abc123def456/"

cloudclerk-0.1.0/tests/test_commands.py

@@ -0,0 +1,67 @@
+"""Tests for CLI commands."""
+
+import json
+
+from typer.testing import CliRunner
+
+from cloudclerk.cli import app
+
+runner = CliRunner()
+
+
+def test_version_flag():
+    result = runner.invoke(app, ["--version"])
+    assert result.exit_code == 0
+    assert "cloudclerk" in result.output
+    assert "0.1.0" in result.output
+
+
+def test_help():
+    result = runner.invoke(app, ["--help"])
+    assert result.exit_code == 0
+    assert "configure" in result.output
+    assert "queries" in result.output
+
+
+def test_queries_help():
+    result = runner.invoke(app, ["queries", "--help"])
+    assert result.exit_code == 0
+    assert "top" in result.output
+    assert "show" in result.output
+
+
+def test_queries_top_invalid_priority(monkeypatch):
+    monkeypatch.setattr(
+        "cloudclerk.config.require_config",
+        lambda: {"auth": {"api_key": "cc_live_test"}, "server": {"url": "https://test.io"}},
+    )
+    result = runner.invoke(app, ["queries", "top", "--priority", "invalid"])
+    assert result.exit_code == 1
+
+
+def test_queries_top_json_output(monkeypatch):
+    mock_data = {"results": [{"query_sha": "abc123", "estimated_cost_usd": "100.00", "priority": "high"}]}
+
+    monkeypatch.setattr(
+        "cloudclerk.commands.queries.CloudClerkClient",
+        lambda: type("MockClient", (), {"list_queries": lambda self, **kw: mock_data})(),
+    )
+
+    result = runner.invoke(app, ["queries", "top", "--json"])
+    assert result.exit_code == 0
+    parsed = json.loads(result.output)
+    assert parsed["results"][0]["query_sha"] == "abc123"
+
+
+def test_queries_show_json_output(monkeypatch):
+    mock_data = {"analysis": {"query_sha": "abc123", "priority": "high", "analysis_result": {"recommendations": []}}}
+
+    monkeypatch.setattr(
+        "cloudclerk.commands.queries.CloudClerkClient",
+        lambda: type("MockClient", (), {"get_query": lambda self, sha: mock_data})(),
+    )
+
+    result = runner.invoke(app, ["queries", "show", "abc123", "--json"])
+    assert result.exit_code == 0
+    parsed = json.loads(result.output)
+    assert parsed["analysis"]["query_sha"] == "abc123"

cloudclerk-0.1.0/tests/test_config.py

@@ -0,0 +1,39 @@
+"""Tests for config management."""
+
+from pathlib import Path
+
+from cloudclerk.config import get_config_path, load_config, save_config
+
+
+def test_save_and_load_config(tmp_path, monkeypatch):
+    monkeypatch.setattr("cloudclerk.config.get_config_dir", lambda: tmp_path)
+    monkeypatch.setattr("cloudclerk.config.get_config_path", lambda: tmp_path / "config.toml")
+
+    path = save_config(api_key="cc_live_testkey123", server_url="https://example.com")
+    assert path.exists()
+
+    config = load_config()
+    assert config["auth"]["api_key"] == "cc_live_testkey123"
+    assert config["server"]["url"] == "https://example.com"
+
+
+def test_load_config_returns_none_when_missing(tmp_path, monkeypatch):
+    monkeypatch.setattr("cloudclerk.config.get_config_path", lambda: tmp_path / "nonexistent.toml")
+    assert load_config() is None
+
+
+def test_require_config_exits_when_missing(tmp_path, monkeypatch):
+    monkeypatch.setattr("cloudclerk.config.get_config_path", lambda: tmp_path / "nonexistent.toml")
+
+    import pytest
+
+    with pytest.raises(SystemExit):
+        from cloudclerk.config import require_config
+
+        require_config()
+
+
+def test_get_config_path_is_in_home():
+    path = get_config_path()
+    assert ".cloudclerk" in str(path)
+    assert path.name == "config.toml"

cloudclerk-0.1.0/tests/test_display.py

@@ -0,0 +1,34 @@
+"""Tests for display formatting helpers."""
+
+from cloudclerk.display import format_date, format_priority, format_savings, format_usd
+
+
+def test_format_usd():
+    assert format_usd(1234.56) == "$1,234.56"
+    assert format_usd(0) == "$0.00"
+    assert format_usd(None) == "-"
+
+
+def test_format_savings():
+    assert format_savings(100, 500) == "$100.00 - $500.00"
+    assert format_savings(None, None) == "-"
+
+
+def test_format_priority_colors():
+    high = format_priority("high")
+    assert high.plain == "HIGH"
+
+    medium = format_priority("medium")
+    assert medium.plain == "MEDIUM"
+
+    low = format_priority("low")
+    assert low.plain == "LOW"
+
+    none = format_priority(None)
+    assert none.plain == "-"
+
+
+def test_format_date():
+    assert format_date("2026-03-25T14:30:00Z") == "2026-03-25"
+    assert format_date(None) == "-"
+    assert format_date("") == "-"