{"id":35430182,"url":"https://github.com/mfhonley/catops","last_synced_at":"2026-02-17T23:08:47.529Z","repository":{"id":311514423,"uuid":"1039275261","full_name":"mfhonley/catops","owner":"mfhonley","description":"CatOps CLI — the simplest way to bring monitoring and intelligence into your infrastructure. One command, instant visibility.","archived":false,"fork":false,"pushed_at":"2026-01-10T18:24:37.000Z","size":5572,"stargazers_count":48,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-11T04:05:35.627Z","etag":null,"topics":["automatization","cli","devops","go","golang","metrics","monitoring","monitoring-tool","server-monitoring"],"latest_commit_sha":null,"homepage":"https://catops.app","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mfhonley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-16T21:22:22.000Z","updated_at":"2026-01-10T18:24:27.000Z","dependencies_parsed_at":"2025-08-25T01:40:18.515Z","dependency_job_id":"a2b04cc7-33a8-458e-bbc0-a6167e071a57","html_url":"https://github.com/mfhonley/catops","commit_stats":null,"previous_names":["honley1/moniq.sh","honley1/catops","mfhonley/catops"],"tags_count":97,"template":false,"template_full_name":null,"purl":"pkg:github/mfhonley/catops","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfhonley%2Fcatops","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfhonley%2Fcatops/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfhonley%2Fcatops/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfhonley%2Fcatops/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mfhonley","download_url":"https://codeload.github.com/mfhonley/catops/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfhonley%2Fcatops/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28340255,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T12:22:26.515Z","status":"ssl_error","status_checked_at":"2026-01-12T12:22:10.856Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automatization","cli","devops","go","golang","metrics","monitoring","monitoring-tool","server-monitoring"],"created_at":"2026-01-02T20:24:32.478Z","updated_at":"2026-02-17T23:08:47.522Z","avatar_url":"https://github.com/mfhonley.png","language":"Go","readme":"# CatOps CLI\n\n[![Go Version](https://img.shields.io/badge/Go-1.21+-blue.svg)](https://golang.org)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Kubernetes-lightgrey.svg)]()\n\n**Fast and convenient server monitoring with AI.** One command to install, zero configuration needed.\n\nMonitor standalone servers or Kubernetes clusters. Get Telegram/Slack/Email alerts and a beautiful web dashboard at [catops.app](https://catops.app).\n\n```bash\n# Install in seconds\ncurl -sfL https://get.catops.app/install.sh | bash\n```\n\n\u003e **Looking for Self-Hosted?** Check out [CatOps Hub](https://catops.app/hub) - single binary with embedded dashboard, no cloud required.\n\n---\n\n## Table of Contents\n\n- [Features](#-features)\n- [Quick Start](#-quick-start)\n- [Installation](#-installation)\n  - [Standalone Servers](#standalone-servers)\n  - [Kubernetes Clusters](#kubernetes-clusters)\n- [Usage](#-usage)\n  - [Basic Commands](#basic-commands)\n  - [AI Assistant](#ai-assistant)\n  - [Telegram Alerts](#telegram-alerts)\n  - [Cloud Mode](#cloud-mode-web-dashboard)\n- [Kubernetes Guide](#-kubernetes-guide)\n- [Configuration](#-configuration)\n- [Log Collection](#-log-collection)\n- [Troubleshooting](#-troubleshooting)\n- [Contributing](#-contributing)\n\n---\n\n## Features\n\n**Core Monitoring:**\n- System metrics (CPU, Memory, Disk, Network, I/O)\n- Process monitoring with resource usage\n- Service detection (nginx, postgres, redis, docker, and 12+ more)\n- **Log collection** from Docker containers\n- Real-time Telegram/Slack/Email alerts\n- Beautiful web dashboard\n- Cross-platform (Linux, macOS, Kubernetes)\n\n**AI-Powered:**\n- **AI Assistant** - Ask questions about your server directly from CLI\n- Smart alert analysis\n- Troubleshooting recommendations\n\n**Deployment Options:**\n- **Standalone**: Monitor individual servers (Linux/macOS)\n- **Kubernetes**: Monitor entire clusters with DaemonSet\n\n**Alerting:**\n- Telegram, Slack, Email notifications\n- Alert deduplication (no spam)\n- Interactive Telegram buttons (Acknowledge, Silence)\n- Instant notifications with detailed context\n\n**Management:**\n- Background service with auto-start\n- Simple CLI commands\n- Automatic updates\n- User-level installation (no root required)\n\n---\n\n## Quick Start\n\n### Standalone Server\n\n```bash\n# 1. Install\ncurl -sfL https://get.catops.app/install.sh | bash\n\n# 2. Check status\ncatops status\n\n# 3. Enable web dashboard (optional)\ncatops auth login YOUR_TOKEN\n```\n\n### Kubernetes Cluster\n\n```bash\n# 1. Get your token from https://catops.app/setup\n\n# 2. Install with Helm\nhelm install catops oci://ghcr.io/mfhonley/catops/helm-charts/catops \\\n  --namespace catops-system \\\n  --create-namespace \\\n  --set auth.token=YOUR_TOKEN\n\n# 3. Verify installation\nkubectl get pods -n catops-system\n```\n\nThat's it! Your servers/nodes appear in the dashboard within 60 seconds.\n\n---\n\n## Installation\n\n### Standalone Servers\n\n**Requirements:**\n- Linux (systemd) or macOS (launchd)\n- AMD64 or ARM64 architecture\n- No root privileges required\n\n**One-Command Install:**\n\n```bash\ncurl -sfL https://get.catops.app/install.sh | bash\n```\n\n**Operating Modes:**\n- **Local Mode** (default): Metrics collected locally, view with `catops status`\n- **Cloud Mode**: Telegram alerts + Web dashboard at [catops.app](https://catops.app)\n\n**Enable Cloud Mode for Telegram alerts:**\n```bash\n# 1. Install CatOps\ncurl -sfL https://get.catops.app/install.sh | bash\n\n# 2. Get token from https://catops.app\ncatops auth login YOUR_TOKEN\n\n# 3. Configure Telegram bot on catops.app dashboard\n```\n\n**From Source (Developers):**\n\n```bash\ngit clone https://github.com/mfhonley/catops.git\ncd catops/cli\ngo build -o catops ./cmd/catops\n./catops --version\n```\n\n---\n\n### Kubernetes Clusters\n\n**Requirements:**\n- Kubernetes 1.19+\n- Helm 3.0+\n- metrics-server installed\n\n**Quick Install:**\n\n```bash\n# Basic installation (core metrics only)\nhelm install catops oci://ghcr.io/mfhonley/catops/helm-charts/catops \\\n  --namespace catops-system \\\n  --create-namespace \\\n  --set auth.token=YOUR_TOKEN\n```\n\n**With Prometheus (Extended Metrics):**\n\n```bash\n# Includes pod labels, owner info, 200+ metrics\nhelm install catops oci://ghcr.io/mfhonley/catops/helm-charts/catops \\\n  --namespace catops-system \\\n  --create-namespace \\\n  --set auth.token=YOUR_TOKEN \\\n  --set prometheus.enabled=true \\\n  --set kubeStateMetrics.enabled=true\n```\n\n**Verify Installation:**\n\n```bash\n# Check pods are running\nkubectl get pods -n catops-system\n\n# Check logs\nkubectl logs -n catops-system -l app.kubernetes.io/name=catops --tail=20\n```\n\n---\n\n## Usage\n\n### Basic Commands\n\n**Monitoring:**\n```bash\ncatops status              # Show current metrics\ncatops processes           # Top processes by resource usage\ncatops restart             # Restart monitoring service\n```\n\n**AI Assistant:**\n```bash\ncatops ask \"Why is my CPU high?\"           # Ask AI about your server\ncatops ask \"What's causing memory spikes?\"  # Analyze issues\ncatops ask \"Should I be worried?\"           # Get recommendations\n```\n\n**Configuration:**\n```bash\ncatops config                       # Show current config\ncatops set interval=30              # Set metrics collection interval (10-300 seconds)\n```\n\n**Service Management:**\n```bash\ncatops service install     # Install as system service (systemd/launchd)\ncatops service start       # Start service\ncatops service stop        # Stop service\ncatops service restart     # Restart service\ncatops service status      # Check service status\ncatops service remove      # Remove service\n```\n\n**System:**\n```bash\ncatops update              # Check for updates and install\ncatops uninstall           # Remove CatOps completely\ncatops cleanup             # Clean up old backup files\ncatops --version           # Show version\n```\n\n### AI Assistant\n\nCatOps includes a **FREE** AI assistant that analyzes your server metrics and provides intelligent answers.\n\n**Features:**\n- Context-aware - Analyzes current CPU, Memory, Disk, and top processes\n- Fast responses - Optimized for CLI\n- Privacy-first - Only sends metrics, not logs\n- No subscription required\n\n**Examples:**\n```bash\ncatops ask \"Why is my CPU usage high?\"\ncatops ask \"What's causing memory spikes?\"\ncatops ask \"Should I be worried about disk usage?\"\ncatops ask \"Explain what's happening on my server\"\n```\n\n### Telegram Alerts\n\n**Setup:**\n1. Enable Cloud Mode: `catops auth login YOUR_TOKEN`\n2. Configure Telegram on [catops.app](https://catops.app) dashboard\n3. Connect your Telegram account\n4. Start receiving personal alerts\n\n**Interactive Alert Buttons:**\n\nWhen connected to [catops.app](https://catops.app), alerts include interactive buttons:\n\n```\nCPU Spike Detected\n\nserver-prod-01\n5.2% -\u003e 35.8% (+30.6% spike)\n\n[Acknowledge] [Silence] [Details]\n```\n\n- **Acknowledge** - Mark alert as seen, stop re-notifications\n- **Silence** - Mute alerts for 30m/1h/2h/24h (useful for maintenance)\n- **Details** - Open web dashboard for full metrics and history\n\n### Cloud Mode (Web Dashboard)\n\n**Enable web dashboard at [catops.app](https://catops.app):**\n\n```bash\n# 1. Get token from https://catops.app (Profile -\u003e Generate Auth Token)\n\n# 2. Login\ncatops auth login YOUR_AUTH_TOKEN\n\n# 3. Verify\ncatops auth info\n```\n\n**Benefits:**\n- Real-time metrics accessible from anywhere\n- Historical data and trends\n- Log collection and analysis\n- Multi-server monitoring\n- Team collaboration\n- Mobile-friendly interface\n\n**Operation Modes:**\n- **Local Mode** (default): Metrics collected locally, no alerts, works offline\n- **Cloud Mode**: Telegram alerts + Web dashboard + Multi-server monitoring + Log collection\n\n### Command Reference\n\n| Command | Description |\n|---------|-------------|\n| `catops` | Show help and available commands |\n| `catops status` | Display current system metrics |\n| `catops processes` | Show top processes by resource usage |\n| `catops ask \"question\"` | Ask AI about your server |\n| `catops start` | Start monitoring (foreground) |\n| `catops restart` | Restart monitoring service |\n| `catops config` | Show current configuration |\n| `catops set interval=N` | Set collection interval (10-300 sec) |\n| `catops auth login TOKEN` | Login with auth token |\n| `catops auth logout` | Clear authentication |\n| `catops auth info` | Show auth status |\n| `catops auth token` | Show full auth token |\n| `catops service install` | Install as system service |\n| `catops service remove` | Remove system service |\n| `catops service start` | Start service |\n| `catops service stop` | Stop service |\n| `catops service restart` | Restart service |\n| `catops service status` | Check service status |\n| `catops update` | Update to latest version |\n| `catops uninstall` | Remove CatOps completely |\n| `catops cleanup` | Clean up old backup files |\n| `catops force-cleanup` | Force cleanup stuck processes |\n| `catops --version` | Show version |\n\n---\n\n## Kubernetes Guide\n\n### Installation\n\n**Prerequisites Check:**\n\n```bash\n# Check Kubernetes version (need 1.19+)\nkubectl version --short\n\n# Check Helm installed (need 3.0+)\nhelm version --short\n\n# Verify metrics-server is working\nkubectl top nodes\n```\n\n**Install metrics-server (if needed):**\n\n```bash\nkubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml\n\n# For Docker Desktop, allow insecure TLS:\nkubectl patch deployment metrics-server -n kube-system \\\n  --type='json' \\\n  -p='[{\"op\": \"add\", \"path\": \"/spec/template/spec/containers/0/args/-\", \"value\": \"--kubelet-insecure-tls\"}]'\n```\n\n**Install CatOps:**\n\n```bash\n# Get your auth token from https://catops.app/setup\n\n# Install with Helm\nhelm install catops oci://ghcr.io/mfhonley/catops/helm-charts/catops \\\n  --namespace catops-system \\\n  --create-namespace \\\n  --set auth.token=YOUR_TOKEN \\\n  --set prometheus.enabled=true \\\n  --set kubeStateMetrics.enabled=true\n```\n\n### What Gets Monitored\n\n**Node Metrics (per node):**\n- CPU, Memory, Disk usage\n- Network I/O, HTTPS connections\n- Pod count and status\n- System information (OS, uptime)\n\n**Pod Metrics (per pod):**\n- CPU/Memory usage\n- Restart count, container count\n- Pod phase (Running/Pending/Failed)\n- Namespace, labels, owner info (with Prometheus)\n\n**Cluster Metrics:**\n- Total nodes / Ready nodes\n- Total pods / Running / Pending / Failed\n- Cluster health percentage\n\n### Managing CatOps\n\n**Update:**\n\n```bash\n# Update to latest version\nhelm upgrade catops oci://ghcr.io/mfhonley/catops/helm-charts/catops \\\n  --namespace catops-system \\\n  --reuse-values\n```\n\n**Uninstall:**\n\n```bash\n# Remove CatOps\nhelm uninstall catops -n catops-system\n\n# Delete namespace\nkubectl delete namespace catops-system\n```\n\n---\n\n## Configuration\n\n**Configuration file:** `~/.catops/config.yaml`\n\n**Example:**\n```yaml\n# Cloud Mode (Set automatically via 'catops auth login')\nauth_token: \"your_auth_token\"\nserver_id: \"507f1f77bcf86cd799439011\"\n\n# Monitoring Configuration\ncollection_interval: 30   # Collect metrics every 30 seconds (default)\n```\n\n**Edit configuration:**\n```bash\n# Via CLI command (recommended)\ncatops set interval=30\n\n# Or edit file directly\nnano ~/.catops/config.yaml\n```\n\n### Metrics Collection Interval\n\n**Default:** 30 seconds | **Range:** 10-300 seconds\n\nHow often to collect system metrics (CPU, Memory, Disk).\n\n```bash\ncatops set interval=30    # Default - balanced\ncatops set interval=15    # More frequent - catches brief spikes\ncatops set interval=60    # Less frequent - minimal resource usage\n```\n\n**When to adjust:**\n- **Missing short-lived spikes?** Decrease to 15 seconds\n- **Want minimal overhead?** Increase to 60-120 seconds\n- **Development environment?** Increase to 60 seconds\n\n---\n\n## Log Collection\n\nCatOps automatically collects logs from various sources when in Cloud Mode:\n\n**Supported Sources:**\n- **Docker containers** - Logs from all running containers\n- **Docker Compose** - Service logs with container name detection\n- **Journald** - System logs on Linux (systemd)\n- **Log files** - Common log file locations\n\n**Log Parsing:**\n- Automatic format detection (JSON, logfmt, syslog, common log formats)\n- Uvicorn/Gunicorn access logs\n- Error and warning detection\n- HTTP request parsing (method, path, status, duration)\n- Stack trace extraction\n\n**View logs in web dashboard at [catops.app](https://catops.app)**\n\n---\n\n## Troubleshooting\n\n### Standalone Issues\n\n**CatOps not starting:**\n```bash\n# Check status\ncatops status\n\n# Force cleanup and restart\ncatops force-cleanup\ncatops restart\n\n# Check logs (Linux)\njournalctl -u catops --since \"10 minutes ago\"\n\n# Check logs (macOS)\ntail -f ~/Library/Logs/catops.log\n\n# Or check default log location\ncat /tmp/catops.log\n```\n\n**Telegram alerts not working:**\n```bash\n# Verify Cloud Mode is enabled\ncatops auth info\n\n# Check Telegram is configured on catops.app dashboard\n# Connect your Telegram account in Settings\n\n# Restart daemon\ncatops restart\n```\n\n**Cloud Mode not working:**\n```bash\n# Check authentication\ncatops auth info\n\n# Re-login\ncatops auth logout\ncatops auth login YOUR_NEW_TOKEN\n```\n\n### Kubernetes Issues\n\n**Pods in CrashLoopBackOff:**\n```bash\n# Check logs for errors\nkubectl logs -n catops-system -l app.kubernetes.io/name=catops --tail=100\n\n# Common fix: Install/fix metrics-server\nkubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml\n```\n\n**High resource usage:**\n```bash\n# Check current resource usage\nkubectl top pods -n catops-system\n\n# Disable Prometheus to reduce usage\nhelm upgrade catops oci://ghcr.io/mfhonley/catops/helm-charts/catops \\\n  --namespace catops-system \\\n  --reuse-values \\\n  --set prometheus.enabled=false\n```\n\n---\n\n## Contributing\n\nWe welcome contributions!\n\n**Quick Start:**\n```bash\n# Fork and clone\ngit clone https://github.com/YOUR_USERNAME/catops.git\ncd catops/cli\n\n# Build\ngo build -o catops ./cmd/catops\n\n# Test\n./catops --version\n```\n\n**Areas to contribute:**\n- Bug fixes and improvements\n- Documentation enhancements\n- Platform support (Windows, FreeBSD)\n- Feature requests\n\n---\n\n## Support\n\n**Get Help:**\n- Telegram: [@mfhonley](https://t.me/mfhonley) - Fastest response\n- Email: me@thehonley.org\n- Issues: [GitHub Issues](https://github.com/mfhonley/catops/issues)\n- Discussions: [GitHub Discussions](https://github.com/mfhonley/catops/discussions)\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n**Components:**\n- **CatOps CLI**: Open source (MIT)\n- **Web Dashboard**: [catops.app](https://catops.app)\n- **Backend API**: Cloud infrastructure for metrics storage\n\n---\n\n## Links\n\n- **Website**: [catops.app](https://catops.app)\n- **Documentation**: [GitHub](https://github.com/mfhonley/catops)\n- **Helm Chart**: [ghcr.io/mfhonley/catops/helm-charts/catops](https://github.com/mfhonley/catops/pkgs/container/catops%2Fhelm-charts%2Fcatops)\n\n---\n\n**Built with love by the open source community**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfhonley%2Fcatops","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmfhonley%2Fcatops","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfhonley%2Fcatops/lists"}