kctl-grafana 0.2.0__tar.gz

kctl_grafana-0.2.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local

kctl_grafana-0.2.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-grafana
+Version: 0.2.0
+Summary: Kodemeio Grafana CLI — manage Grafana monitoring platform
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.4.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'

kctl_grafana-0.2.0/README.md

@@ -0,0 +1,171 @@
+# kctl-grafana
+
+Grafana monitoring platform CLI — manage dashboards, datasources, alerts, users, and backups.
+
+## Installation
+
+```bash
+uv tool install kctl-grafana
+```
+
+Requires `kctl-lib>=0.4.0` (installed automatically).
+
+## Quick Start
+
+```bash
+# Configure a profile
+kctl-grafana config init
+
+# Check Grafana connectivity
+kctl-grafana health check
+
+# View platform status
+kctl-grafana status overview
+
+# List all dashboards
+kctl-grafana dashboard list
+
+# Export a dashboard to file
+kctl-grafana dashboard export <uid> --output my-dashboard.json
+
+# Add a deploy annotation
+kctl-grafana annotation add "Deployed v1.2.3" --tags deploy,production
+
+# Backup all dashboards and datasources
+kctl-grafana backup create --output ./grafana-backup
+```
+
+## Command Groups
+
+| Group | Description | Key Commands |
+|-------|-------------|--------------|
+| `config` | Profile management | `init`, `add`, `use`, `show`, `validate`, `remove`, `set`, `profiles`, `current` |
+| `health` | API health checks | `check`, `detailed` |
+| `status` | Quick overview | `overview` |
+| `dashboard` | Dashboard management | `list`, `show`, `export`, `import`, `search`, `star` |
+| `datasource` | Datasource management | `list`, `show`, `test` |
+| `alert` | Alert rule management | `list`, `show`, `silence`, `contacts` |
+| `folder` | Folder organization | `list`, `create`, `delete` |
+| `annotation` | Deploy markers & events | `add`, `list` |
+| `user` | Organization user management | `list`, `add` |
+| `backup` | Backup and restore | `create`, `restore` |
+| `selftest` | Self-test diagnostics | `run` |
+
+## Command Reference
+
+### dashboard
+
+```bash
+kctl-grafana dashboard list
+kctl-grafana dashboard show <uid>
+kctl-grafana dashboard export <uid> --output dashboard.json
+kctl-grafana dashboard import dashboard.json --folder <folder-uid>
+kctl-grafana dashboard search "kubernetes"
+kctl-grafana dashboard star <uid>
+kctl-grafana dashboard star <uid> --unstar
+```
+
+### datasource
+
+```bash
+kctl-grafana datasource list
+kctl-grafana datasource show <name>
+kctl-grafana datasource test              # Test all datasources
+kctl-grafana datasource test <name>       # Test a specific datasource
+```
+
+### alert
+
+```bash
+kctl-grafana alert list
+kctl-grafana alert show <uid>
+kctl-grafana alert silence <uid> --duration 1h --comment "Maintenance window"
+kctl-grafana alert contacts
+```
+
+### annotation
+
+```bash
+kctl-grafana annotation add "Deploy v2.0" --tags deploy,prod
+kctl-grafana annotation add "Incident" --dashboard <uid>
+kctl-grafana annotation list --from 24h --tags deploy
+```
+
+### backup
+
+```bash
+kctl-grafana backup create --output ./backup-2026-04-05
+kctl-grafana backup restore ./backup-2026-04-05
+kctl-grafana backup restore ./backup-2026-04-05 --skip-datasources
+```
+
+### folder
+
+```bash
+kctl-grafana folder list
+kctl-grafana folder create "Production Dashboards"
+kctl-grafana folder delete <uid> --force
+```
+
+### user
+
+```bash
+kctl-grafana user list
+kctl-grafana user add user@example.com --role Editor
+```
+
+## Global Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--profile` | `-p` | Config profile name |
+| `--format` | `-f` | Output format: `pretty`, `json`, `csv`, `yaml` |
+| `--json` | | Shortcut for `--format json` |
+| `--quiet` | `-q` | Suppress info messages |
+| `--no-header` | | Omit headers in CSV output |
+| `--debug` | | Enable debug logging |
+| `--url` | | Grafana API URL override |
+| `--api-key` | | Grafana API key override |
+| `--version` | `-V` | Show version and exit |
+
+## Configuration
+
+Config lives in `~/.config/kodemeio/config.yaml` under the `grafana` service key.
+
+```bash
+# Interactive setup
+kctl-grafana config init
+
+# Add a named profile
+kctl-grafana config add --profile production \
+  --url https://grafana.kodeme.io \
+  --api-key <service-account-token>
+
+# Switch active profile
+kctl-grafana config use production
+
+# Show current config (secrets masked)
+kctl-grafana config show
+```
+
+Example `~/.config/kodemeio/config.yaml` entry:
+
+```yaml
+grafana:
+  default_profile: production
+  profiles:
+    production:
+      url: https://grafana.kodeme.io
+      api_key: ${GRAFANA_API_KEY}
+```
+
+## Development
+
+```bash
+cd packages/kctl-grafana
+uv sync --all-extras
+uv run pytest tests/ -v
+uv run mypy src/
+uv run ruff check src/
+uv build
+```

kctl_grafana-0.2.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-grafana"
+version = "0.2.0"
+description = "Kodemeio Grafana CLI — manage Grafana monitoring platform"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.4.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-httpx>=0.35.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[project.scripts]
+kctl-grafana = "kctl_grafana.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[project.entry-points."kctl_grafana.plugins"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_grafana"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_grafana-0.2.0/skills/grafana-admin/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: grafana-admin
+description: >
+  Grafana monitoring platform administration via kctl-grafana CLI (12 groups, ~33 commands).
+  MUST use for ANY kctl-grafana operation.
+  Triggers on: "alert", "annotation", "backup", "check", "config", "contacts", "dashboard", "datasource", "deploy", "detailed", "export", "folder", "generate", "health", "import", "init", "kctl-grafana", "overview", "profile", "remove", "restore", "search", "selftest", "silence", "skill", "star", "status", "test", "user".
+  Auto-generated: 2026-04-05
+  registry_hash: bf42f2813358
+---
+
+# grafana-admin — kctl-grafana CLI Reference
+
+> Auto-generated from `kctl-grafana` command registry. Do not edit manually.
+> To regenerate: `kctl-grafana skill generate`
+> To add custom content: edit `SKILL.extra.md` in the same directory.
+
+## Overview
+
+**CLI:** `kctl-grafana`
+**Command groups:** 12
+**Total commands:** ~33
+**Install:** `cd cli && uv tool install --editable .`
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | JSON output |
+| `--quiet`, `-q` | Suppress info messages |
+| `--format`, `-f` | Output format: pretty/json/csv/yaml |
+| `--no-header` | Omit CSV header row |
+| `--profile`, `-p` | Config profile name |
+| `--version`, `-V` | Show version |
+
+## Command Reference
+
+### `kctl-grafana alert`
+
+Alert rule management.
+
+| Command | Description |
+|---------|-------------|
+| `alert contacts` | List notification contact points. |
+| `alert list` | List alert rules with current state. |
+| `alert show <uid>` | Show alert rule details. |
+| `alert silence <uid> [--duration] [--comment]` | Silence an alert rule for a given duration. |
+
+### `kctl-grafana annotation`
+
+Annotation management (deploy markers, events).
+
+| Command | Description |
+|---------|-------------|
+| `annotation add <text> [--tags] [--dashboard_uid]` | Add an annotation (useful for deploy markers). |
+| `annotation list [--from_time] [--to_time] [--tags] [--limit]` | List recent annotations. |
+
+### `kctl-grafana backup`
+
+Backup and restore dashboards and datasources.
+
+| Command | Description |
+|---------|-------------|
+| `backup create [--output_dir]` | Export all dashboards and datasources to a backup directory. |
+| `backup restore <backup_dir> [--skip_datasources] [--skip_dashboards]` | Restore dashboards and datasources from a backup directory. |
+
+### `kctl-grafana config`
+
+Manage CLI configuration and profiles.
+
+| Command | Description |
+|---------|-------------|
+| `config export` | Export current configuration as YAML. |
+| `config init [--url] [--api_key] [--org_id] [--name]` | Initialize CLI configuration. |
+| `config remove <name> [--force]` | Remove a profile. |
+| `config show` | Show configuration (keys masked). |
+| `config test` | Test API connection. |
+| `config use <name>` | Switch default profile. |
+
+### `kctl-grafana dashboard`
+
+Dashboard management.
+
+| Command | Description |
+|---------|-------------|
+| `dashboard export <uid> [--output_file]` | Export dashboard JSON to file. |
+| `dashboard import <file_path> [--folder_uid] [--overwrite]` | Import dashboard from JSON file. |
+| `dashboard list` | List all dashboards. |
+| `dashboard search <query>` | Search dashboards by name or tag. |
+| `dashboard show <uid>` | Show dashboard metadata and panel summary. |
+| `dashboard star <uid> [--unstar]` | Star or unstar a dashboard. |
+
+### `kctl-grafana datasource`
+
+Datasource management.
+
+| Command | Description |
+|---------|-------------|
+| `datasource list` | List all datasources with type and status. |
+| `datasource show <name>` | Show datasource configuration details. |
+| `datasource test [--name]` | Test datasource connectivity. |
+
+### `kctl-grafana folder`
+
+Folder organization.
+
+| Command | Description |
+|---------|-------------|
+| `folder create <title> [--uid]` | Create a new folder. |
+| `folder delete <uid> [--force]` | Delete a folder and all its dashboards. |
+| `folder list` | List all folders. |
+
+### `kctl-grafana health`
+
+Health checks for Grafana API.
+
+| Command | Description |
+|---------|-------------|
+| `health check` | Check Grafana API connectivity, version, and org info. |
+| `health detailed` | Detailed health check including all datasources. |
+
+### `kctl-grafana selftest`
+
+Self-test diagnostics.
+
+| Command | Description |
+|---------|-------------|
+| `selftest run` | Run diagnostic checks for kctl-grafana. |
+
+### `kctl-grafana skill`
+
+Claude Code skill management.
+
+| Command | Description |
+|---------|-------------|
+| `skill generate [--output] [--install] [--check]` | Auto-generate SKILL.md from CLI command registry. |
+
+**Examples:**
+```bash
+kctl-grafana skill generate
+kctl-grafana skill generate --install
+kctl-grafana skill generate --check
+```
+
+### `kctl-grafana status`
+
+Quick status overview.
+
+| Command | Description |
+|---------|-------------|
+| `status overview` | Show Grafana status overview: dashboard count, datasource health, active alerts, version. |
+
+### `kctl-grafana user`
+
+Organization user management.
+
+| Command | Description |
+|---------|-------------|
+| `user add <email> [--role]` | Add a user to the organization. |
+| `user list` | List organization users. |
+
+## Configuration
+
+Shared config: `~/.config/kodemeio/config.yaml`
+
+```bash
+kctl-grafana config init       # Interactive setup
+kctl-grafana config show       # Show current config
+kctl-grafana config profiles   # List profiles
+kctl-grafana config current    # Show active profile
+kctl-grafana config validate   # Verify config
+```

kctl_grafana-0.2.0/src/kctl_grafana/__init__.py

@@ -0,0 +1,3 @@
+"""kctl-grafana: Kodemeio Grafana CLI."""
+
+__version__ = "0.2.0"

kctl_grafana-0.2.0/src/kctl_grafana/__main__.py

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

kctl_grafana-0.2.0/src/kctl_grafana/cli.py

@@ -0,0 +1,146 @@
+"""Main CLI entry point for kctl-grafana."""
+
+from __future__ import annotations
+
+
+from typing import Annotated
+
+import typer
+from kctl_lib import KctlError, handle_cli_error
+
+from kctl_grafana import __version__
+from kctl_grafana.commands.alert import app as alert_app
+from kctl_grafana.commands.annotation import app as annotation_app
+from kctl_grafana.commands.backup import app as backup_app
+from kctl_grafana.commands.config_cmd import app as config_app
+from kctl_grafana.commands.dashboard import app as dashboard_app
+from kctl_grafana.commands.datasource import app as datasource_app
+from kctl_grafana.commands.folder import app as folder_app
+from kctl_grafana.commands.health import app as health_app
+from kctl_grafana.commands.selftest import app as selftest_app
+from kctl_grafana.commands.status import app as status_app
+from kctl_grafana.commands.user import app as user_app
+from kctl_grafana.core.callbacks import AppContext
+from kctl_grafana.commands.doctor_cmd import app as doctor_app
+from kctl_grafana.commands.skill_cmd import app as skill_app
+from kctl_lib.self_update import notify_if_outdated
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-grafana {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-grafana",
+    help="Kodemeio Grafana CLI - manage your Grafana monitoring platform.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON (shortcut for --format json)")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = False,
+    output_format: Annotated[
+        str, typer.Option("--format", "-f", help="Output format: pretty, json, csv, yaml")
+    ] = "pretty",
+    no_header: Annotated[bool, typer.Option("--no-header", help="Omit headers in CSV output")] = False,
+    debug: Annotated[bool, typer.Option("--debug", help="Enable debug logging")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile name")] = None,
+    url: Annotated[str | None, typer.Option("--url", help="API URL override")] = None,
+    api_key: Annotated[str | None, typer.Option("--api-key", help="API key override")] = None,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """Kodemeio Grafana CLI."""
+    import os
+
+    if debug:
+        os.environ["KCTL_DEBUG"] = "1"
+
+    effective_format = "json" if json_output else output_format
+
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output or effective_format == "json",
+        quiet=quiet,
+        format=effective_format,
+        no_header=no_header,
+        debug=debug,
+        profile=profile,
+        url_override=url,
+        api_key_override=api_key,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-grafana", __version__)
+
+
+# Command groups
+app.add_typer(config_app, name="config")
+app.add_typer(health_app, name="health")
+app.add_typer(status_app, name="status")
+app.add_typer(dashboard_app, name="dashboard")
+app.add_typer(datasource_app, name="datasource")
+app.add_typer(alert_app, name="alert")
+app.add_typer(folder_app, name="folder")
+app.add_typer(annotation_app, name="annotation")
+app.add_typer(user_app, name="user")
+app.add_typer(backup_app, name="backup")
+app.add_typer(selftest_app, name="selftest")
+app.add_typer(doctor_app, name="doctor")
+app.add_typer(skill_app, name="skill", hidden=True)
+
+
+@app.command("self-update")
+def self_update_cmd(ctx: typer.Context) -> None:
+    """Check for updates and upgrade kctl-grafana."""
+    actx = ctx.obj
+    out = actx.output
+
+    from kctl_lib.self_update import check_update
+    from kctl_lib.self_update import update as do_update
+
+    latest = check_update("kctl-grafana", __version__)
+    if latest:
+        out.info(f"Updating to {latest}...")
+        do_update("kctl-grafana")
+        out.success(f"Updated to {latest}")
+    else:
+        out.success("Already up to date")
+
+
+@app.command()
+def completions(
+    shell: Annotated[str, typer.Argument(help="Shell type: zsh, bash, fish")] = "zsh",
+    install: Annotated[bool, typer.Option("--install", help="Install completions")] = False,
+) -> None:
+    """Generate or install shell completions."""
+    from kctl_lib.completions import get_completion_script, install_completions
+
+    if install:
+        path = install_completions("kctl-grafana", shell)
+        if path:
+            typer.echo(f"Completions installed to {path}")
+        else:
+            typer.echo(f"Could not install completions for {shell}", err=True)
+            raise typer.Exit(code=1)
+    else:
+        script = get_completion_script("kctl-grafana", shell)
+        typer.echo(script)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KctlError as e:
+        handle_cli_error(e)
+
+
+if __name__ == "__main__":
+    _run()

kctl_grafana-0.2.0/src/kctl_grafana/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules for kctl-grafana."""