{"id":37231574,"url":"https://github.com/nachtschatt3n/unifictl","last_synced_at":"2026-01-15T03:44:47.805Z","repository":{"id":332327146,"uuid":"1111434933","full_name":"nachtschatt3n/unifictl","owner":"nachtschatt3n","description":"🤖 AI-powered CLI for UniFi networks - Built with Rust | LLM-optimized output | Smart correlation \u0026 diagnostics | Time-series analytics | kubectl-like UX","archived":false,"fork":false,"pushed_at":"2025-12-08T01:19:18.000Z","size":323,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-13T13:48:16.190Z","etag":null,"topics":["ai","api-client","automation","cli","devops","llm","network-management","networking","rust","ubiquiti","unifi"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nachtschatt3n.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-06T23:32:20.000Z","updated_at":"2025-12-08T01:19:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nachtschatt3n/unifictl","commit_stats":null,"previous_names":["nachtschatt3n/unifictl"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/nachtschatt3n/unifictl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nachtschatt3n%2Funifictl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nachtschatt3n%2Funifictl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nachtschatt3n%2Funifictl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nachtschatt3n%2Funifictl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nachtschatt3n","download_url":"https://codeload.github.com/nachtschatt3n/unifictl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nachtschatt3n%2Funifictl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28442335,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"online","status_checked_at":"2026-01-15T02:00:08.019Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai","api-client","automation","cli","devops","llm","network-management","networking","rust","ubiquiti","unifi"],"created_at":"2026-01-15T03:44:47.074Z","updated_at":"2026-01-15T03:44:47.796Z","avatar_url":"https://github.com/nachtschatt3n.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# unifictl\n\n\u003cdiv align=\"center\"\u003e\n\n[![License](https://img.shields.io/badge/license-GPL--3.0-blue.svg)](LICENSE)\n[![Rust](https://img.shields.io/badge/rust-1.70+-orange.svg)](https://www.rust-lang.org/)\n[![Version](https://img.shields.io/badge/version-0.5.0-green.svg)](https://github.com/nachtschatt3n/unifictl)\n[![Tests](https://img.shields.io/badge/tests-75%20passing-success.svg)](#testing)\n\n**A powerful CLI tool for UniFi networks with AI-first design**\n\n[Features](#features) •\n[Installation](#installation) •\n[Quick Start](#quick-start) •\n[AI Guide](AI_AGENT_GUIDE.md) •\n[Examples](EXAMPLES.md)\n\n\u003c/div\u003e\n\n---\n\n## Overview\n\n`unifictl` is a comprehensive command-line interface for managing UniFi networks through both the **UniFi Site Manager API** (cloud) and **local UniFi controllers**. Built with Rust for performance and reliability, it provides human-friendly commands while offering AI-optimized output for automated network management.\n\n### What makes unifictl special?\n\n- 🤖 **AI-First Design**: LLM-optimized output with token estimation, smart truncation, and JSON schemas\n- 🔄 **Correlation Commands**: Aggregate related network data in single API calls\n- 🏥 **Diagnostic Mode**: Multi-endpoint health checks with actionable recommendations\n- 📊 **Time-Series Export**: Historical data for trend analysis and pattern detection\n- 🎯 **kubectl-like UX**: Intuitive command structure with consistent patterns\n- ⚡ **Performance**: Native binary with minimal overhead, fast execution\n- 🛡️ **Safety Features**: Dry-run mode, interactive confirmations, context-aware errors\n\n## Features\n\n### 🤖 AI-Powered Network Management\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n**LLM-Optimized Output** (`-o llm`)\n- Token counting (~4 chars/token)\n- Intelligent truncation (\u003e4000 tokens)\n- JSON schema metadata\n- Field importance levels\n- Statistical summaries\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n**Correlation Commands**\n- Aggregate client + AP + events\n- Device + connected clients\n- Reduce API calls by 80%\n- Single-command troubleshooting\n- Cross-reference network data\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n**Diagnostic Mode**\n- Network health checks\n- WiFi performance analysis\n- Client troubleshooting\n- Pass/fail with recommendations\n- Multi-endpoint validation\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n**Time-Series Export**\n- Traffic statistics (CSV/JSON)\n- WiFi metrics over time\n- Event log export\n- Trend analysis ready\n- Bandwidth planning data\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### 🛠️ Core Features\n\n#### Output Formats \u0026 Filtering\n- **Pretty** (default): Human-readable tables with auto-column selection\n- **JSON**: Structured output for scripting and automation\n- **CSV**: Spreadsheet-ready exports for reporting\n- **Raw**: Exact API responses\n- **LLM**: AI-optimized with metadata and schemas\n\nAdvanced filtering with `--filter`, `--filter-regex`, `--sort-by`, `--columns`, and `--full-ids`\n\n#### Network Operations\n\n**Cloud (Site Manager API)**\n- Host and site management\n- Device inventory across sites\n- ISP metrics and analytics (EA)\n- SD-WAN configuration (EA)\n\n**Local Controller**\n- Device management (adopt, restart, upgrade)\n- Client operations (block, reconnect, metadata)\n- Network configuration (VLANs, WLANs, firewall)\n- WiFi analytics (connectivity, stats, radio AI)\n- Traffic analysis (flows, DPI, routes)\n- Event monitoring and logging\n- Health and security status\n\n#### Safety \u0026 Reliability\n- 🔒 **Dry-run mode**: Preview deletions without executing\n- ✋ **Interactive confirmations**: Prompts before destructive operations\n- 📝 **Context-aware errors**: Detailed troubleshooting guidance\n- 🔄 **Watch mode**: Live refresh with timestamps\n- 🎯 **Smart defaults**: Sensible configuration precedence\n\n## Installation\n\n### From Source\n\n```bash\ngit clone https://github.com/nachtschatt3n/unifictl.git\ncd unifictl\ncargo build --release\nsudo cp target/release/unifictl /usr/local/bin/\n```\n\n### Package Managers\n\n**Debian/Ubuntu**\n```bash\ncargo install cargo-deb\ncargo deb\nsudo dpkg -i target/debian/unifictl_*.deb\n```\n\n**Arch Linux**\n```bash\ncd packaging/arch\nmakepkg -si\n```\n\n## Quick Start\n\n### 1. Configure Cloud API\n\n```bash\nunifictl configure --key \"YOUR_API_KEY\"\nunifictl host list\n```\n\n### 2. Configure Local Controller\n\n```bash\nunifictl local configure \\\n  --url https://192.168.1.1:8443 \\\n  --username admin \\\n  --password 'your-password' \\\n  --site default \\\n  --scope local\n```\n\n### 3. Basic Commands\n\n```bash\n# List devices\nunifictl local device list\n\n# Get client details with AI optimization\nunifictl local client list -o llm\n\n# Troubleshoot a client\nunifictl local correlate client aa:bb:cc:dd:ee:ff --include-events\n\n# Run network diagnostics\nunifictl local diagnose network\n\n# Export traffic data\nunifictl local time-series traffic \\\n  --start 1765000000000 \\\n  --end 1765100000000 \\\n  --format csv \u003e traffic.csv\n```\n\n## Common Use Cases\n\n### 🔍 Troubleshoot Client Connectivity\n\n```bash\n# Get everything about a client in one command\nunifictl local correlate client \u003cMAC\u003e --include-events -o llm\n\n# Returns: client info + connected AP + recent events + AI summary\n```\n\n### 📊 Network Health Check\n\n```bash\n# Quick health assessment\nunifictl local diagnose network -o llm\n\n# WiFi performance check\nunifictl local diagnose wifi\n\n# VPN health with packet loss reasons\nunifictl local vpn get -o json\n```\n\n### 📈 Bandwidth Analysis\n\n```bash\n# Export last 24 hours of traffic\nSTART=$(python3 -c \"import time; print(int((time.time() - 86400) * 1000))\")\nEND=$(python3 -c \"import time; print(int(time.time() * 1000))\")\n\nunifictl local time-series traffic --start $START --end $END --format csv\n```\n\n### 🔧 Device Management\n\n```bash\n# List unadopted devices\nunifictl local device list --unadopted\n\n# Adopt all pending devices\nunifictl local device adopt-all\n\n# Restart a device\nunifictl local device restart \u003cMAC\u003e\n```\n\n### 🎨 Custom Output\n\n```bash\n# Live monitoring\nunifictl local client list --watch 5\n\n# Filtered export\nunifictl local device list \\\n  --filter \"AP\" \\\n  --columns name,ip,model,version \\\n  --sort-by name \\\n  -o csv \u003e aps.csv\n\n# Regex filtering\nunifictl local device list --filter-regex \"^U(AP|SW)-.*\"\n```\n\n## AI Agent Integration\n\nFor AI-powered network management, see the comprehensive [AI Agent Guide](AI_AGENT_GUIDE.md).\n\n**Quick Example:**\n```python\nimport subprocess\nimport json\n\n# Get LLM-optimized device data\nresult = subprocess.run(\n    [\"unifictl\", \"local\", \"device\", \"list\", \"-o\", \"llm\"],\n    capture_output=True, text=True\n)\n\ndata = json.loads(result.stdout)\nprint(f\"Found {data['llm_metadata']['item_count']} devices\")\nprint(f\"Estimated tokens: {data['llm_metadata']['estimated_tokens']}\")\nprint(f\"Token efficient: {data['llm_metadata']['ai_guidance']['token_efficient']}\")\n```\n\n## Command Reference\n\n### Cloud API (Site Manager)\n\n```bash\n# Hosts\nunifictl host list\nunifictl host get \u003cHOST_ID\u003e\n\n# Sites and devices\nunifictl site list [--host-id \u003cHOST_ID\u003e]\nunifictl device list [--host-id \u003cHOST_ID\u003e] [--site-id \u003cSITE_ID\u003e]\nunifictl device get \u003cDEVICE_ID\u003e\n\n# ISP metrics and SD-WAN (EA)\nunifictl isp get --type 5m --site-id \u003cSITE_ID\u003e --start \u003cRFC3339\u003e --end \u003cRFC3339\u003e\nunifictl sdwan list\nunifictl sdwan get \u003cCONFIG_ID\u003e\n```\n\n### Local Controller\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDevice Operations\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nunifictl local device list [--unadopted] [--limit N]\nunifictl local device get \u003cMAC\u003e [--ports] [--config]\nunifictl local device restart \u003cMAC\u003e\nunifictl local device adopt \u003cMAC\u003e\nunifictl local device adopt-all\nunifictl local device upgrade \u003cMAC\u003e\nunifictl local device spectrum-scan \u003cMAC\u003e\nunifictl local device port-anomalies\nunifictl local device mac-tables [--device \u003cMAC\u003e]\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClient Operations\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nunifictl local client list [--wired|--wireless|--blocked] [--limit N]\nunifictl local client block \u003cMAC\u003e\nunifictl local client unblock \u003cMAC\u003e\nunifictl local client reconnect \u003cMAC\u003e\nunifictl local client active [--limit N]\nunifictl local client history [--limit N]\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAI-Powered Commands\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Correlation\nunifictl local correlate client \u003cMAC\u003e [--include-events]\nunifictl local correlate device \u003cMAC\u003e [--include-clients]\nunifictl local correlate ap \u003cAP_MAC\u003e\n\n# Diagnostics\nunifictl local diagnose network\nunifictl local diagnose wifi\nunifictl local diagnose client [\u003cMAC\u003e]\n\n# Time-Series\nunifictl local time-series traffic --start \u003cTS\u003e --end \u003cTS\u003e [--format csv|json]\nunifictl local time-series wifi --start \u003cTS\u003e --end \u003cTS\u003e [--format csv|json]\nunifictl local time-series events [--limit N] [--format csv|json]\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWiFi Operations\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nunifictl local wifi connectivity\nunifictl local wifi stats --start \u003cTS\u003e --end \u003cTS\u003e [--ap-mac \u003cMAC|all\u003e] [--radios]\nunifictl local wifi radio-ai\nunifictl local wifi management\nunifictl local wifi config\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eTraffic \u0026 Analytics\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nunifictl local traffic stats --start \u003cTS\u003e --end \u003cTS\u003e --include-unidentified \u003ctrue|false\u003e\nunifictl local traffic flow-latest --period \u003cday|month\u003e --top \u003cN\u003e\nunifictl local traffic app-rate --start \u003cTS\u003e --end \u003cTS\u003e\nunifictl local traffic filter-data\nunifictl local traffic routes\nunifictl local traffic rules\nunifictl local traffic flows [--query \u003cJSON\u003e]\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eNetwork Configuration\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nunifictl local network list|create|update|delete\nunifictl local wlan list|create|update|delete\nunifictl local firewall-rule list|create|update|delete\nunifictl local firewall-group list|create|update|delete\nunifictl local policy-table list|create|update|delete\nunifictl local zone list|create|update|delete\nunifictl local object list|create|update|delete\nunifictl local port-profile list\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMonitoring\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nunifictl local health get\nunifictl local security get\nunifictl local wan get\nunifictl local dpi get\nunifictl local event list [--limit N]\nunifictl local log critical|all|count|device-alert\nunifictl local top-client list [--limit N]\nunifictl local top-device list [--limit N]\n```\n\u003c/details\u003e\n\n## Testing\n\n```bash\n# Run unit tests\ncargo test\n\n# Run full endpoint test suite\nbash test_all_endpoints.sh\n\n# Test specific functionality\ncargo test --test integration_test\n```\n\nCurrent test coverage: **75 endpoints, 100% passing**\n\n## Configuration\n\n**Precedence order**: CLI flag → Local config (`.unifictl.yaml`) → User config (`~/.config/unifictl/config.yaml`)\n\n### Cloud API\n```bash\nunifictl configure --key \"YOUR_API_KEY\" [--scope local|user]\nunifictl config-show  # View current config (passwords masked)\n```\n\n### Local Controller\n```bash\nunifictl local configure \\\n  --url https://192.168.1.1:8443 \\\n  --username admin \\\n  --password 'password' \\\n  --site default \\\n  [--verify-tls] \\\n  [--scope local]\n```\n\n**Note**: TLS verification is disabled by default for self-signed certificates. Use `--verify-tls` if your controller has a valid certificate.\n\n## Troubleshooting\n\n### UDM Rate Limiting\n\nUniFi Dream Machines may hit login rate limits with CLI tools that create new sessions per command.\n\n**Symptoms**: Repeated 401 errors, intermittent authentication failures\n\n**Solution**:\n```bash\n# SSH into your UDM\nvi /usr/lib/ulp-go/config.props\n\n# Find and increase this value\nsuccess.login.limit.count=100  # Default is 5-10\n\n# Restart UniFi OS\nsystemctl restart unifi-os\n```\n\n### Common Issues\n\n**Port 8443 connectivity**: The tool automatically preserves port `:8443` for local controllers\n\n**Certificate errors**: Use the default (no `--verify-tls`) for self-signed certs\n\n**Site parameter**: Commands default to configured site; override with `--site \u003cNAME\u003e`\n\n## Development\n\nSee [AGENTS.md](AGENTS.md) for development guidelines, testing requirements, and contribution workflow.\n\n**Quick development setup**:\n```bash\ncargo build\ncargo test\ncargo clippy\ncargo fmt\n```\n\n## Documentation\n\n- **[README.md](README.md)** - This file (overview and reference)\n- **[AI_AGENT_GUIDE.md](AI_AGENT_GUIDE.md)** - Comprehensive AI agent integration guide\n- **[EXAMPLES.md](EXAMPLES.md)** - Real-world usage examples\n- **[AGENTS.md](AGENTS.md)** - Development and contribution guide\n\n## License\n\nGPL-3.0 - see [LICENSE](LICENSE) file for details\n\n## Credits\n\nBuilt by [Mathias Uhl](https://github.com/nachtschatt3n)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[⬆ Back to Top](#unifictl)**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnachtschatt3n%2Funifictl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnachtschatt3n%2Funifictl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnachtschatt3n%2Funifictl/lists"}