lgtm-cli 0.1.0__tar.gz

lgtm_cli-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.3
+Name: lgtm-cli
+Version: 0.1.0
+Summary: Lightweight CLI for querying Loki, Prometheus/Mimir, and Tempo
+Author: Aiman Ismail
+Author-email: Aiman Ismail <aiman@primeintellect.ai>
+Requires-Dist: click>=8.3.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# LGTM CLI
+
+Lightweight CLI for querying Loki, Prometheus/Mimir, and Tempo.
+
+## Installation
+
+**Requires Python 3.12+**
+
+```bash
+# Install globally
+uv tool install git+https://github.com/pokgak/lgtm-cli
+
+# Or run directly without installing
+uvx --from git+https://github.com/pokgak/lgtm-cli lgtm --help
+```
+
+## Usage
+
+```bash
+# List configured instances
+lgtm instances
+
+# Query Loki logs (defaults: last 15 min, limit 50)
+lgtm loki query '{app="myapp"} |= "error"'
+
+# Query Prometheus metrics
+lgtm prom query 'rate(http_requests_total[5m])'
+
+# Search Tempo traces (defaults: last 15 min, limit 20)
+lgtm tempo search -q '{resource.service.name="api"}'
+
+# Use specific instance
+lgtm -i production loki labels
+```
+
+## Configuration
+
+Create config at `~/.config/lgtm/config.yaml`:
+
+```yaml
+version: "1"
+default_instance: "local"
+
+instances:
+  local:
+    loki:
+      url: "http://localhost:3100"
+    prometheus:
+      url: "http://localhost:9090"
+    tempo:
+      url: "http://localhost:3200"
+```
+
+### Authentication
+
+| Config Fields | Auth Type | Description |
+|---------------|-----------|-------------|
+| `token` only | Bearer | `Authorization: Bearer <token>` header |
+| `username` + `token` | Basic | HTTP Basic auth |
+| `headers` | Custom | Custom headers (e.g., `X-Scope-OrgID` for multi-tenant) |
+
+Example with authentication:
+
+```yaml
+version: "1"
+default_instance: "production"
+
+instances:
+  production:
+    loki:
+      url: "https://loki.example.com"
+      token: "${LOKI_TOKEN}"  # Bearer auth
+    prometheus:
+      url: "https://mimir.example.com"
+      username: "${MIMIR_USER}"  # Basic auth
+      token: "${MIMIR_TOKEN}"
+    tempo:
+      url: "https://tempo.example.com"
+      token: "${TEMPO_TOKEN}"
+      headers:
+        X-Scope-OrgID: "my-tenant"
+```
+
+Environment variables (`${VAR_NAME}`) are expanded at runtime.
+
+## Built-in Best Practices
+
+- **Default time range:** 15 minutes (not hours/days)
+- **Default limits:** 50 for logs, 20 for traces
+- **Discovery commands:** Explore labels/metrics/tags first
+
+### Recommended Workflow
+
+1. **Discover** what's available:
+   ```bash
+   lgtm loki labels
+   lgtm loki label-values app
+   ```
+
+2. **Aggregate** to get overview:
+   ```bash
+   lgtm loki instant 'sum by (app) (count_over_time({namespace="prod"} |= "error" [15m]))'
+   ```
+
+3. **Drill down** to specifics:
+   ```bash
+   lgtm loki query '{namespace="prod", app="checkout"} |= "error"' --limit 20
+   ```
+
+## Commands
+
+### Loki
+
+```bash
+lgtm loki labels                  # List available labels
+lgtm loki label-values <label>    # List values for a label
+lgtm loki query <logql>           # Query logs
+lgtm loki instant <logql>         # Instant query (for aggregations)
+lgtm loki series <selector>...    # List series
+```
+
+### Prometheus
+
+```bash
+lgtm prom labels                  # List available labels
+lgtm prom label-values <label>    # List values for a label
+lgtm prom query <promql>          # Instant query
+lgtm prom range <promql>          # Range query
+lgtm prom series <selector>...    # List series
+lgtm prom metadata                # Get metric metadata
+```
+
+### Tempo
+
+```bash
+lgtm tempo tags                   # List available tags
+lgtm tempo tag-values <tag>       # List values for a tag
+lgtm tempo search                 # Search traces
+lgtm tempo trace <trace_id>       # Get trace by ID
+```
+
+## Compatibility
+
+Config format is compatible with [lgtm-mcp](https://github.com/pokgak/lgtm-mcp) for easy migration.

lgtm_cli-0.1.0/README.md

@@ -0,0 +1,144 @@
+# LGTM CLI
+
+Lightweight CLI for querying Loki, Prometheus/Mimir, and Tempo.
+
+## Installation
+
+**Requires Python 3.12+**
+
+```bash
+# Install globally
+uv tool install git+https://github.com/pokgak/lgtm-cli
+
+# Or run directly without installing
+uvx --from git+https://github.com/pokgak/lgtm-cli lgtm --help
+```
+
+## Usage
+
+```bash
+# List configured instances
+lgtm instances
+
+# Query Loki logs (defaults: last 15 min, limit 50)
+lgtm loki query '{app="myapp"} |= "error"'
+
+# Query Prometheus metrics
+lgtm prom query 'rate(http_requests_total[5m])'
+
+# Search Tempo traces (defaults: last 15 min, limit 20)
+lgtm tempo search -q '{resource.service.name="api"}'
+
+# Use specific instance
+lgtm -i production loki labels
+```
+
+## Configuration
+
+Create config at `~/.config/lgtm/config.yaml`:
+
+```yaml
+version: "1"
+default_instance: "local"
+
+instances:
+  local:
+    loki:
+      url: "http://localhost:3100"
+    prometheus:
+      url: "http://localhost:9090"
+    tempo:
+      url: "http://localhost:3200"
+```
+
+### Authentication
+
+| Config Fields | Auth Type | Description |
+|---------------|-----------|-------------|
+| `token` only | Bearer | `Authorization: Bearer <token>` header |
+| `username` + `token` | Basic | HTTP Basic auth |
+| `headers` | Custom | Custom headers (e.g., `X-Scope-OrgID` for multi-tenant) |
+
+Example with authentication:
+
+```yaml
+version: "1"
+default_instance: "production"
+
+instances:
+  production:
+    loki:
+      url: "https://loki.example.com"
+      token: "${LOKI_TOKEN}"  # Bearer auth
+    prometheus:
+      url: "https://mimir.example.com"
+      username: "${MIMIR_USER}"  # Basic auth
+      token: "${MIMIR_TOKEN}"
+    tempo:
+      url: "https://tempo.example.com"
+      token: "${TEMPO_TOKEN}"
+      headers:
+        X-Scope-OrgID: "my-tenant"
+```
+
+Environment variables (`${VAR_NAME}`) are expanded at runtime.
+
+## Built-in Best Practices
+
+- **Default time range:** 15 minutes (not hours/days)
+- **Default limits:** 50 for logs, 20 for traces
+- **Discovery commands:** Explore labels/metrics/tags first
+
+### Recommended Workflow
+
+1. **Discover** what's available:
+   ```bash
+   lgtm loki labels
+   lgtm loki label-values app
+   ```
+
+2. **Aggregate** to get overview:
+   ```bash
+   lgtm loki instant 'sum by (app) (count_over_time({namespace="prod"} |= "error" [15m]))'
+   ```
+
+3. **Drill down** to specifics:
+   ```bash
+   lgtm loki query '{namespace="prod", app="checkout"} |= "error"' --limit 20
+   ```
+
+## Commands
+
+### Loki
+
+```bash
+lgtm loki labels                  # List available labels
+lgtm loki label-values <label>    # List values for a label
+lgtm loki query <logql>           # Query logs
+lgtm loki instant <logql>         # Instant query (for aggregations)
+lgtm loki series <selector>...    # List series
+```
+
+### Prometheus
+
+```bash
+lgtm prom labels                  # List available labels
+lgtm prom label-values <label>    # List values for a label
+lgtm prom query <promql>          # Instant query
+lgtm prom range <promql>          # Range query
+lgtm prom series <selector>...    # List series
+lgtm prom metadata                # Get metric metadata
+```
+
+### Tempo
+
+```bash
+lgtm tempo tags                   # List available tags
+lgtm tempo tag-values <tag>       # List values for a tag
+lgtm tempo search                 # Search traces
+lgtm tempo trace <trace_id>       # Get trace by ID
+```
+
+## Compatibility
+
+Config format is compatible with [lgtm-mcp](https://github.com/pokgak/lgtm-mcp) for easy migration.

lgtm_cli-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "lgtm-cli"
+version = "0.1.0"
+description = "Lightweight CLI for querying Loki, Prometheus/Mimir, and Tempo"
+readme = "README.md"
+authors = [
+    { name = "Aiman Ismail", email = "aiman@primeintellect.ai" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "click>=8.3.1",
+    "httpx>=0.28.1",
+    "pyyaml>=6.0.3",
+]
+
+[project.scripts]
+lgtm = "lgtm_cli.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.8.22,<0.9.0"]
+build-backend = "uv_build"

lgtm_cli-0.1.0/src/lgtm_cli/__init__.py

@@ -0,0 +1,13 @@
+from .config import load_config, Config, InstanceConfig, ServiceConfig, DEFAULT_CONFIG_PATH
+from .client import LokiClient, PrometheusClient, TempoClient
+
+__all__ = [
+    "load_config",
+    "Config",
+    "InstanceConfig",
+    "ServiceConfig",
+    "DEFAULT_CONFIG_PATH",
+    "LokiClient",
+    "PrometheusClient",
+    "TempoClient",
+]

lgtm_cli-0.1.0/src/lgtm_cli/cli.py

@@ -0,0 +1,668 @@
+import json
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import click
+
+from .config import load_config, DEFAULT_CONFIG_PATH
+from .client import LokiClient, PrometheusClient, TempoClient, AlertingClient
+
+
+# Best practice defaults
+DEFAULT_TIME_RANGE_MINUTES = 15  # Start with narrow time range
+DEFAULT_LOKI_LIMIT = 50  # Reasonable limit for logs
+DEFAULT_TEMPO_LIMIT = 20  # Reasonable limit for traces
+DEFAULT_PROM_STEP = "60s"  # 1 minute resolution
+
+
+def get_default_times(minutes: int = DEFAULT_TIME_RANGE_MINUTES) -> tuple[str, str]:
+    """Get default start/end times (RFC3339) for the last N minutes."""
+    now = datetime.now(timezone.utc)
+    start = now - timedelta(minutes=minutes)
+    return start.strftime("%Y-%m-%dT%H:%M:%SZ"), now.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def get_default_times_unix(minutes: int = DEFAULT_TIME_RANGE_MINUTES) -> tuple[str, str]:
+    """Get default start/end times (Unix seconds) for the last N minutes."""
+    now = datetime.now(timezone.utc)
+    start = now - timedelta(minutes=minutes)
+    return str(int(start.timestamp())), str(int(now.timestamp()))
+
+
+def output_json(data: dict):
+    """Output JSON data, pretty-printed."""
+    click.echo(json.dumps(data, indent=2))
+
+
+def output_error(msg: str):
+    """Output error message to stderr."""
+    click.echo(f"Error: {msg}", err=True)
+
+
+@click.group()
+@click.option("--config", "-c", type=click.Path(exists=True, path_type=Path), help="Config file path")
+@click.option("--instance", "-i", help="Instance name from config")
+@click.pass_context
+def main(ctx, config: Path | None, instance: str | None):
+    """LGTM CLI - Query Loki, Prometheus, and Tempo.
+
+    Best practices are built-in:
+    - Default time range: 15 minutes (use --start/--end to override)
+    - Default limits: 50 for logs, 20 for traces
+    - Always filter by labels when possible
+    """
+    ctx.ensure_object(dict)
+    try:
+        ctx.obj["config"] = load_config(config)
+        ctx.obj["instance_name"] = instance
+    except FileNotFoundError as e:
+        output_error(str(e))
+        output_error(f"Create a config file at {DEFAULT_CONFIG_PATH}")
+        sys.exit(1)
+
+
+# === LOKI COMMANDS ===
+
+@main.group()
+@click.pass_context
+def loki(ctx):
+    """Query Loki logs."""
+    instance = ctx.obj["config"].get_instance(ctx.obj["instance_name"])
+    if not instance.loki:
+        output_error(f"Loki not configured for instance '{instance.name}'")
+        sys.exit(1)
+    ctx.obj["client"] = LokiClient(instance.loki)
+
+
+@loki.command()
+@click.argument("query")
+@click.option("--start", "-s", help="Start time (RFC3339). Default: 15 minutes ago")
+@click.option("--end", "-e", help="End time (RFC3339). Default: now")
+@click.option("--limit", "-l", default=DEFAULT_LOKI_LIMIT, help=f"Max entries (default: {DEFAULT_LOKI_LIMIT})")
+@click.option("--direction", "-d", type=click.Choice(["backward", "forward"]), default="backward")
+@click.pass_context
+def query(ctx, query: str, start: str | None, end: str | None, limit: int, direction: str):
+    """Query logs with LogQL.
+
+    Examples:
+
+      lgtm loki query '{app="myapp"}'
+
+      lgtm loki query '{app="myapp"} |= "error"' --limit 100
+
+      lgtm loki query '{app="myapp"}' --start 2024-01-15T10:00:00Z --end 2024-01-15T11:00:00Z
+    """
+    default_start, default_end = get_default_times()
+    try:
+        result = ctx.obj["client"].query(
+            query=query,
+            start=start or default_start,
+            end=end or default_end,
+            limit=limit,
+            direction=direction,
+        )
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@loki.command()
+@click.argument("query")
+@click.option("--time", "-t", help="Evaluation time (RFC3339). Default: now")
+@click.pass_context
+def instant(ctx, query: str, time: str | None):
+    """Run instant query (for metric queries like count_over_time).
+
+    Examples:
+
+      lgtm loki instant 'count_over_time({app="myapp"}[5m])'
+
+      lgtm loki instant 'sum by (level) (count_over_time({app="myapp"} | json [5m]))'
+    """
+    try:
+        result = ctx.obj["client"].query_instant(query, time)
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@loki.command()
+@click.option("--start", "-s", help="Start time filter")
+@click.option("--end", "-e", help="End time filter")
+@click.pass_context
+def labels(ctx, start: str | None, end: str | None):
+    """List available labels.
+
+    Use this first to discover what labels are available before querying.
+    """
+    try:
+        result = ctx.obj["client"].labels(start, end)
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@loki.command("label-values")
+@click.argument("label")
+@click.option("--start", "-s", help="Start time filter")
+@click.option("--end", "-e", help="End time filter")
+@click.pass_context
+def label_values(ctx, label: str, start: str | None, end: str | None):
+    """List values for a label.
+
+    Examples:
+
+      lgtm loki label-values app
+
+      lgtm loki label-values namespace
+    """
+    try:
+        result = ctx.obj["client"].label_values(label, start, end)
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@loki.command()
+@click.argument("match", nargs=-1, required=True)
+@click.option("--start", "-s", help="Start time filter")
+@click.option("--end", "-e", help="End time filter")
+@click.pass_context
+def series(ctx, match: tuple[str, ...], start: str | None, end: str | None):
+    """List series matching selectors.
+
+    Examples:
+
+      lgtm loki series '{app="myapp"}'
+
+      lgtm loki series '{namespace="prod"}' '{namespace="staging"}'
+    """
+    try:
+        result = ctx.obj["client"].series(list(match), start, end)
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+# === PROMETHEUS COMMANDS ===
+
+@main.group()
+@click.pass_context
+def prom(ctx):
+    """Query Prometheus/Mimir metrics."""
+    instance = ctx.obj["config"].get_instance(ctx.obj["instance_name"])
+    if not instance.prometheus:
+        output_error(f"Prometheus not configured for instance '{instance.name}'")
+        sys.exit(1)
+    ctx.obj["client"] = PrometheusClient(instance.prometheus)
+
+
+@prom.command()
+@click.argument("query")
+@click.option("--time", "-t", help="Evaluation time (RFC3339). Default: now")
+@click.pass_context
+def query(ctx, query: str, time: str | None):
+    """Run instant query.
+
+    Examples:
+
+      lgtm prom query 'up{job="prometheus"}'
+
+      lgtm prom query 'rate(http_requests_total[5m])'
+    """
+    try:
+        result = ctx.obj["client"].query(query, time)
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@prom.command()
+@click.argument("query")
+@click.option("--start", "-s", help="Start time (RFC3339). Default: 15 minutes ago")
+@click.option("--end", "-e", help="End time (RFC3339). Default: now")
+@click.option("--step", default=DEFAULT_PROM_STEP, help=f"Resolution step (default: {DEFAULT_PROM_STEP})")
+@click.pass_context
+def range(ctx, query: str, start: str | None, end: str | None, step: str):
+    """Run range query.
+
+    Examples:
+
+      lgtm prom range 'rate(http_requests_total[5m])'
+
+      lgtm prom range 'up' --step 5m --start 2024-01-15T10:00:00Z
+    """
+    default_start, default_end = get_default_times()
+    try:
+        result = ctx.obj["client"].query_range(
+            query=query,
+            start=start or default_start,
+            end=end or default_end,
+            step=step,
+        )
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@prom.command()
+@click.option("--start", "-s", help="Start time filter")
+@click.option("--end", "-e", help="End time filter")
+@click.pass_context
+def labels(ctx, start: str | None, end: str | None):
+    """List available labels.
+
+    Use this first to discover what labels are available.
+    """
+    try:
+        result = ctx.obj["client"].labels(start, end)
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@prom.command("label-values")
+@click.argument("label")
+@click.option("--start", "-s", help="Start time filter")
+@click.option("--end", "-e", help="End time filter")
+@click.pass_context
+def prom_label_values(ctx, label: str, start: str | None, end: str | None):
+    """List values for a label.
+
+    Examples:
+
+      lgtm prom label-values job
+
+      lgtm prom label-values __name__  # List all metric names
+    """
+    try:
+        result = ctx.obj["client"].label_values(label, start, end)
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@prom.command()
+@click.argument("match", nargs=-1, required=True)
+@click.option("--start", "-s", help="Start time filter")
+@click.option("--end", "-e", help="End time filter")
+@click.pass_context
+def series(ctx, match: tuple[str, ...], start: str | None, end: str | None):
+    """List series matching selectors.
+
+    Examples:
+
+      lgtm prom series 'up'
+
+      lgtm prom series 'http_requests_total{job="api"}'
+    """
+    try:
+        result = ctx.obj["client"].series(list(match), start, end)
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@prom.command()
+@click.option("--metric", "-m", help="Filter by metric name")
+@click.pass_context
+def metadata(ctx, metric: str | None):
+    """Get metric metadata.
+
+    Examples:
+
+      lgtm prom metadata
+
+      lgtm prom metadata --metric http_requests_total
+    """
+    try:
+        result = ctx.obj["client"].metadata(metric)
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+# === TEMPO COMMANDS ===
+
+@main.group()
+@click.pass_context
+def tempo(ctx):
+    """Query Tempo traces."""
+    instance = ctx.obj["config"].get_instance(ctx.obj["instance_name"])
+    if not instance.tempo:
+        output_error(f"Tempo not configured for instance '{instance.name}'")
+        sys.exit(1)
+    ctx.obj["client"] = TempoClient(instance.tempo)
+
+
+@tempo.command()
+@click.argument("trace_id")
+@click.pass_context
+def trace(ctx, trace_id: str):
+    """Get trace by ID.
+
+    Use this when you have a specific trace ID to investigate.
+
+    Examples:
+
+      lgtm tempo trace abc123def456
+    """
+    try:
+        result = ctx.obj["client"].trace(trace_id)
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@tempo.command()
+@click.option("--query", "-q", help="TraceQL query")
+@click.option("--start", "-s", help="Start time (Unix seconds). Default: 15 minutes ago")
+@click.option("--end", "-e", help="End time (Unix seconds). Default: now")
+@click.option("--min-duration", help="Minimum duration (e.g., 100ms, 1s)")
+@click.option("--max-duration", help="Maximum duration")
+@click.option("--limit", "-l", default=DEFAULT_TEMPO_LIMIT, help=f"Max traces (default: {DEFAULT_TEMPO_LIMIT})")
+@click.pass_context
+def search(ctx, query: str | None, start: str | None, end: str | None,
+           min_duration: str | None, max_duration: str | None, limit: int):
+    """Search traces with TraceQL.
+
+    Examples:
+
+      lgtm tempo search -q '{resource.service.name="api"}'
+
+      lgtm tempo search -q '{status=error}' --min-duration 1s
+
+      lgtm tempo search --min-duration 500ms --limit 50
+    """
+    default_start, default_end = get_default_times_unix()
+    try:
+        result = ctx.obj["client"].search(
+            query=query,
+            start=start or default_start,
+            end=end or default_end,
+            min_duration=min_duration,
+            max_duration=max_duration,
+            limit=limit,
+        )
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@tempo.command()
+@click.pass_context
+def tags(ctx):
+    """List available tags.
+
+    Use this first to discover what tags/attributes are available.
+    """
+    try:
+        result = ctx.obj["client"].tags()
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@tempo.command("tag-values")
+@click.argument("tag")
+@click.pass_context
+def tag_values(ctx, tag: str):
+    """List values for a tag.
+
+    Examples:
+
+      lgtm tempo tag-values service.name
+
+      lgtm tempo tag-values http.status_code
+    """
+    try:
+        result = ctx.obj["client"].tag_values(tag)
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+# === ALERTS COMMANDS ===
+
+DEFAULT_SILENCE_DURATION_HOURS = 2
+
+
+def parse_duration(duration: str) -> timedelta:
+    """Parse duration string like '2h', '30m', '1d' to timedelta."""
+    import re
+    match = re.match(r'^(\d+)([smhd])$', duration.lower())
+    if not match:
+        raise click.BadParameter(f"Invalid duration format: {duration}. Use format like '2h', '30m', '1d'")
+    value = int(match.group(1))
+    unit = match.group(2)
+    if unit == 's':
+        return timedelta(seconds=value)
+    elif unit == 'm':
+        return timedelta(minutes=value)
+    elif unit == 'h':
+        return timedelta(hours=value)
+    elif unit == 'd':
+        return timedelta(days=value)
+    raise click.BadParameter(f"Unknown time unit: {unit}")
+
+
+def parse_matcher(matcher: str) -> dict:
+    """Parse matcher string like 'alertname=HighCPU' or 'severity=~warning|critical'."""
+    import re
+    match = re.match(r'^([^=!~]+)(=~|!~|!=|=)(.*)$', matcher)
+    if not match:
+        raise click.BadParameter(f"Invalid matcher format: {matcher}. Use format like 'label=value' or 'label=~regex'")
+    name = match.group(1)
+    op = match.group(2)
+    value = match.group(3)
+    return {
+        "name": name,
+        "value": value,
+        "isRegex": op in ("=~", "!~"),
+        "isEqual": op in ("=", "=~"),
+    }
+
+
+@main.group()
+@click.pass_context
+def alerts(ctx):
+    """Query Grafana Alerting/Alertmanager."""
+    instance = ctx.obj["config"].get_instance(ctx.obj["instance_name"])
+    if not instance.alerting:
+        output_error(f"Alerting not configured for instance '{instance.name}'")
+        sys.exit(1)
+    ctx.obj["client"] = AlertingClient(instance.alerting)
+
+
+@alerts.command("list")
+@click.option("--filter", "-f", "filters", multiple=True, help="Filter alerts by label (e.g., 'alertname=HighCPU')")
+@click.option("--receiver", "-r", help="Filter by receiver")
+@click.option("--silenced/--no-silenced", default=True, help="Include silenced alerts")
+@click.option("--inhibited/--no-inhibited", default=True, help="Include inhibited alerts")
+@click.option("--active/--no-active", default=True, help="Include active alerts")
+@click.pass_context
+def alerts_list(ctx, filters: tuple[str, ...], receiver: str | None, silenced: bool, inhibited: bool, active: bool):
+    """List firing alerts.
+
+    Examples:
+
+      lgtm alerts list
+
+      lgtm alerts list --filter 'alertname=HighCPU'
+
+      lgtm alerts list --no-silenced --active
+    """
+    try:
+        result = ctx.obj["client"].list_alerts(
+            filter=list(filters) if filters else None,
+            receiver=receiver,
+            silenced=silenced,
+            inhibited=inhibited,
+            active=active,
+        )
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@alerts.command("groups")
+@click.option("--filter", "-f", "filters", multiple=True, help="Filter alerts by label")
+@click.option("--receiver", "-r", help="Filter by receiver")
+@click.pass_context
+def alerts_groups(ctx, filters: tuple[str, ...], receiver: str | None):
+    """List alerts grouped by receiver/labels.
+
+    Examples:
+
+      lgtm alerts groups
+
+      lgtm alerts groups --filter 'severity=critical'
+    """
+    try:
+        result = ctx.obj["client"].list_alert_groups(
+            filter=list(filters) if filters else None,
+            receiver=receiver,
+        )
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@alerts.command("silences")
+@click.option("--filter", "-f", "filters", multiple=True, help="Filter silences by label")
+@click.pass_context
+def alerts_silences(ctx, filters: tuple[str, ...]):
+    """List all silences.
+
+    Examples:
+
+      lgtm alerts silences
+
+      lgtm alerts silences --filter 'alertname=HighCPU'
+    """
+    try:
+        result = ctx.obj["client"].list_silences(
+            filter=list(filters) if filters else None,
+        )
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@alerts.command("silence-get")
+@click.argument("silence_id")
+@click.pass_context
+def alerts_silence_get(ctx, silence_id: str):
+    """Get a specific silence by ID.
+
+    Examples:
+
+      lgtm alerts silence-get abc123-def456
+    """
+    try:
+        result = ctx.obj["client"].get_silence(silence_id)
+        output_json(result)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@alerts.command("silence-create")
+@click.option("--matcher", "-m", "matchers", multiple=True, required=True,
+              help="Matcher in format 'label=value' or 'label=~regex'. Can be specified multiple times.")
+@click.option("--duration", "-d", default="2h", help="Silence duration (e.g., '2h', '30m', '1d'). Default: 2h")
+@click.option("--comment", "-c", required=True, help="Comment explaining the silence")
+@click.option("--created-by", required=True, help="Creator identifier (e.g., email)")
+@click.pass_context
+def alerts_silence_create(ctx, matchers: tuple[str, ...], duration: str, comment: str, created_by: str):
+    """Create a new silence.
+
+    Examples:
+
+      lgtm alerts silence-create --matcher 'alertname=HighCPU' --duration 2h --comment "Maintenance" --created-by "user@example.com"
+
+      lgtm alerts silence-create -m 'alertname=HighCPU' -m 'severity=warning' -d 1h -c "Investigating" --created-by "ops"
+    """
+    try:
+        parsed_matchers = [parse_matcher(m) for m in matchers]
+        delta = parse_duration(duration)
+        now = datetime.now(timezone.utc)
+        starts_at = now.strftime("%Y-%m-%dT%H:%M:%SZ")
+        ends_at = (now + delta).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+        result = ctx.obj["client"].create_silence(
+            matchers=parsed_matchers,
+            starts_at=starts_at,
+            ends_at=ends_at,
+            created_by=created_by,
+            comment=comment,
+        )
+        output_json(result)
+    except click.BadParameter as e:
+        output_error(str(e))
+        sys.exit(1)
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+@alerts.command("silence-delete")
+@click.argument("silence_id")
+@click.pass_context
+def alerts_silence_delete(ctx, silence_id: str):
+    """Delete/expire a silence by ID.
+
+    Examples:
+
+      lgtm alerts silence-delete abc123-def456
+    """
+    try:
+        ctx.obj["client"].delete_silence(silence_id)
+        click.echo(f"Silence {silence_id} deleted successfully")
+    except Exception as e:
+        output_error(str(e))
+        sys.exit(1)
+
+
+# === CONFIG COMMANDS ===
+
+@main.command()
+@click.pass_context
+def instances(ctx):
+    """List configured instances."""
+    config = ctx.obj["config"]
+    result = {
+        "default": config.default_instance,
+        "instances": {}
+    }
+    for name, instance in config.instances.items():
+        result["instances"][name] = {
+            "loki": instance.loki.url if instance.loki else None,
+            "prometheus": instance.prometheus.url if instance.prometheus else None,
+            "tempo": instance.tempo.url if instance.tempo else None,
+            "alerting": instance.alerting.url if instance.alerting else None,
+        }
+    output_json(result)
+
+
+if __name__ == "__main__":
+    main()

lgtm_cli-0.1.0/src/lgtm_cli/client.py

@@ -0,0 +1,239 @@
+import base64
+from urllib.parse import urlencode
+
+import httpx
+
+from .config import ServiceConfig
+
+
+class LGTMClient:
+    def __init__(self, config: ServiceConfig, timeout: float = 30.0):
+        self.config = config
+        self.base_url = config.url.rstrip("/")
+        self.timeout = timeout
+
+    def _get_headers(self) -> dict[str, str]:
+        headers = {"Accept": "application/json"}
+        if self.config.username and self.config.token:
+            credentials = f"{self.config.username}:{self.config.token}"
+            encoded = base64.b64encode(credentials.encode()).decode()
+            headers["Authorization"] = f"Basic {encoded}"
+        elif self.config.token:
+            headers["Authorization"] = f"Bearer {self.config.token}"
+        if self.config.headers:
+            headers.update(self.config.headers)
+        return headers
+
+    def get(self, path: str, params: dict | None = None) -> dict:
+        url = f"{self.base_url}{path}"
+        with httpx.Client(timeout=self.timeout) as client:
+            response = client.get(url, params=params, headers=self._get_headers())
+            response.raise_for_status()
+            return response.json()
+
+    def post(self, path: str, data: dict | None = None, params: dict | None = None) -> dict:
+        url = f"{self.base_url}{path}"
+        with httpx.Client(timeout=self.timeout) as client:
+            response = client.post(url, data=data, params=params, headers=self._get_headers())
+            response.raise_for_status()
+            return response.json()
+
+    def post_json(self, path: str, json_data: dict | None = None, params: dict | None = None) -> dict:
+        url = f"{self.base_url}{path}"
+        with httpx.Client(timeout=self.timeout) as client:
+            response = client.post(url, json=json_data, params=params, headers=self._get_headers())
+            response.raise_for_status()
+            return response.json()
+
+    def delete(self, path: str, params: dict | None = None) -> dict:
+        url = f"{self.base_url}{path}"
+        with httpx.Client(timeout=self.timeout) as client:
+            response = client.delete(url, params=params, headers=self._get_headers())
+            response.raise_for_status()
+            if response.text:
+                return response.json()
+            return {}
+
+
+class LokiClient(LGTMClient):
+    def query(self, query: str, start: str, end: str, limit: int = 100, direction: str = "backward") -> dict:
+        return self.get("/loki/api/v1/query_range", {
+            "query": query,
+            "start": start,
+            "end": end,
+            "limit": limit,
+            "direction": direction,
+        })
+
+    def query_instant(self, query: str, time: str | None = None) -> dict:
+        params = {"query": query}
+        if time:
+            params["time"] = time
+        return self.get("/loki/api/v1/query", params)
+
+    def labels(self, start: str | None = None, end: str | None = None) -> dict:
+        params = {}
+        if start:
+            params["start"] = start
+        if end:
+            params["end"] = end
+        return self.get("/loki/api/v1/labels", params or None)
+
+    def label_values(self, label: str, start: str | None = None, end: str | None = None) -> dict:
+        params = {}
+        if start:
+            params["start"] = start
+        if end:
+            params["end"] = end
+        return self.get(f"/loki/api/v1/label/{label}/values", params or None)
+
+    def series(self, match: list[str], start: str | None = None, end: str | None = None) -> dict:
+        params = {"match[]": match}
+        if start:
+            params["start"] = start
+        if end:
+            params["end"] = end
+        return self.get("/loki/api/v1/series", params)
+
+
+class PrometheusClient(LGTMClient):
+    def query(self, query: str, time: str | None = None) -> dict:
+        params = {"query": query}
+        if time:
+            params["time"] = time
+        return self.get("/api/v1/query", params)
+
+    def query_range(self, query: str, start: str, end: str, step: str = "60s") -> dict:
+        return self.get("/api/v1/query_range", {
+            "query": query,
+            "start": start,
+            "end": end,
+            "step": step,
+        })
+
+    def labels(self, start: str | None = None, end: str | None = None) -> dict:
+        params = {}
+        if start:
+            params["start"] = start
+        if end:
+            params["end"] = end
+        return self.get("/api/v1/labels", params or None)
+
+    def label_values(self, label: str, start: str | None = None, end: str | None = None) -> dict:
+        params = {}
+        if start:
+            params["start"] = start
+        if end:
+            params["end"] = end
+        return self.get(f"/api/v1/label/{label}/values", params or None)
+
+    def series(self, match: list[str], start: str | None = None, end: str | None = None) -> dict:
+        params = {"match[]": match}
+        if start:
+            params["start"] = start
+        if end:
+            params["end"] = end
+        return self.get("/api/v1/series", params)
+
+    def metadata(self, metric: str | None = None) -> dict:
+        params = {}
+        if metric:
+            params["metric"] = metric
+        return self.get("/api/v1/metadata", params or None)
+
+
+class TempoClient(LGTMClient):
+    def trace(self, trace_id: str) -> dict:
+        return self.get(f"/api/traces/{trace_id}")
+
+    def search(
+        self,
+        query: str | None = None,
+        start: str | None = None,
+        end: str | None = None,
+        min_duration: str | None = None,
+        max_duration: str | None = None,
+        limit: int = 20,
+    ) -> dict:
+        params = {"limit": limit}
+        if query:
+            params["q"] = query
+        if start:
+            params["start"] = start
+        if end:
+            params["end"] = end
+        if min_duration:
+            params["minDuration"] = min_duration
+        if max_duration:
+            params["maxDuration"] = max_duration
+        return self.get("/api/search", params)
+
+    def tags(self) -> dict:
+        return self.get("/api/search/tags")
+
+    def tag_values(self, tag: str) -> dict:
+        return self.get(f"/api/search/tag/{tag}/values")
+
+
+class AlertingClient(LGTMClient):
+    BASE_PATH = "/api/alertmanager/grafana/api/v2"
+
+    def list_alerts(
+        self,
+        filter: list[str] | None = None,
+        receiver: str | None = None,
+        silenced: bool = True,
+        inhibited: bool = True,
+        active: bool = True,
+    ) -> list:
+        params = {
+            "silenced": str(silenced).lower(),
+            "inhibited": str(inhibited).lower(),
+            "active": str(active).lower(),
+        }
+        if filter:
+            params["filter"] = filter
+        if receiver:
+            params["receiver"] = receiver
+        return self.get(f"{self.BASE_PATH}/alerts", params)
+
+    def list_alert_groups(
+        self,
+        filter: list[str] | None = None,
+        receiver: str | None = None,
+    ) -> list:
+        params = {}
+        if filter:
+            params["filter"] = filter
+        if receiver:
+            params["receiver"] = receiver
+        return self.get(f"{self.BASE_PATH}/alerts/groups", params or None)
+
+    def list_silences(self, filter: list[str] | None = None) -> list:
+        params = {}
+        if filter:
+            params["filter"] = filter
+        return self.get(f"{self.BASE_PATH}/silences", params or None)
+
+    def get_silence(self, silence_id: str) -> dict:
+        return self.get(f"{self.BASE_PATH}/silence/{silence_id}")
+
+    def create_silence(
+        self,
+        matchers: list[dict],
+        starts_at: str,
+        ends_at: str,
+        created_by: str,
+        comment: str,
+    ) -> dict:
+        payload = {
+            "matchers": matchers,
+            "startsAt": starts_at,
+            "endsAt": ends_at,
+            "createdBy": created_by,
+            "comment": comment,
+        }
+        return self.post_json(f"{self.BASE_PATH}/silences", payload)
+
+    def delete_silence(self, silence_id: str) -> dict:
+        return self.delete(f"{self.BASE_PATH}/silence/{silence_id}")

lgtm_cli-0.1.0/src/lgtm_cli/config.py

@@ -0,0 +1,136 @@
+import os
+import re
+import subprocess
+from pathlib import Path
+from dataclasses import dataclass
+
+import yaml
+
+
+DEFAULT_CONFIG_PATH = Path.home() / ".config" / "lgtm" / "config.yaml"
+
+
+@dataclass
+class ServiceConfig:
+    url: str
+    token: str | None = None
+    username: str | None = None
+    headers: dict[str, str] | None = None
+
+
+@dataclass
+class InstanceConfig:
+    name: str
+    loki: ServiceConfig | None = None
+    prometheus: ServiceConfig | None = None
+    tempo: ServiceConfig | None = None
+    alerting: ServiceConfig | None = None
+
+
+@dataclass
+class Config:
+    version: str
+    default_instance: str | None
+    instances: dict[str, InstanceConfig]
+
+    def get_instance(self, name: str | None = None) -> InstanceConfig:
+        if name:
+            if name not in self.instances:
+                raise ValueError(f"Instance '{name}' not found in config")
+            return self.instances[name]
+        if self.default_instance:
+            return self.instances[self.default_instance]
+        return next(iter(self.instances.values()))
+
+
+def resolve_1password_ref(ref: str) -> str:
+    """Resolve a 1Password reference using the op CLI.
+
+    Args:
+        ref: 1Password reference in format 'op://vault/item/field'
+
+    Returns:
+        The secret value from 1Password
+
+    Raises:
+        RuntimeError: If op CLI fails or is not available
+    """
+    try:
+        result = subprocess.run(
+            ["op", "read", ref],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip()
+    except FileNotFoundError:
+        raise RuntimeError("1Password CLI (op) not found. Install it from https://1password.com/downloads/command-line/")
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(f"Failed to read from 1Password: {e.stderr.strip()}")
+
+
+def resolve_secret(value: str) -> str:
+    """Resolve secrets from environment variables or 1Password.
+
+    Supports:
+    - Environment variables: ${VAR_NAME}
+    - 1Password references: op://vault/item/field
+
+    Args:
+        value: The value to resolve
+
+    Returns:
+        The resolved value with secrets substituted
+    """
+    # Check if entire value is a 1Password reference
+    if value.startswith("op://"):
+        return resolve_1password_ref(value)
+
+    # Handle ${op://...} pattern for 1Password within strings
+    op_pattern = r'\$\{(op://[^}]+)\}'
+    def replace_op(match):
+        return resolve_1password_ref(match.group(1))
+    value = re.sub(op_pattern, replace_op, value)
+
+    # Handle ${VAR_NAME} pattern for environment variables
+    env_pattern = r'\$\{([^}]+)\}'
+    def replace_env(match):
+        var_name = match.group(1)
+        return os.environ.get(var_name, "")
+    return re.sub(env_pattern, replace_env, value)
+
+
+def parse_service_config(data: dict | None) -> ServiceConfig | None:
+    if not data:
+        return None
+    return ServiceConfig(
+        url=resolve_secret(data.get("url", "")),
+        token=resolve_secret(data["token"]) if data.get("token") else None,
+        username=resolve_secret(data["username"]) if data.get("username") else None,
+        headers={k: resolve_secret(v) for k, v in data.get("headers", {}).items()} or None,
+    )
+
+
+def load_config(path: Path | None = None) -> Config:
+    config_path = path or DEFAULT_CONFIG_PATH
+    if not config_path.exists():
+        raise FileNotFoundError(f"Config file not found: {config_path}")
+
+    with open(config_path) as f:
+        data = yaml.safe_load(f)
+
+    instances = {}
+    for name, instance_data in data.get("instances", {}).items():
+        instances[name] = InstanceConfig(
+            name=name,
+            loki=parse_service_config(instance_data.get("loki")),
+            prometheus=parse_service_config(instance_data.get("prometheus")),
+            tempo=parse_service_config(instance_data.get("tempo")),
+            alerting=parse_service_config(instance_data.get("alerting")),
+        )
+
+    return Config(
+        version=data.get("version", "1"),
+        default_instance=data.get("default_instance"),
+        instances=instances,
+    )