clirey 0.1.0__tar.gz

clirey-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: clirey
+Version: 0.1.0
+Summary: A powerful CLI & live terminal monitor for Celery with just a broker URL
+Author-email: Inzam <your-email@example.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/inzam/clirey
+Project-URL: Documentation, https://github.com/inzam/clirey#readme
+Project-URL: Repository, https://github.com/inzam/clirey
+Project-URL: Issues, https://github.com/inzam/clirey/issues
+Keywords: celery,cli,monitoring,redis,rabbitmq,tui,rich,dashboard
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: celery>=5.3.0
+Requires-Dist: redis>=5.0.0
+Requires-Dist: kombu>=5.3.0
+Requires-Dist: amqp>=5.2.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: pydantic>=2.0.0
+
+# ⚡ Clirey
+
+**Clirey** is a modern, rich CLI tool and interactive live terminal dashboard (TUI) for monitoring and controlling **Celery** clusters using **only the Celery Broker URL**—with zero dependencies on your worker application code, task definitions, or backend database.
+
+---
+
+## ✨ Features
+
+- **No Task Code Required**: Connects to the Celery cluster solely via the Broker URL (`redis://`, `rediss://`, `amqp://`, `pyamqp://`).
+- **🖥️ Live Interactive TUI Dashboard (`clirey top` / `clirey monitor`)**:
+  - **Cluster Overview**: Online/Offline workers count, active running tasks, throughput (events/sec), total processed, failure counts.
+  - **Worker Matrix**: Worker node names, status, pool concurrency, OS load averages (1m, 5m, 15m), and uptime.
+  - **Active Tasks**: Real-time running tasks, executing worker node, runtime duration, and arguments.
+  - **Queues & Backlog**: Worker consumers count and direct broker pending message depth (e.g. Redis `LLEN` / RabbitMQ queue declare).
+  - **Live Event Stream**: Real-time event ticker (succeeded, failed, retried, started, worker heartbeats) with durations and exception details.
+- **⚡ Scriptable One-Shot Commands**:
+  - `clirey workers`: List active worker nodes, pool configs, uptime, and load averages.
+  - `clirey tasks`: View currently active, scheduled (ETA), or reserved tasks.
+  - `clirey queues`: Broker queue depths and worker subscription mapping.
+  - `clirey events`: Live streaming event tail on your console.
+  - `clirey ping`: Ping all active workers and calculate cluster round-trip latency.
+  - `clirey task <task_id>`: Inspect task status and worker assignment.
+  - `clirey revoke <task_id>`: Remotely revoke or terminate running tasks.
+- **🎮 Built-in Simulator (`clirey demo`)**: Run and test the live terminal dashboard instantly without needing a live Celery cluster.
+- **🔐 Automatic Credential Masking**: Passwords and secrets in broker connection strings are automatically masked in terminal outputs.
+
+---
+
+## 🚀 Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/clirey.git
+cd clirey
+
+# Create virtual environment and install
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+---
+
+## ⚙️ Broker URL Configuration
+
+You can provide the broker URL in any of the following ways (in priority order):
+
+1. **CLI Option**: `--broker` or `-b`
+   ```bash
+   clirey top -b redis://:password@10.0.1.50:6379/0
+   ```
+2. **Environment Variable**: `CELERY_BROKER_URL` or `CLIREY_BROKER_URL` or `REDIS_URL`
+   ```bash
+   export CELERY_BROKER_URL="amqp://guest:guest@localhost:5672//"
+   clirey top
+   ```
+3. **Config File (`.clirey.json` or `~/.clirey.json`)**:
+   ```json
+   {
+     "broker_url": "redis://localhost:6379/0"
+   }
+   ```
+
+---
+
+## 📖 Usage Guide
+
+### 1. Launch Live Interactive Terminal Dashboard
+```bash
+clirey top
+# or with explicit broker
+clirey top --broker redis://localhost:6379/0 --refresh 1.5
+```
+
+### 2. Try the Demo Simulator
+```bash
+clirey demo
+```
+
+### 3. List Connected Workers
+```bash
+clirey workers
+```
+Output:
+```
+                                        Active Celery Workers                                         
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┓
+┃ Worker Node                ┃  Status  ┃ Active ┃ Processed ┃ Concurrency ┃ Pool    ┃ Load Avg (1,5,15m) ┃   Uptime ┃ Queues  ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━┩
+│ celery@worker-1.prod       │ ● ONLINE │      2 │    14,320 │           8 │ prefork │ 0.45, 0.38, 0.30   │  23h 40m │ default │
+│ celery@worker-2.prod       │ ● ONLINE │      1 │     9,812 │           4 │ gevent  │ 0.12, 0.15, 0.18   │  10h 15m │ reports │
+└────────────────────────────┴──────────┴────────┴━━━━━━━━━━━┴━━━━━━━━━━━━━┴━━━━━━━━━┴━━━━━━━━━━━━━━━━━━━━┴━━━━━━━━━━┴─────────┘
+```
+
+### 4. Inspect Queues & Backlog
+```bash
+clirey queues
+```
+
+### 5. List Active & Scheduled Tasks
+```bash
+clirey tasks --type active
+clirey tasks --type scheduled
+```
+
+### 6. Stream Live Events
+```bash
+clirey events
+```
+
+### 7. Ping Active Workers
+```bash
+clirey ping
+```
+
+### 8. Revoke / Terminate a Task
+```bash
+clirey revoke <task-uuid> --terminate --signal SIGTERM
+```
+
+---
+
+## 🧪 Running Tests
+
+```bash
+pytest
+```
+
+---
+
+## 📜 License
+
+MIT License

clirey-0.1.0/README.md

@@ -0,0 +1,133 @@
+# ⚡ Clirey
+
+**Clirey** is a modern, rich CLI tool and interactive live terminal dashboard (TUI) for monitoring and controlling **Celery** clusters using **only the Celery Broker URL**—with zero dependencies on your worker application code, task definitions, or backend database.
+
+---
+
+## ✨ Features
+
+- **No Task Code Required**: Connects to the Celery cluster solely via the Broker URL (`redis://`, `rediss://`, `amqp://`, `pyamqp://`).
+- **🖥️ Live Interactive TUI Dashboard (`clirey top` / `clirey monitor`)**:
+  - **Cluster Overview**: Online/Offline workers count, active running tasks, throughput (events/sec), total processed, failure counts.
+  - **Worker Matrix**: Worker node names, status, pool concurrency, OS load averages (1m, 5m, 15m), and uptime.
+  - **Active Tasks**: Real-time running tasks, executing worker node, runtime duration, and arguments.
+  - **Queues & Backlog**: Worker consumers count and direct broker pending message depth (e.g. Redis `LLEN` / RabbitMQ queue declare).
+  - **Live Event Stream**: Real-time event ticker (succeeded, failed, retried, started, worker heartbeats) with durations and exception details.
+- **⚡ Scriptable One-Shot Commands**:
+  - `clirey workers`: List active worker nodes, pool configs, uptime, and load averages.
+  - `clirey tasks`: View currently active, scheduled (ETA), or reserved tasks.
+  - `clirey queues`: Broker queue depths and worker subscription mapping.
+  - `clirey events`: Live streaming event tail on your console.
+  - `clirey ping`: Ping all active workers and calculate cluster round-trip latency.
+  - `clirey task <task_id>`: Inspect task status and worker assignment.
+  - `clirey revoke <task_id>`: Remotely revoke or terminate running tasks.
+- **🎮 Built-in Simulator (`clirey demo`)**: Run and test the live terminal dashboard instantly without needing a live Celery cluster.
+- **🔐 Automatic Credential Masking**: Passwords and secrets in broker connection strings are automatically masked in terminal outputs.
+
+---
+
+## 🚀 Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/clirey.git
+cd clirey
+
+# Create virtual environment and install
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+---
+
+## ⚙️ Broker URL Configuration
+
+You can provide the broker URL in any of the following ways (in priority order):
+
+1. **CLI Option**: `--broker` or `-b`
+   ```bash
+   clirey top -b redis://:password@10.0.1.50:6379/0
+   ```
+2. **Environment Variable**: `CELERY_BROKER_URL` or `CLIREY_BROKER_URL` or `REDIS_URL`
+   ```bash
+   export CELERY_BROKER_URL="amqp://guest:guest@localhost:5672//"
+   clirey top
+   ```
+3. **Config File (`.clirey.json` or `~/.clirey.json`)**:
+   ```json
+   {
+     "broker_url": "redis://localhost:6379/0"
+   }
+   ```
+
+---
+
+## 📖 Usage Guide
+
+### 1. Launch Live Interactive Terminal Dashboard
+```bash
+clirey top
+# or with explicit broker
+clirey top --broker redis://localhost:6379/0 --refresh 1.5
+```
+
+### 2. Try the Demo Simulator
+```bash
+clirey demo
+```
+
+### 3. List Connected Workers
+```bash
+clirey workers
+```
+Output:
+```
+                                        Active Celery Workers                                         
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┓
+┃ Worker Node                ┃  Status  ┃ Active ┃ Processed ┃ Concurrency ┃ Pool    ┃ Load Avg (1,5,15m) ┃   Uptime ┃ Queues  ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━┩
+│ celery@worker-1.prod       │ ● ONLINE │      2 │    14,320 │           8 │ prefork │ 0.45, 0.38, 0.30   │  23h 40m │ default │
+│ celery@worker-2.prod       │ ● ONLINE │      1 │     9,812 │           4 │ gevent  │ 0.12, 0.15, 0.18   │  10h 15m │ reports │
+└────────────────────────────┴──────────┴────────┴━━━━━━━━━━━┴━━━━━━━━━━━━━┴━━━━━━━━━┴━━━━━━━━━━━━━━━━━━━━┴━━━━━━━━━━┴─────────┘
+```
+
+### 4. Inspect Queues & Backlog
+```bash
+clirey queues
+```
+
+### 5. List Active & Scheduled Tasks
+```bash
+clirey tasks --type active
+clirey tasks --type scheduled
+```
+
+### 6. Stream Live Events
+```bash
+clirey events
+```
+
+### 7. Ping Active Workers
+```bash
+clirey ping
+```
+
+### 8. Revoke / Terminate a Task
+```bash
+clirey revoke <task-uuid> --terminate --signal SIGTERM
+```
+
+---
+
+## 🧪 Running Tests
+
+```bash
+pytest
+```
+
+---
+
+## 📜 License
+
+MIT License

clirey-0.1.0/clirey/__init__.py

@@ -0,0 +1,3 @@
+"""Clirey: Celery CLI Monitoring & Live Dashboard."""
+
+__version__ = "0.1.0"

clirey-0.1.0/clirey/cli.py

@@ -0,0 +1,270 @@
+import os
+import sys
+from typing import Optional
+
+# Ensure UTF-8 output streams on Windows
+if sys.platform.startswith("win"):
+    try:
+        if sys.stdout and hasattr(sys.stdout, "reconfigure"):
+            sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        if sys.stderr and hasattr(sys.stderr, "reconfigure"):
+            sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+
+import time
+import typer
+from rich.panel import Panel
+from rich.text import Text
+from clirey.config import ClireyConfig, mask_broker_url
+from clirey.core.client import CeleryClient
+from clirey.core.events import EventMonitor
+from clirey.mock.simulator import MockDashboard
+from clirey.ui.console import console, err_console, format_event_badge
+from clirey.ui.dashboard import Dashboard
+from clirey.ui.tables import (
+    create_events_table,
+    create_queues_table,
+    create_tasks_table,
+    create_workers_table,
+)
+
+app = typer.Typer(
+    name="clirey",
+    help="Clirey: Modern CLI & Live Terminal Monitor for Celery with just a Broker URL.",
+    add_completion=False,
+)
+
+
+
+def get_resolved_broker(broker: Optional[str]) -> str:
+    """Resolve and validate broker URL."""
+    resolved = ClireyConfig.resolve_broker_url(broker)
+    if not resolved:
+        err_console.print(
+            "[bold red]Error:[/] No Celery broker URL specified!\n"
+            "Provide it via [bold yellow]--broker <url>[/] or set the [bold yellow]CELERY_BROKER_URL[/] environment variable."
+        )
+        raise typer.Exit(code=1)
+    return resolved
+
+
+@app.command(name="top")
+@app.command(name="monitor")
+@app.command(name="live")
+def cmd_top(
+    broker: Optional[str] = typer.Option(
+        None,
+        "--broker",
+        "-b",
+        help="Celery broker URL (e.g., redis://localhost:6379/0 or amqp://guest:guest@localhost:5672//)",
+    ),
+    backend: Optional[str] = typer.Option(
+        None,
+        "--backend",
+        help="Optional Celery result backend URL",
+    ),
+    refresh: float = typer.Option(
+        1.5,
+        "--refresh",
+        "-r",
+        help="Dashboard refresh interval in seconds",
+    ),
+):
+    """Launch the real-time interactive TUI dashboard."""
+    broker_url = get_resolved_broker(broker)
+    dashboard = Dashboard(broker_url=broker_url, backend_url=backend, refresh_rate=refresh)
+    dashboard.run()
+
+
+@app.command(name="demo")
+def cmd_demo(
+    refresh: float = typer.Option(
+        1.0,
+        "--refresh",
+        "-r",
+        help="Demo refresh interval in seconds",
+    ),
+):
+    """Run an interactive live demo simulator without needing a live Celery broker."""
+    demo = MockDashboard(refresh_rate=refresh)
+    demo.run()
+
+
+@app.command(name="workers")
+@app.command(name="status")
+def cmd_workers(
+    broker: Optional[str] = typer.Option(None, "--broker", "-b", help="Celery broker URL"),
+    timeout: float = typer.Option(3.0, "--timeout", "-t", help="Timeout for worker inspection in seconds"),
+):
+    """List all connected Celery workers, pool concurrency, load, and stats."""
+    broker_url = get_resolved_broker(broker)
+    console.print(f"[dim]Connecting to broker: {mask_broker_url(broker_url)}[/]")
+
+    with console.status("[bold cyan]Inspecting Celery workers...[/]", spinner="dots"):
+        client = CeleryClient(broker_url=broker_url, timeout=timeout)
+        workers = client.get_workers()
+
+    if not workers:
+        console.print(
+            Panel(
+                "[bold yellow]No Celery workers responded within timeout.[/]\n\n"
+                "• Check if workers are running and connected to this broker.\n"
+                "• Verify that the broker URL is reachable.",
+                title="[bold red]No Workers Detected[/]",
+                border_style="red",
+            )
+        )
+        return
+
+    table = create_workers_table(workers)
+    console.print(table)
+
+
+@app.command(name="tasks")
+def cmd_tasks(
+    broker: Optional[str] = typer.Option(None, "--broker", "-b", help="Celery broker URL"),
+    filter_type: str = typer.Option(
+        "all",
+        "--type",
+        "-t",
+        help="Task type to display: all, active, scheduled, reserved",
+    ),
+    timeout: float = typer.Option(3.0, "--timeout", help="Timeout in seconds"),
+):
+    """List currently active, scheduled, or reserved tasks across the cluster."""
+    broker_url = get_resolved_broker(broker)
+    client = CeleryClient(broker_url=broker_url, timeout=timeout)
+
+    with console.status("[bold cyan]Fetching tasks from workers...[/]", spinner="dots"):
+        active = client.get_active_tasks() if filter_type in ("all", "active") else []
+        scheduled = client.get_scheduled_tasks() if filter_type in ("all", "scheduled") else []
+        reserved = client.get_reserved_tasks() if filter_type in ("all", "reserved") else []
+
+    all_tasks = active + scheduled + reserved
+    if not all_tasks:
+        console.print("[yellow]No tasks currently running or queued in workers.[/]")
+        return
+
+    table = create_tasks_table(all_tasks, title=f"Celery Tasks ({len(all_tasks)} found)")
+    console.print(table)
+
+
+@app.command(name="queues")
+def cmd_queues(
+    broker: Optional[str] = typer.Option(None, "--broker", "-b", help="Celery broker URL"),
+    timeout: float = typer.Option(3.0, "--timeout", help="Timeout in seconds"),
+):
+    """Inspect broker queue backlog depths and active worker subscriptions."""
+    broker_url = get_resolved_broker(broker)
+    client = CeleryClient(broker_url=broker_url, timeout=timeout)
+
+    with console.status("[bold cyan]Querying queues and broker backlog...[/]", spinner="dots"):
+        queues = client.get_queues()
+
+    table = create_queues_table(queues)
+    console.print(table)
+
+
+@app.command(name="events")
+def cmd_events(
+    broker: Optional[str] = typer.Option(None, "--broker", "-b", help="Celery broker URL"),
+):
+    """Stream real-time Celery events to standard output."""
+    broker_url = get_resolved_broker(broker)
+    console.print(f"[bold cyan]⚡ Streaming live Celery events from:[/] {mask_broker_url(broker_url)}")
+    console.print("[dim]Press Ctrl+C to stop streaming.\n[/]")
+
+    client = CeleryClient(broker_url=broker_url)
+
+    def on_event(ev):
+        t_str = time.strftime("%H:%M:%S", time.localtime(ev.timestamp))
+        task_name = ev.task_name or "unknown"
+        tid = f"[{ev.task_id[:8]}]" if ev.task_id else ""
+        dur = f"({ev.runtime:.2f}s)" if ev.runtime is not None else ""
+        worker = f"@{ev.worker}" if ev.worker else ""
+        badge = format_event_badge(ev.event_type)
+
+        console.print(f"[dim]{t_str}[/]  {badge}  [bold yellow]{task_name}[/] [dim]{tid}[/] [cyan]{worker}[/] [green]{dur}[/]")
+        if ev.exception:
+            console.print(f"       [red]└─ Error: {ev.exception}[/]")
+
+    monitor = EventMonitor(client, on_event_callback=on_event)
+    monitor.start()
+
+    try:
+        while True:
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        monitor.stop()
+        console.print("\n[yellow]Stopped event stream.[/]")
+
+
+@app.command(name="ping")
+def cmd_ping(
+    broker: Optional[str] = typer.Option(None, "--broker", "-b", help="Celery broker URL"),
+    timeout: float = typer.Option(3.0, "--timeout", help="Timeout in seconds"),
+):
+    """Ping active Celery workers and check response latency."""
+    broker_url = get_resolved_broker(broker)
+    client = CeleryClient(broker_url=broker_url, timeout=timeout)
+
+    t0 = time.perf_counter()
+    with console.status("[bold cyan]Pinging workers...[/]", spinner="dots"):
+        res = client.ping()
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+
+    if not res:
+        console.print("[bold red]✖ No response from any worker.[/]")
+        raise typer.Exit(code=1)
+
+    console.print(f"[bold green]✔ Received responses in {elapsed_ms:.1f}ms:[/]")
+    for worker, reply in res.items():
+        console.print(f"  • [bold cyan]{worker}:[/] [green]{reply}[/]")
+
+
+@app.command(name="task")
+def cmd_task(
+    task_id: str = typer.Argument(..., help="Celery task UUID to inspect"),
+    broker: Optional[str] = typer.Option(None, "--broker", "-b", help="Celery broker URL"),
+    backend: Optional[str] = typer.Option(None, "--backend", help="Optional result backend URL"),
+):
+    """Query a specific task across workers and result backend."""
+    broker_url = get_resolved_broker(broker)
+    client = CeleryClient(broker_url=broker_url, backend_url=backend)
+
+    with console.status(f"[bold cyan]Querying task {task_id}...[/]", spinner="dots"):
+        info = client.query_task(task_id)
+
+    console.print(Panel(str(info), title=f"Task Query: {task_id}", border_style="cyan"))
+
+
+@app.command(name="revoke")
+def cmd_revoke(
+    task_id: str = typer.Argument(..., help="Celery task UUID to revoke"),
+    broker: Optional[str] = typer.Option(None, "--broker", "-b", help="Celery broker URL"),
+    terminate: bool = typer.Option(False, "--terminate", "-t", help="Terminate currently executing task process"),
+    signal: str = typer.Option("SIGTERM", "--signal", "-s", help="Signal to send when terminating (e.g. SIGTERM, SIGKILL)"),
+):
+    """Revoke or terminate a Celery task by ID."""
+    broker_url = get_resolved_broker(broker)
+    client = CeleryClient(broker_url=broker_url)
+
+    confirm = typer.confirm(f"Are you sure you want to revoke task '{task_id}' (terminate={terminate})?")
+    if not confirm:
+        console.print("[yellow]Aborted.[/]")
+        return
+
+    with console.status(f"[bold cyan]Revoking task {task_id}...[/]", spinner="dots"):
+        res = client.revoke_task(task_id, terminate=terminate, signal=signal)
+
+    console.print(f"[bold green]✔ Revoke broadcast sent.[/] Replies: {res}")
+
+
+def main():
+    """Main entrypoint for CLI execution."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

clirey-0.1.0/clirey/config.py

@@ -0,0 +1,76 @@
+"""Configuration and Broker URL resolution for Clirey."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse, urlunparse
+from pydantic import BaseModel, Field
+
+
+def mask_broker_url(url: str) -> str:
+    """Mask password and sensitive credentials in broker URL for display."""
+    if not url:
+        return ""
+    try:
+        parsed = urlparse(url)
+        if parsed.password:
+            netloc = f"{parsed.username or ''}:****@{parsed.hostname or ''}"
+            if parsed.port:
+                netloc += f":{parsed.port}"
+            masked = parsed._replace(netloc=netloc)
+            return urlunparse(masked)
+        return url
+    except Exception:
+        # Fallback regex mask
+        return re.sub(r":([^@]+)@", r":****@", url)
+
+
+class ClireyConfig(BaseModel):
+    """Clirey configuration settings."""
+    broker_url: str = Field(default="redis://localhost:6379/0", description="Celery broker connection URL")
+    result_backend: Optional[str] = Field(default=None, description="Optional Celery result backend URL")
+    refresh_rate: float = Field(default=1.5, description="Dashboard refresh rate in seconds")
+    timeout: float = Field(default=2.5, description="Timeout for inspect / ping requests")
+    event_buffer_size: int = Field(default=1000, description="Max event log buffer size")
+    max_history_tasks: int = Field(default=500, description="Max task history records")
+
+    @classmethod
+    def resolve_broker_url(cls, explicit_url: Optional[str] = None) -> str:
+        """Resolve broker URL by checking:
+        1. Explicitly passed parameter
+        2. Environment variables: CELERY_BROKER_URL, CLIREY_BROKER_URL, REDIS_URL, RABBITMQ_URL, AMQP_URL
+        3. Config file in current directory or user home
+        4. Default localhost redis
+        """
+        if explicit_url and explicit_url.strip():
+            return explicit_url.strip()
+
+        env_keys = [
+            "CLIREY_BROKER_URL",
+            "CELERY_BROKER_URL",
+            "REDIS_URL",
+            "RABBITMQ_URL",
+            "AMQP_URL",
+        ]
+        for key in env_keys:
+            val = os.environ.get(key)
+            if val and val.strip():
+                return val.strip()
+
+        # Check for config files (.clirey.json or ~/.clirey.json)
+        local_cfg = Path(".clirey.json")
+        home_cfg = Path.home() / ".clirey.json"
+        for p in [local_cfg, home_cfg]:
+            if p.exists() and p.is_file():
+                try:
+                    import json
+                    data = json.loads(p.read_text(encoding="utf-8"))
+                    if "broker_url" in data and data["broker_url"]:
+                        return str(data["broker_url"]).strip()
+                except Exception:
+                    pass
+
+        return "redis://localhost:6379/0"