---
name: ikuai-cli
description: |
  iKuai 路由器管理 CLI 工具（中文增强版） — 通过命令行管理爱快路由器的网络、用户、VPN、防火墙等功能。
  内置 AI Agent 技能文档，支持 Claude Code / WorkBuddy 等 AI 助手直接操作路由器。
  适用于：查看路由器状态、配置网络/DNS/DHCP/VPN/防火墙、
  管理用户、查看日志，或自动化任何 iKuai 路由器操作。
---

# iKuai CLI 中文版 — AI Agent 技能

通过本地 v4.0 HTTP API 管理 iKuai 路由器的 Go CLI 工具。本版本为中文增强版，内置完整 AI Agent 技能文档。

## 使用场景

- **📊 路由器状态监控** — CPU、内存、运行时间、流量统计
- **🌐 网络配置** — DNS、DHCP、VLAN、NAT、PPPoE、VPN
- **👥 用户管理** — 在线会话、踢出用户、认证账号
- **🔒 安全防护** — ACL、MAC 过滤、URL 过滤、域名黑名单
- **⚙️ 系统管理** — 日志查看、计划任务、远程访问、VRRP
- **🤖 AI Agent 集成** — 让 AI 助手直接操控路由器

## 前置条件

```bash
# 方式一：持久化会话（推荐长期使用）
ikuai-cli auth set-url https://192.168.9.1
ikuai-cli auth set-token <TOKEN>

# 方式二：环境变量（适用于脚本和 Agent，不写入磁盘）
export IKUAI_CLI_BASE_URL=https://192.168.9.1
export IKUAI_CLI_TOKEN=<TOKEN>

# 验证连接
ikuai-cli auth status --format json
```

> **优先级**：Session 文件 > 环境变量 > 无

## 输出模式

| 标志 | 模式 | 用途 |
|------|------|------|
| (默认) | table (TTY) / JSON (管道) | 人读 / 脚本自动检测 |
| `--format json` | 紧凑 JSON | Agent 解析、管道到 jq |
| `--format yaml` | YAML | LLM token 高效模式 |
| `--raw` | 完整 API 信封 | 调试 |
| `--human-time` | 时间戳转本地时间 | 日志阅读 |
| `--dry-run` | 预览不执行 | 安全检查 |

## 命令格式

```
ikuai-cli <资源> <操作> [参数] [标志]
```

- **读取**：`ikuai-cli monitor system --format json`
- **列表**：`ikuai-cli network dhcp list --page 1 --page-size 50`
- **写入**：`ikuai-cli network dhcp create --name "Office" --interface lan1 --addr-pool "192.168.9.100-200"`
- **写入（逃逸舱）**：`ikuai-cli network dns set --data '{"key":"value"}'`
- **REPL**：`ikuai-cli` （交互式 Shell，支持 Tab 补全）

## 子领域技能

| 技能 | 文件 | 功能范围 |
|------|------|----------|
| [Monitor](skills/monitor.md) | `skills/monitor.md` | CPU、内存、流量、客户端监控 |
| [Network](skills/network.md) | `skills/network.md` | DNS、DHCP、VLAN、NAT、WAN/LAN、PPPoE |
| [Security](skills/security.md) | `skills/security.md` | ACL、MAC、L7、URL、域名黑名单、连接限制 |
| [VPN](skills/vpn.md) | `skills/vpn.md` | PPTP、L2TP、OpenVPN、IKEv2、IPSec、WireGuard |
| [Users](skills/users.md) | `skills/users.md` | 在线用户、账号、套餐管理 |
| [System](skills/system.md) | `skills/system.md` | 配置、计划任务、远程访问、VRRP、内核参数 |
| [Auth](skills/auth.md) | `skills/auth.md` | 登录、PPPoE 认证账号 |
| [Log](skills/log.md) | `skills/log.md` | 系统/DHCP/PPPoE/认证/ARP 日志 |
| [Objects](skills/objects.md) | `skills/objects.md` | IP/MAC/端口/域名/时间对象组 |
| [QoS](skills/qos.md) | `skills/qos.md` | IP/MAC 带宽控制 |
| [Routing](skills/routing.md) | `skills/routing.md` | 静态路由、分流规则 |
| [Wireless](skills/wireless.md) | `skills/wireless.md` | 黑白名单、VLAN、AC 管理 |
| [Advanced](skills/advanced.md) | `skills/advanced.md` | FTP、HTTP、Samba、SNMPD 服务 |
| [Batch](skills/batch.md) | `skills/batch.md` | 多命令工作流 |

## 错误处理

| 错误码 | 含义 | 解决方案 |
|--------|------|----------|
| 3007 | Token 无效或过期 | `auth set-token <TOKEN>` |
| 1008 | 会话过期 | `auth set-token <TOKEN>` |
| 10014 | 权限不足 | 检查用户权限 |

## 安装方法

### macOS / Linux（一键脚本，推荐）

```bash
curl -fsSL https://raw.githubusercontent.com/ikuaios/ikuai-cli/main/scripts/install.sh | sh
```

### Go install

```bash
go install github.com/ikuaios/ikuai-cli/cmd/ikuai-cli@latest
```

### 从源码编译

```bash
git clone https://github.com/ikuaios/ikuai-cli.git
cd ikuai-cli
make build
```

## Shell 补全

```bash
ikuai-cli completion bash > ~/.local/share/bash-completion/completions/ikuai-cli
ikuai-cli completion zsh  > ~/.zsh/completions/_ikuai-cli
ikuai-cli completion fish > ~/.config/fish/completions/ikuai-cli.fish
```

## 项目信息

- **GitHub**: https://github.com/ikuaios/ikuai-cli
- **语言**: Go
- **许可证**: MIT
- **版本**: 中文增强版