kctl-plausible 0.6.2__tar.gz

kctl_plausible-0.6.2/.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_plausible-0.6.2/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-plausible
+Version: 0.6.2
+Summary: Kodemeio Plausible Analytics CLI — manage Plausible CE via Stats API v1
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.7.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_plausible-0.6.2/README.md

@@ -0,0 +1,120 @@
+# kctl-plausible
+
+Kodemeio Plausible CLI — manage analytics via Stats API.
+
+## Installation
+
+```bash
+# From workspace (development)
+uv tool install --editable packages/kctl-plausible
+
+# From PyPI
+uv tool install kctl-plausible
+```
+
+## Quick Start
+
+```bash
+# Initialize configuration
+kctl-plausible config init
+
+# Test API connectivity
+kctl-plausible config test
+
+# View realtime visitors
+kctl-plausible stats realtime terakidz.com
+
+# List all tracked sites
+kctl-plausible sites list
+
+# View top pages for a site
+kctl-plausible stats pages terakidz.com --period 7d
+```
+
+## Command Groups
+
+| Group | Commands | Description |
+|-------|----------|-------------|
+| `config` | init, add, use, show, set, remove, profiles, current, test, migrate | Manage profiles and credentials |
+| `stats` | realtime, aggregate, timeseries, pages, sources, countries | Analytics data queries |
+| `sites` | list, show, create, delete | Site (domain) management |
+| `goals` | list, create, delete | Conversion goal management |
+| `export` | csv, json | Bulk data export |
+| `doctor` | check | Diagnostic checks (API connectivity, auth, config) |
+
+## Global Options
+
+All commands accept these options:
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--json` | | Output as JSON |
+| `--format` | `-f` | Output format: `pretty`, `json`, `csv`, `yaml` |
+| `--quiet` | `-q` | Suppress info messages |
+| `--no-header` | | Omit header row in table/CSV output |
+| `--profile` | `-p` | Config profile name |
+| `--version` | `-V` | Show version and exit |
+
+## Configuration
+
+Config is stored in `~/.config/kodemeio/config.yaml` under the `plausible` key.
+
+```bash
+# Create a new profile
+kctl-plausible config init
+
+# Add a named profile
+kctl-plausible config add --profile prod
+
+# Switch active profile
+kctl-plausible config use prod
+
+# Show current config (secrets masked)
+kctl-plausible config show
+
+# Test connectivity
+kctl-plausible config test
+```
+
+### Config Keys
+
+| Key | Description |
+|-----|-------------|
+| `url` | Plausible instance URL (e.g. `https://plausible.io` or self-hosted) |
+| `api_key` | Plausible API key with Stats API access |
+
+### Profile Example
+
+```yaml
+profiles:
+  kodemeio:
+    plausible:
+      url: https://analytics.kodeme.io
+      api_key: ${PLAUSIBLE_API_KEY}
+```
+
+## Common Workflows
+
+```bash
+# View aggregate stats for a period
+kctl-plausible stats aggregate terakidz.com --period 30d --metrics visitors,pageviews
+
+# Check top traffic sources
+kctl-plausible stats sources terakidz.com --period 7d
+
+# Create a new conversion goal
+kctl-plausible goals create terakidz.com --event "Signup"
+
+# Export monthly data as CSV
+kctl-plausible export csv terakidz.com --period month > analytics.csv
+```
+
+## Development
+
+```bash
+cd packages/kctl-plausible
+uv sync --all-extras
+uv run pytest tests/ -v
+uv run mypy src/
+uv run ruff check src/
+```

kctl_plausible-0.6.2/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-plausible"
+version = "0.6.2"
+description = "Kodemeio Plausible Analytics CLI — manage Plausible CE via Stats API v1"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.7.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-plausible = "kctl_plausible.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_plausible"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_plausible-0.6.2/skills/plausible-admin/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: plausible-admin
+description: >
+  Plausible Analytics management via kctl-plausible CLI.
+  MUST use for ANY kctl-plausible operation.
+  Triggers on: "plausible, analytics, stats, pageviews, visitors, traffic, goals".
+---
+
+# kctl-plausible
+
+Kodemeio Plausible Analytics CLI - query and manage your Plausible CE instance (stats, sites, goals, exports).
+
+## Installation
+
+```bash
+uv tool install kctl-plausible
+```
+
+## Global Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--json` | | JSON output (shortcut for --format json) |
+| `--quiet` | `-q` | Suppress info messages |
+| `--format` | `-f` | Output format: pretty/json/csv/yaml |
+| `--no-header` | | Omit headers in CSV output |
+| `--debug` | | Enable debug logging |
+| `--profile` | `-p` | Config profile name |
+| `--url` | | API URL override |
+| `--api-key` | | API key override |
+| `--version` | `-V` | Show version |
+
+## Commands
+
+### config
+- `kctl-plausible config init` — Initialize CLI configuration
+- `kctl-plausible config show` — Show configuration (keys masked)
+- `kctl-plausible config test` — Test API connection
+
+### stats
+- `kctl-plausible stats realtime` — Get current realtime visitors count
+- `kctl-plausible stats aggregate` — Get aggregate stats for a site
+- `kctl-plausible stats breakdown` — Get breakdown stats by a property
+- `kctl-plausible stats timeseries` — Get timeseries stats for a site
+
+### sites
+- `kctl-plausible sites list` — List all sites
+- `kctl-plausible sites create` — Create (provision) a new site
+- `kctl-plausible sites delete` — Delete a site
+- `kctl-plausible sites info` — Get site details
+
+### goals
+- `kctl-plausible goals list` — List all goals for a site
+- `kctl-plausible goals create` — Create a new goal for a site
+- `kctl-plausible goals delete` — Delete a goal from a site
+
+### export
+- `kctl-plausible export csv` — Export breakdown stats as CSV
+- `kctl-plausible export json` — Export breakdown stats as JSON
+
+### doctor
+- `kctl-plausible doctor` — Run diagnostic checks
+
+## Configuration
+
+Service key: `plausible` in `~/.config/kodemeio/config.yaml`
+
+```yaml
+profiles:
+  terakidz:
+    plausible:
+      url: https://analytics.kodeme.io
+      api_key: <key>
+```

kctl_plausible-0.6.2/src/kctl_plausible/__init__.py

@@ -0,0 +1,3 @@
+"""kctl-plausible: Kodemeio Plausible Analytics CLI."""
+
+__version__ = "0.6.2"

kctl_plausible-0.6.2/src/kctl_plausible/__main__.py

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

kctl_plausible-0.6.2/src/kctl_plausible/cli.py

@@ -0,0 +1,97 @@
+"""Main CLI entry point for kctl-plausible."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from kctl_lib import KctlError, handle_cli_error
+
+from kctl_plausible import __version__
+from kctl_plausible.commands.config_cmd import app as config_app
+from kctl_plausible.commands.doctor import app as doctor_app
+from kctl_plausible.commands.export import app as export_app
+from kctl_plausible.commands.goals import app as goals_app
+from kctl_plausible.commands.sites import app as sites_app
+from kctl_plausible.commands.stats import app as stats_app
+from kctl_plausible.core.callbacks import AppContext
+from kctl_lib.self_update import notify_if_outdated
+from kctl_lib.tui import add_tui_command
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-plausible {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-plausible",
+    help="Kodemeio Plausible Analytics CLI - query and manage your Plausible CE instance.",
+    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 Plausible Analytics 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-plausible", __version__)
+
+
+# ---------------------------------------------------------------------------
+# Command groups
+# ---------------------------------------------------------------------------
+app.add_typer(config_app, name="config")
+app.add_typer(stats_app, name="stats")
+app.add_typer(sites_app, name="sites")
+app.add_typer(goals_app, name="goals")
+app.add_typer(export_app, name="export")
+app.add_typer(doctor_app, name="doctor")
+add_tui_command(app, service_key="plausible", version=__version__)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KctlError as e:
+        handle_cli_error(e)
+
+
+if __name__ == "__main__":
+    _run()

kctl_plausible-0.6.2/src/kctl_plausible/commands/config_cmd.py

@@ -0,0 +1,105 @@
+"""Configuration management commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_plausible.core.callbacks import AppContext
+from kctl_plausible.core.config import (
+    CONFIG_FILE,
+    SERVICE_KEY,
+    ServiceConfig,
+    get_all_services_in_profile,
+    get_default_profile,
+    get_profile_names,
+    resolve_active_profile_name,
+    set_default_profile,
+    set_service_config,
+)
+
+app = typer.Typer(help="Manage CLI configuration and profiles.")
+
+
+def _mask(val: str) -> str:
+    if not val:
+        return "[dim]not set[/dim]"
+    return f"{val[:4]}{'*' * max(0, len(val) - 8)}{val[-4:]}" if len(val) > 10 else "****"
+
+
+@app.command()
+def init(
+    ctx: typer.Context,
+    url: Annotated[str | None, typer.Option("--url")] = None,
+    api_key: Annotated[str | None, typer.Option("--api-key")] = None,
+    name: Annotated[str | None, typer.Option("--name", "-n")] = None,
+) -> None:
+    """Initialize CLI configuration."""
+    c: AppContext = ctx.obj
+    out = c.output
+    profile_name = name or typer.prompt("Profile name", default="kodemeio")
+    api_url = url or typer.prompt("Plausible URL (e.g. https://plausible.example.com)")
+    key = api_key or typer.prompt("API key", hide_input=True)
+
+    svc = ServiceConfig(url=api_url, api_key=key)
+    set_service_config(profile_name, svc)
+    if len(get_profile_names()) <= 1:
+        set_default_profile(profile_name)
+    out.success(f"Configuration saved to {CONFIG_FILE}")
+    out.kv("Profile", profile_name)
+    out.kv("URL", api_url)
+    out.kv("API Key", _mask(key))
+
+
+@app.command()
+def show(ctx: typer.Context) -> None:
+    """Show configuration (keys masked)."""
+    c: AppContext = ctx.obj
+    out = c.output
+    default = get_default_profile()
+    sections = [
+        (
+            "General",
+            [
+                ("Config file", str(CONFIG_FILE)),
+                ("Default profile", default),
+                ("Service key", SERVICE_KEY),
+            ],
+        )
+    ]
+    for pname in get_profile_names():
+        marker = " [green](default)[/green]" if pname == default else ""
+        services = get_all_services_in_profile(pname)
+        kvs = []
+        for svc_name, svc_data in services.items():
+            if not isinstance(svc_data, dict):
+                continue
+            indicator = "[green]●[/green]" if svc_name == SERVICE_KEY else "[dim]○[/dim]"
+            kvs.append(
+                (
+                    f"{indicator} {svc_name}",
+                    f"{svc_data.get('url', '')}  key: {_mask(svc_data.get('api_key', ''))}",
+                )
+            )
+        sections.append((f"Profile: {pname}{marker}", kvs or [("(empty)", "")]))
+    out.detail("Configuration", sections)
+
+
+@app.command()
+def test(ctx: typer.Context) -> None:
+    """Test API connection."""
+    c: AppContext = ctx.obj
+    out = c.output
+    active = resolve_active_profile_name(c.profile)
+    out.info(f"Testing profile '{active}' → {SERVICE_KEY}")
+    try:
+        status = c.client.check_health()
+        if status == 200:
+            out.success("Connected to Plausible Analytics API")
+        else:
+            out.error(f"Connection failed: HTTP {status}")
+            raise typer.Exit(1)
+    except Exception as e:
+        out.error(f"Connection failed: {e}")
+        raise typer.Exit(1) from e

kctl_plausible-0.6.2/src/kctl_plausible/commands/doctor.py

@@ -0,0 +1,82 @@
+"""Doctor diagnostic checks for kctl-plausible."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import typer
+from kctl_lib.doctor_base import CheckResult, DoctorCheck, run_doctor
+
+from kctl_plausible.core.callbacks import AppContext
+
+
+@dataclass
+class APIConnectivityCheck:
+    """Check that the configured API endpoint is reachable."""
+
+    name: str = "API Connectivity"
+
+    def run(self) -> CheckResult:
+        try:
+            from kctl_plausible.core.config import get_service_config, resolve_active_profile_name
+
+            profile = resolve_active_profile_name()
+            cfg = get_service_config(profile)
+            url = cfg.url or ""
+            if not url:
+                return CheckResult(
+                    name=self.name,
+                    status="fail",
+                    message="No URL configured",
+                    fix_command="kctl-plausible config init",
+                )
+            return CheckResult(name=self.name, status="ok", message=f"URL: {url}")
+        except Exception as e:
+            return CheckResult(name=self.name, status="warn", message=str(e))
+
+
+@dataclass
+class AuthCheck:
+    """Check that authentication credentials are configured."""
+
+    name: str = "Authentication"
+
+    def run(self) -> CheckResult:
+        try:
+            from kctl_plausible.core.config import get_service_config, resolve_active_profile_name
+
+            profile = resolve_active_profile_name()
+            cfg = get_service_config(profile)
+            token = cfg.api_key or ""
+            if not token:
+                return CheckResult(
+                    name=self.name,
+                    status="fail",
+                    message="No API key configured",
+                    fix_command="kctl-plausible config init",
+                )
+            masked = token[:4] + "****" + token[-4:] if len(token) > 8 else "****"
+            return CheckResult(name=self.name, status="ok", message=f"API key configured ({masked})")
+        except Exception as e:
+            return CheckResult(name=self.name, status="warn", message=str(e))
+
+
+app = typer.Typer(help="Run diagnostic checks.", no_args_is_help=False, invoke_without_command=True)
+
+
+@app.callback(invoke_without_command=True)
+def doctor(ctx: typer.Context) -> None:
+    """Run all diagnostic checks."""
+    if ctx.invoked_subcommand is not None:
+        return
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    checks: list[DoctorCheck] = [
+        APIConnectivityCheck(),
+        AuthCheck(),
+    ]
+
+    all_passed = run_doctor(checks, out)  # type: ignore[arg-type]
+    if not all_passed:
+        raise typer.Exit(code=1)

kctl_plausible-0.6.2/src/kctl_plausible/commands/export.py

@@ -0,0 +1,99 @@
+"""Export commands for Plausible Analytics.
+
+Export breakdown data as CSV or JSON to stdout or file.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import sys
+from io import StringIO
+from typing import Annotated
+
+import typer
+
+from kctl_plausible.core.callbacks import AppContext
+
+app = typer.Typer(help="Export Plausible stats data.")
+
+
+def _fetch_breakdown(c: AppContext, site_id: str, period: str, prop: str, metrics: str, limit: int) -> list[dict]:
+    """Fetch breakdown data from the API."""
+    params: dict[str, str | int] = {
+        "site_id": site_id,
+        "period": period,
+        "property": prop,
+        "metrics": metrics,
+        "limit": limit,
+    }
+    result = c.client.get("/stats/breakdown", params=params)
+    if isinstance(result, dict) and "results" in result:
+        return result["results"]
+    if isinstance(result, list):
+        return result
+    return []
+
+
+@app.command("csv")
+def csv_cmd(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain (e.g. example.com)")],
+    prop: Annotated[
+        str, typer.Option("--property", help="Breakdown property: visit:source, visit:page, etc.")
+    ] = "visit:source",
+    period: Annotated[str, typer.Option("--period", "-p", help="Time period")] = "30d",
+    metrics: Annotated[str, typer.Option("--metrics", "-m", help="Comma-separated metrics")] = "visitors,pageviews",
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Max results")] = 100,
+    output: Annotated[str | None, typer.Option("--output", "-o", help="Output file path (default: stdout)")] = None,
+) -> None:
+    """Export breakdown stats as CSV."""
+    c: AppContext = ctx.obj
+    rows = _fetch_breakdown(c, site_id, period, prop, metrics, limit)
+
+    if not rows:
+        c.output.info("No data to export.")
+        return
+
+    columns = list(rows[0].keys())
+    buf = StringIO()
+    writer = csv.DictWriter(buf, fieldnames=columns)
+    writer.writeheader()
+    writer.writerows(rows)
+
+    csv_content = buf.getvalue()
+    if output:
+        with open(output, "w", encoding="utf-8") as f:
+            f.write(csv_content)
+        c.output.success(f"Exported {len(rows)} rows to {output}")
+    else:
+        sys.stdout.write(csv_content)
+
+
+@app.command("json")
+def json_cmd(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain (e.g. example.com)")],
+    prop: Annotated[
+        str, typer.Option("--property", help="Breakdown property: visit:source, visit:page, etc.")
+    ] = "visit:source",
+    period: Annotated[str, typer.Option("--period", "-p", help="Time period")] = "30d",
+    metrics: Annotated[str, typer.Option("--metrics", "-m", help="Comma-separated metrics")] = "visitors,pageviews",
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Max results")] = 100,
+    output: Annotated[str | None, typer.Option("--output", "-o", help="Output file path (default: stdout)")] = None,
+) -> None:
+    """Export breakdown stats as JSON."""
+    c: AppContext = ctx.obj
+    rows = _fetch_breakdown(c, site_id, period, prop, metrics, limit)
+
+    if not rows:
+        c.output.info("No data to export.")
+        return
+
+    json_content = json.dumps(rows, indent=2)
+    if output:
+        with open(output, "w", encoding="utf-8") as f:
+            f.write(json_content)
+        c.output.success(f"Exported {len(rows)} rows to {output}")
+    else:
+        sys.stdout.write(json_content + "\n")

kctl_plausible-0.6.2/src/kctl_plausible/commands/goals.py

@@ -0,0 +1,82 @@
+"""Goal management commands for Plausible Analytics.
+
+Supports listing, creating, and deleting goals for a site.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_plausible.core.callbacks import AppContext
+
+app = typer.Typer(help="Manage Plausible goals.")
+
+
+@app.command("list")
+def list_cmd(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain (e.g. example.com)")],
+) -> None:
+    """List all goals for a site."""
+    c: AppContext = ctx.obj
+    out = c.output
+    result = c.client.get("/sites/goals", params={"site_id": site_id})
+    if isinstance(result, dict) and "goals" in result:
+        goals = result["goals"]
+    elif isinstance(result, list):
+        goals = result
+    else:
+        goals = [result] if result else []
+
+    out.table(goals, columns=["id", "goal_type", "event_name", "page_path"], title=f"Goals — {site_id}")
+
+
+@app.command()
+def create(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain")],
+    goal_type: Annotated[str, typer.Option("--type", "-t", help="Goal type: event or page_path")] = "event",
+    event_name: Annotated[str | None, typer.Option("--event-name", "-e", help="Event name (for event goals)")] = None,
+    page_path: Annotated[str | None, typer.Option("--page-path", help="Page path (for page_path goals)")] = None,
+) -> None:
+    """Create a new goal for a site."""
+    c: AppContext = ctx.obj
+    out = c.output
+
+    payload: dict[str, str] = {"site_id": site_id, "goal_type": goal_type}
+    if goal_type == "event":
+        if not event_name:
+            out.error("--event-name is required for event goals")
+            raise typer.Exit(1)
+        payload["event_name"] = event_name
+    elif goal_type == "page_path":
+        if not page_path:
+            out.error("--page-path is required for page_path goals")
+            raise typer.Exit(1)
+        payload["page_path"] = page_path
+    else:
+        out.error(f"Unknown goal type: {goal_type}. Use 'event' or 'page_path'.")
+        raise typer.Exit(1)
+
+    result = c.client.post("/sites/goals", json=payload)
+    out.success(f"Goal created for {site_id}")
+    out.raw_json(result)
+
+
+@app.command()
+def delete(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain")],
+    goal_id: Annotated[int, typer.Argument(help="Goal ID to delete")],
+    force: Annotated[bool, typer.Option("--force", "-f", help="Skip confirmation")] = False,
+) -> None:
+    """Delete a goal from a site."""
+    c: AppContext = ctx.obj
+    out = c.output
+    if not force:
+        typer.confirm(f"Delete goal {goal_id} from site '{site_id}'?", abort=True)
+
+    c.client.delete(f"/sites/goals/{goal_id}", params={"site_id": site_id})
+    out.success(f"Goal {goal_id} deleted from {site_id}")

kctl_plausible-0.6.2/src/kctl_plausible/commands/sites.py

@@ -0,0 +1,72 @@
+"""Site management commands for Plausible Analytics.
+
+Supports listing, creating, deleting, and getting info on sites.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_plausible.core.callbacks import AppContext
+
+app = typer.Typer(help="Manage Plausible sites.")
+
+
+@app.command("list")
+def list_cmd(ctx: typer.Context) -> None:
+    """List all sites."""
+    c: AppContext = ctx.obj
+    out = c.output
+    result = c.client.get("/sites")
+    if isinstance(result, dict) and "sites" in result:
+        sites = result["sites"]
+    elif isinstance(result, list):
+        sites = result
+    else:
+        sites = [result] if result else []
+
+    out.table(sites, columns=["domain", "timezone"], title="Plausible Sites")
+
+
+@app.command()
+def create(
+    ctx: typer.Context,
+    domain: Annotated[str, typer.Argument(help="Domain to add (e.g. example.com)")],
+    timezone: Annotated[str, typer.Option("--timezone", "-tz", help="Timezone (e.g. Europe/London)")] = "Etc/UTC",
+) -> None:
+    """Create (provision) a new site."""
+    c: AppContext = ctx.obj
+    out = c.output
+    result = c.client.post("/sites", json={"domain": domain, "timezone": timezone})
+    out.success(f"Site created: {domain}")
+    out.raw_json(result)
+
+
+@app.command()
+def delete(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain to delete")],
+    force: Annotated[bool, typer.Option("--force", "-f", help="Skip confirmation")] = False,
+) -> None:
+    """Delete a site."""
+    c: AppContext = ctx.obj
+    out = c.output
+    if not force:
+        typer.confirm(f"Delete site '{site_id}'? This cannot be undone.", abort=True)
+
+    c.client.delete(f"/sites/{site_id}")
+    out.success(f"Site deleted: {site_id}")
+
+
+@app.command()
+def info(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain to get info for")],
+) -> None:
+    """Get site details."""
+    c: AppContext = ctx.obj
+    out = c.output
+    result = c.client.get(f"/sites/{site_id}")
+    out.raw_json(result)

kctl_plausible-0.6.2/src/kctl_plausible/commands/stats.py

@@ -0,0 +1,128 @@
+"""Stats commands for Plausible Analytics.
+
+Covers realtime visitors, aggregate stats, breakdowns, and timeseries.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_plausible.core.callbacks import AppContext
+
+app = typer.Typer(help="Query Plausible Analytics stats.")
+
+
+@app.command()
+def realtime(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain (e.g. example.com)")],
+) -> None:
+    """Get current realtime visitors count."""
+    c: AppContext = ctx.obj
+    out = c.output
+    result = c.client.get("/stats/realtime/visitors", params={"site_id": site_id})
+    out.kv("Site", site_id)
+    out.kv("Realtime Visitors", str(result))
+
+
+@app.command()
+def aggregate(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain (e.g. example.com)")],
+    period: Annotated[str, typer.Option("--period", "-p", help="Time period: day, 7d, 30d, month, 6mo, 12mo")] = "30d",
+    metrics: Annotated[
+        str,
+        typer.Option("--metrics", "-m", help="Comma-separated metrics: visitors,pageviews,bounce_rate,visit_duration"),
+    ] = "visitors,pageviews,bounce_rate,visit_duration",
+    date: Annotated[str | None, typer.Option("--date", help="Date (YYYY-MM-DD) for the period")] = None,
+    filters: Annotated[str | None, typer.Option("--filters", help="Plausible filter expression")] = None,
+) -> None:
+    """Get aggregate stats for a site."""
+    c: AppContext = ctx.obj
+    out = c.output
+    params: dict[str, str] = {"site_id": site_id, "period": period, "metrics": metrics}
+    if date:
+        params["date"] = date
+    if filters:
+        params["filters"] = filters
+
+    result = c.client.get("/stats/aggregate", params=params)
+    if isinstance(result, dict) and "results" in result:
+        results = result["results"]
+        rows = [{"metric": k, "value": v.get("value", v) if isinstance(v, dict) else v} for k, v in results.items()]
+        out.table(rows, columns=["metric", "value"], title=f"Aggregate Stats — {site_id} ({period})")
+    else:
+        out.raw_json(result)
+
+
+@app.command()
+def breakdown(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain (e.g. example.com)")],
+    prop: Annotated[
+        str, typer.Option("--property", help="Breakdown property: visit:source, visit:page, etc.")
+    ] = "visit:source",
+    period: Annotated[str, typer.Option("--period", "-p", help="Time period: day, 7d, 30d, month, 6mo, 12mo")] = "30d",
+    metrics: Annotated[str, typer.Option("--metrics", "-m", help="Comma-separated metrics")] = "visitors,pageviews",
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Max results to return")] = 10,
+    date: Annotated[str | None, typer.Option("--date", help="Date (YYYY-MM-DD) for the period")] = None,
+    filters: Annotated[str | None, typer.Option("--filters", help="Plausible filter expression")] = None,
+) -> None:
+    """Get breakdown stats by a property."""
+    c: AppContext = ctx.obj
+    out = c.output
+    params: dict[str, str | int] = {
+        "site_id": site_id,
+        "period": period,
+        "property": prop,
+        "metrics": metrics,
+        "limit": limit,
+    }
+    if date:
+        params["date"] = date
+    if filters:
+        params["filters"] = filters
+
+    result = c.client.get("/stats/breakdown", params=params)
+    if isinstance(result, dict) and "results" in result:
+        rows = result["results"]
+        # Determine columns from first row
+        if rows:
+            columns = list(rows[0].keys())
+        else:
+            columns = [prop.split(":")[-1], "visitors"]
+        out.table(rows, columns=columns, title=f"Breakdown by {prop} — {site_id} ({period})")
+    else:
+        out.raw_json(result)
+
+
+@app.command()
+def timeseries(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain (e.g. example.com)")],
+    period: Annotated[str, typer.Option("--period", "-p", help="Time period: day, 7d, 30d, month, 6mo, 12mo")] = "30d",
+    metrics: Annotated[str, typer.Option("--metrics", "-m", help="Comma-separated metrics")] = "visitors,pageviews",
+    date: Annotated[str | None, typer.Option("--date", help="Date (YYYY-MM-DD) for the period")] = None,
+    filters: Annotated[str | None, typer.Option("--filters", help="Plausible filter expression")] = None,
+) -> None:
+    """Get timeseries stats for a site."""
+    c: AppContext = ctx.obj
+    out = c.output
+    params: dict[str, str] = {"site_id": site_id, "period": period, "metrics": metrics}
+    if date:
+        params["date"] = date
+    if filters:
+        params["filters"] = filters
+
+    result = c.client.get("/stats/timeseries", params=params)
+    if isinstance(result, dict) and "results" in result:
+        rows = result["results"]
+        if rows:
+            columns = list(rows[0].keys())
+        else:
+            columns = ["date", "visitors"]
+        out.table(rows, columns=columns, title=f"Timeseries — {site_id} ({period})")
+    else:
+        out.raw_json(result)

kctl_plausible-0.6.2/src/kctl_plausible/core/callbacks.py

@@ -0,0 +1,39 @@
+"""Typer global callback and shared context for kctl-plausible.
+
+Subclasses AppContextBase from kctl-lib with Plausible Analytics-specific fields.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from kctl_lib.callbacks import AppContextBase
+
+from kctl_plausible.core.client import PlausibleClient
+from kctl_plausible.core.config import resolve_connection
+
+
+@dataclass
+class AppContext(AppContextBase):
+    """Plausible Analytics-specific application context."""
+
+    debug: bool = False
+    url_override: str | None = None
+    api_key_override: str | None = None
+    _client: PlausibleClient | None = field(default=None, repr=False, init=False)
+
+    @property
+    def client(self) -> PlausibleClient:
+        if self._client is None:
+            url, api_key = resolve_connection(
+                profile_name=self.profile,
+                url_override=self.url_override,
+                api_key_override=self.api_key_override,
+            )
+            self._client = PlausibleClient(base_url=url, api_key=api_key)
+        return self._client
+
+    def close(self) -> None:
+        """Close underlying HTTP client."""
+        if self._client is not None:
+            self._client.close()

kctl_plausible-0.6.2/src/kctl_plausible/core/client.py

@@ -0,0 +1,61 @@
+"""Plausible Analytics API client, subclassing kctl-lib's APIClient.
+
+Provides Plausible-specific auth (Authorization: Bearer <key>),
+retry support, and health check functionality.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from kctl_lib.api_client import APIClient
+from kctl_lib.exceptions import ConfigError
+
+
+class PlausibleClient(APIClient):
+    """Synchronous httpx client for Plausible Analytics API with retry support."""
+
+    AUTH_HEADER = "Authorization"
+    AUTH_PREFIX = "Bearer "
+    API_PREFIX = "/api/v1"
+
+    def __init__(
+        self,
+        base_url: str = "",
+        api_key: str = "",
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        retry_base_delay: float = 2.0,
+        retry_max_delay: float = 60.0,
+        **kwargs: Any,
+    ):
+        if not base_url:
+            raise ConfigError("No URL configured. Run: kctl-plausible config init")
+
+        super().__init__(
+            base_url=base_url,
+            credential=api_key or "unset",
+            timeout=timeout,
+            retry_enabled=True,
+            max_retries=max_retries,
+            retry_base_delay=retry_base_delay,
+            retry_max_delay=retry_max_delay,
+            **kwargs,
+        )
+
+    @property
+    def root_url(self) -> str:
+        """Public accessor for the root URL (without /api/v1)."""
+        return self._base_url.rsplit("/api/v1", 1)[0]
+
+    def check_health(self) -> int:
+        """Check health by hitting /api/health (not under /v1), returns HTTP status code."""
+        try:
+            r = httpx.get(
+                f"{self.root_url}/api/health",
+                timeout=5,
+            )
+            return r.status_code
+        except httpx.HTTPError:
+            return 0

kctl_plausible-0.6.2/src/kctl_plausible/core/config.py

@@ -0,0 +1,134 @@
+"""Profile management and configuration resolution for kctl-plausible.
+
+Delegates to kctl-lib's config framework with Plausible Analytics-specific settings.
+"""
+
+from __future__ import annotations
+
+import os
+
+from kctl_lib.config import (
+    CONFIG_DIR,
+    CONFIG_FILE,
+    ConfigFile,
+    expand_env,
+    get_all_services_in_profile,
+    get_default_profile,
+    get_profile_names,
+    is_service_scoped,
+    load_config,
+    load_raw_config,
+    remove_profile,
+    save_raw_config,
+    set_default_profile,
+)
+from kctl_lib.config import get_service_config as _get_service_config
+from kctl_lib.config import (
+    resolve_active_profile_name as _resolve_active_profile_name,
+)
+from kctl_lib.config import set_service_config as _set_service_config
+from pydantic import BaseModel
+
+# This CLI's service key within a profile
+SERVICE_KEY = "plausible"
+
+# Environment variable prefix for this CLI
+ENV_PREFIX = "KCTL_PLAUSIBLE"
+
+__all__ = [
+    "CONFIG_DIR",
+    "CONFIG_FILE",
+    "ConfigFile",
+    "SERVICE_KEY",
+    "ServiceConfig",
+    "get_all_services_in_profile",
+    "get_default_profile",
+    "get_profile_names",
+    "get_service_config",
+    "is_service_scoped",
+    "load_config",
+    "load_raw_config",
+    "remove_profile",
+    "resolve_active_profile_name",
+    "resolve_connection",
+    "save_raw_config",
+    "set_default_profile",
+    "set_service_config",
+]
+
+
+class ServiceConfig(BaseModel):
+    """Plausible Analytics service-specific config within a profile."""
+
+    url: str = ""
+    api_key: str = ""
+
+
+def get_service_config(profile_name: str) -> ServiceConfig:
+    """Get Plausible service config from a profile."""
+    raw = _get_service_config(
+        profile_name,
+        SERVICE_KEY,
+        valid_fields=list(ServiceConfig.model_fields.keys()),
+    )
+    if not raw:
+        return ServiceConfig()
+    return ServiceConfig(**raw)
+
+
+def set_service_config(profile_name: str, svc_config: ServiceConfig) -> None:
+    """Write Plausible service config into a profile."""
+    svc_data = svc_config.model_dump(exclude_defaults=False)
+    # Remove empty values
+    cleaned = {k: v for k, v in svc_data.items() if v}
+    _set_service_config(profile_name, SERVICE_KEY, cleaned)
+
+
+def _expand_key(api_key: str) -> str:
+    """Expand ${ENV_VAR} references in API key values."""
+    return expand_env(api_key)
+
+
+def resolve_active_profile_name(
+    profile_name: str | None = None,
+) -> str:
+    """Resolve the active profile name from all sources."""
+    return _resolve_active_profile_name(profile_name, ENV_PREFIX)
+
+
+def resolve_connection(
+    profile_name: str | None = None,
+    url_override: str | None = None,
+    api_key_override: str | None = None,
+) -> tuple[str, str]:
+    """Resolve API URL and API key from all sources.
+
+    Priority:
+    1. CLI flags (url_override, api_key_override)
+    2. KCTL_PLAUSIBLE_URL / KCTL_PLAUSIBLE_API_KEY env vars
+    3. Profile's plausible service config
+    """
+    url = ""
+    api_key = ""
+
+    # 3. Config file profile (service-scoped)
+    pname = resolve_active_profile_name(profile_name)
+    svc = get_service_config(pname)
+    if svc.url:
+        url = svc.url
+    if svc.api_key:
+        api_key = svc.api_key
+
+    # 2. KCTL env vars
+    if env_url := os.environ.get("KCTL_PLAUSIBLE_URL"):
+        url = env_url
+    if env_key := os.environ.get("KCTL_PLAUSIBLE_API_KEY"):
+        api_key = env_key
+
+    # 1. CLI flags
+    if url_override:
+        url = url_override
+    if api_key_override:
+        api_key = api_key_override
+
+    return url, api_key

kctl_plausible-0.6.2/tests/conftest.py

@@ -0,0 +1,83 @@
+"""Shared test fixtures for kctl-plausible tests."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+from typer.testing import CliRunner
+
+from kctl_lib.output import Output
+
+from kctl_plausible.core.callbacks import AppContext
+from kctl_plausible.core.client import PlausibleClient
+
+
+@pytest.fixture
+def runner() -> CliRunner:
+    """Typer CLI test runner."""
+    return CliRunner()
+
+
+@pytest.fixture
+def mock_client() -> MagicMock:
+    """Mocked PlausibleClient with predictable responses."""
+    client = MagicMock(spec=PlausibleClient)
+    client._root_url = "https://plausible.test.io"
+    client._base_url = "https://plausible.test.io/api/v1"
+    client._credential = "test-api-key-12345"
+    client.AUTH_HEADER = "Authorization"
+    client.AUTH_PREFIX = "Bearer "
+    client.check_health.return_value = 200
+    client.get.return_value = {"results": {}}
+    client.post.return_value = {}
+    client.delete.return_value = {}
+    return client
+
+
+@pytest.fixture
+def app_context(mock_client: MagicMock) -> AppContext:
+    """AppContext with mock client injected."""
+    ctx = AppContext(json_mode=True)
+    ctx._client = mock_client
+    return ctx
+
+
+@pytest.fixture
+def mock_config(tmp_path: Path):
+    """Redirect kctl-lib config to a temp directory."""
+    config_dir = tmp_path / "kodemeio"
+    config_dir.mkdir(parents=True)
+    config_file = config_dir / "config.yaml"
+    config_file.write_text("default_profile: default\nprofiles: {}\n")
+    with patch("kctl_lib.config.CONFIG_FILE", config_file):
+        yield config_file
+
+
+@pytest.fixture
+def mock_output() -> Output:
+    """Output instance for testing."""
+    return Output(json_mode=False, quiet=True, format="pretty")
+
+
+@pytest.fixture
+def mock_context(mock_client: MagicMock, mock_output: Output) -> AppContext:
+    """AppContext with mocked client."""
+    ctx = AppContext(quiet=True)
+    ctx._client = mock_client
+    ctx._output = mock_output
+    return ctx
+
+
+@pytest.fixture
+def sample_stats() -> dict:
+    """Sample Plausible aggregate stats response."""
+    return {
+        "results": {
+            "visitors": {"value": 1234},
+            "pageviews": {"value": 5678},
+            "bounce_rate": {"value": 42.5},
+            "visit_duration": {"value": 185},
+        }
+    }

kctl_plausible-0.6.2/tests/test_cli.py

@@ -0,0 +1,30 @@
+"""Basic CLI tests for kctl-plausible."""
+
+from __future__ import annotations
+
+from typer.testing import CliRunner
+
+from kctl_plausible.cli import app
+
+runner = CliRunner()
+
+
+def test_app_exists():
+    assert app is not None
+
+
+def test_help():
+    result = runner.invoke(app, ["--help"])
+    assert result.exit_code == 0
+    assert "Usage" in result.output
+
+
+def test_version():
+    result = runner.invoke(app, ["--version"])
+    assert result.exit_code == 0
+
+
+def test_config_help():
+    result = runner.invoke(app, ["config", "--help"])
+    assert result.exit_code == 0
+    assert "Usage" in result.output