ikuai-cli

README

ikuai-cli 中文版

iKuai 路由器命令行管理工具 — 在终端轻松管理你的爱快路由器

English | 🇨🇳 中文（默认）

---

🚀 这是什么？

ikuai-cli 是一个开源的命令行工具，让你不用打开浏览器，直接在终端里管理 iKuai 爱快路由器的所有功能：

你能做什么	一行命令搞定
👀 查看路由器状态	ikuai-cli monitor system
🌐 管理 DNS / DHCP	ikuai-cli network dns get
🔒 配置防火墙规则	ikuai-cli security acl list
🛡️ 管理 VPN	ikuai-cli vpn wireguard list
👥 查看在线用户	ikuai-cli users online
📝 查看系统日志	ikuai-cli log system list --human-time

💡 特别增强：本版本内置 AI Agent 技能文档，支持 AI 助手（如 Claude Code）直接操作你的路由器！

---

📦 安装（30 秒搞定）

方法一：一键安装脚本（推荐）

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

脚本会自动下载最新版本到 ~/.local/bin/，无需 sudo 权限。

方法二：Go 安装

如果你有 Go 环境（1.21+）：

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

方法三：从源码编译

git clone https://github.com/ikuaios/ikuai-cli.git
cd ikuai-cli
make build
# 编译产物在当前目录的 ./ikuai-cli

# 安装到 PATH（可选）
sudo mv ikuai-cli /usr/local/bin/
# 或（无需 sudo）：
mkdir -p ~/.local/bin && mv ikuai-cli ~/.local/bin/

# 清理编译临时文件和源码（可选，节省磁盘空间）
cd .. && rm -rf ikuai-cli
# 注意：这会删除整个源码目录，包括编译产物。
#      如果已将 ikuai-cli 移至 PATH 目录后再执行此命令则无影响。

🔧 其他安装方式

预编译二进制文件：

# 从 GitHub Releases 下载（替换 ARCH 为你需要的架构）
VERSION=1.0.3 ARCH=linux_amd64
curl -fsSL "https://github.com/ikuaios/ikuai-cli/releases/download/v${VERSION}/ikuai-cli_${ARCH}.tar.gz" -o ikuai-cli.tar.gz
tar -xzf ikuai-cli.tar.gz
mv ikuai-cli ~/.local/bin/

Windows 用户： 从 Releases 下载 ikuai-cli_windows_amd64.zip。

验证安装

ikuai-cli version
# 输出类似：ikuai-cli v1.0.5 (abc1234)

卸载

如果以后不需要了，删除即可：

# 删除程序（根据你的安装方式选择）
rm ~/.local/bin/ikuai-cli          # 一键脚本 / 手动安装
rm $(go env GOPATH)/bin/ikuai-cli  # go install 方式

# 清除配置文件（可选，会清除保存的 URL 和 Token）
rm -rf ~/.ikuai-cli

# 清除 Shell 补全（可选）
rm -f ~/.local/share/bash-completion/completions/ikuai-cli
rm -f ~/.zsh/completions/_ikuai-cli
rm -f ~/.config/fish/completions/ikuai-cli.fish

💡 只需删除 ikuai-cli 二进制文件即可完成卸载。配置文件和补全脚本按需清理。

升级到最新版

# 方法一：一键脚本（推荐，会自动下载最新 Release）
curl -fsSL https://raw.githubusercontent.com/ikuaios/ikuai-cli/main/scripts/install.sh | sh

# 方法二：Go 安装（自动拉取最新代码）
go install github.com/ikuaios/ikuai-cli/cmd/ikuai-cli@latest

# 验证版本
ikuai-cli version

⚠️ 升级提示：如果当前正在运行 ikuai-cli 的 REPL 模式或长连接进程，请先退出再执行升级。

---

🔑 第一步：获取 Token（必读！）

iKuai 路通过 Token 认证 来保证安全。你需要先在路由器上生成一个 Token：

图文教程

1. 打开浏览器，访问路由器后台（通常是 https://192.168.9.1）
2. 用管理员账号登录
3. 进入 高级设置 → 系统设置 → API Token
4. 点击 新建 Token，输入名称（比如 "CLI"），权限选 全部
5. 复制生成的 Token 字符串（⚠️ 只显示一次，请妥善保存）

详细图文教程见 docs/install.md

---

⚡ 快速开始（三步上手）

Step 1：连接路由器

方式 A：环境变量（推荐给新手，关掉终端就失效）

export IKUAI_CLI_BASE_URL=https://192.168.9.1   # 改成你的路由器地址
export IKUAI_CLI_TOKEN=这里粘贴你的Token          # 粘贴刚才复制的 Token

方式 B：保存配置（推荐长期使用，保存在本地文件中）

ikuai-cli auth set-url https://192.168.9.1        # 设置路由器地址
ikuai-cli auth set-token 这里粘贴你的Token         # 设置 Token

💡 两种方式的区别？

• 方式 A：临时生效，适合一次性操作或写在脚本里
• 方式 B：永久保存到 ~/.ikuai-cli/config.json，下次打开终端直接用
• 如果同时设置了两者，方式 B 的优先级更高

Step 2：验证连接

ikuai-cli auth status

如果看到类似下面的输出就说明连上了 ✅：

┌──────────────────┬──────────────┐
│ Base URL         │ https://192.168.9.1 │
│ Authenticated    │ ✅ Yes            │
│ Uptime           │ 3天12小时          │
│ Version          │ 3.0.8             │
│ WAN IP           │ 1.2.3.4           │
└──────────────────┴──────────────┘

Step 3：开始使用！

# 查看系统状态（CPU、内存、运行时间等）
ikuai-cli monitor system

# 查看所有正在上网的人
ikuai-cli users online

# 查看 DNS 配置
ikuai-cli network dns get

# 查看防火墙规则
ikuai-cli security acl list

🎉 恭喜！你已经成功用命令行控制路由器了！

---

📋 常用命令速查表

我想...	命令
查看系统整体状态	ikuai-cli monitor system
查看谁在上网	ikuai-cli users online
把某个人踢下线	ikuai-cli users kick <IP或MAC>
查看 DNS 配置	ikuai-cli network dns get
查看 DHCP 分配列表	ikuai-cli network dhcp list
查看防火墙规则	ikuai-cli security acl list
查看系统日志	ikuai-cli log system list --human-time
查看 VPN 列表	ikuai-cli vpn pptp list
查看静态路由	ikuai-cli routing static list
进入交互模式（REPL）	ikuai-cli （然后可以 Tab 补全）

输出格式

默认输出漂亮的表格。需要给程序用？加参数切换格式：

ikuai-cli monitor system                # 表格（人看）— 默认
ikuai-cli monitor system --format json  # JSON（程序/AI 用）
ikuai-cli monitor system --format yaml  # YAML（省 token 格式）
ikuai-cli monitor system --raw          # 完整 API 返回值（调试用）
ikuai-cli log system list --human-time  # 日志显示可读时间

---

🤖 AI Agent 增强（本版特色）

这是 ikuai-cli 中文版 的独家功能！

本版本内置了完整的 AI Agent 技能文档，让 AI 助手（Claude Code 等）能够理解并操作你的 iKuai 路由器。

能做什么？

你可以直接用自然语言告诉 AI：

你的话	AI 会做的事
"看看路由器的 CPU 和内存"	调用 ikuai-cli monitor system 并解读结果
"把 MAC 地址 xx:xx:xx 的设备踢下线"	调用 ikuai-cli users kick 执行踢人
"查看今天有哪些人上过网"	调用日志相关命令并汇总
"帮我配一个 PPTP VPN"	引导你完成 PPTP 服务端配置
"备份一下路由器配置"	调用批量操作中的备份流程
"查看防火墙有没有拦截可疑请求"	分析 ACL 规则和日志

安装技能到你的 AI Agent

方法一：Skills CLI（推荐）

npx skills add ikuaios/ikuai-cli -g -y

方法二：手动安装

# 克隆到技能目录
mkdir -p ~/.claude/skills
git clone https://github.com/ikuaios/ikuai-cli.git ~/.claude/skills/ikuai-cli

方法三：WorkBuddy Agent 技能

# 复制技能文件到 WorkBuddy 技能目录
cp -r skills/* ~/.workbuddy/skills/ikuai-cli/

内置技能一览

技能领域	功能覆盖
📊 monitor	CPU、内存、流量、在线客户端、应用协议统计
🌐 network	DNS、DHCP、VLAN、NAT、WAN/LAN、PPPoE
🔒 security	ACL、MAC 过滤、L7 规则、URL/域名过滤
🛡️ vpn	PPTP、L2TP、OpenVPN、IKEv2、IPSec、WireGuard
👥 users	在线用户管理、认证账号、套餐
⚙️ system	主机名、NTP、VRRP、内核参数、定时任务
📝 log	9 种日志类型查看与清除
📦 objects	IP/MAC/端口/域名/时间对象组
🚦 routing	静态路由、分流规则
📶 wireless	Wi-Fi 黑白名单、AC 管理
⚡ qos	IP/MAC 带宽控制
🔧 advanced	FTP/HTTP/Samba/SNMPD 高级服务
🔄 batch	初始化、批量 DHCP、配置备份工作流
🔐 auth	登录认证、PPPoE 认证账号

---

🎮 交互模式（REPL）

不想记命令？进入交互模式，支持多级 Tab 键自动补全：

$ ikuai-cli
ikuai> monitor<TAB>              # 自动补全子命令
ikuai> monitor system            # 执行命令
ikuai> users online --format json  # 加参数也行
ikuai> exit                       # 退出

---

🏗️ 完整功能清单

• 🌐 网络管理 — DNS、DHCP、VLAN、NAT、PPPoE、网口配置
• 📊 系统监控 — CPU、内存、运行时间、流量、在线用户
• 🔒 安全策略 — 防火墙 ACL、MAC 过滤、URL/域名过滤、L7 应用过滤
• 👥 用户管理 — 在线会话、踢下线、认证账号、套餐管理
• 🛣️ 路由配置 — 静态路由、策略路由、分流规则
• 🛡️ VPN — IPSec、PPTP、L2TP、OpenVPN、WireGuard（6 种协议全覆盖）
• 📶 无线管理 — Wi-Fi 黑白名单、VLAN 绑定、AC 管理
• ⚡ QoS — 基于带宽控制的流量整形
• ⚙️ 系统维护 — 主机名、NTP、定时任务、VRRP、SSH 重置、远程访问
• 📝 日志系统 — 系统/DHCP/PPPoE/认证/ARP 等 9 种日志
• 🔄 批量操作 — 一键初始化、批量配置、配置备份

---

🛠️ Shell 补全

安装后可以开启命令补全，提升效率：

# Bash
ikuai-cli completion bash > ~/.local/share/bash-completion/completions/ikuai-cli

# Zsh（macOS 默认）
ikuai-cli completion zsh > ~/.zsh/completions/_ikuai-cli

# Fish
ikuai-cli completion fish > ~/.config/fish/completions/ikuai-cli.fish

# PowerShell
ikuai-cli completion powershell > ikuai-cli.ps1

---

💡 使用技巧

1. 写脚本时用环境变量

把下面两行放在脚本开头就行：

#!/bin/bash
export IKUAI_CLI_BASE_URL=https://192.168.9.1
export IKUAI_CLI_TOKEN=你的Token
ikuai-cli monitor system --format json

2. 用 JSON 输出配合 jq 处理数据

# 只提取在线用户的 IP 和用户名
ikuai-cli users online --format json | jq '.[] | {ip, username}'

# 提取 CPU 使用率
ikuai-cli monitor system --format json | jq '.cpu_usage'

3. 安全预览模式

不确定命令会不会改坏东西？先加上 --dry-run 预览一下：

ikuai-cli network dhcp create --name Test --dry-run
# 会显示要执行的操作但不会真的执行

---

📖 更多文档

文档	说明
完整命令参考	所有命令和参数的详细说明
安装指南	各种安装方式的详细步骤
输出格式说明	表格/JSON/YAML/raw 各格式详解
兼容性说明	支持的 iKuai 版本和限制
开发指南	参与贡献的指南
SKILL.md	AI Agent 技能主入口

---

🤝 社区

• 🐛 Bug 反馈 — 遇到问题？来这里提
• 💡 功能建议 — 想要新功能？告诉我们
• 🔒 安全漏洞报告 — 发现安全问题？请按此流程报告

---

📄 许可证

本项目基于 MIT 开源协议发布。原始项目来自 ikuaidev/ikuai-cli，感谢原作者的贡献。

本中文版由 ikuaios 维护，增加 AI Agent 增强功能和完整中文文档。