ikuai-cli

A CLI for iKuai routers — manage network, users, VPN, firewall and more from the terminal.

中文文档

Installation

macOS / Linux:

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

Go install:

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

How to Get a Token from the Router

Quick Start

1. Authenticate

Option A: Environment variables (recommended for scripts & agents)

export IKUAI_CLI_BASE_URL=https://192.168.1.1
export IKUAI_CLI_TOKEN=
ikuai-cli monitor system   # works immediately

Option B: Persistent session (saved to ~/.ikuai-cli/config.json)

ikuai-cli auth set-url https://192.168.1.1
ikuai-cli auth set-token 

2. Verify

ikuai-cli auth status

3. Explore

ikuai-cli monitor system                     # CPU, memory, uptime, WAN IP
ikuai-cli network dns get                    # DNS config
ikuai-cli network dns proxy create --domain example.com --dns-addr 8.8.8.8 --parse-type ipv4
ikuai-cli network pppoe set --comment maintenance --mtu 1480 --mru 1480
ikuai-cli users online                       # Online users
ikuai-cli users online get 1                 # Online user detail
ikuai-cli security acl list                  # Security rules
ikuai-cli log system list --human-time       # System logs

Full command reference: docs/cli-reference.md

Features

• Network — DNS, DHCP, VLAN, NAT, PPPoE, interfaces
• Monitor — CPU, memory, uptime, traffic, online clients
• Security — ACL, MAC filtering, L7 rules, URL filtering, domain blacklist, peerconn, terminals
• Users — auth accounts, online sessions, kick, auth packages, bandwidth limits
• Routing — static routes, policy routing, multi-WAN
• VPN — PPTP, L2TP, OpenVPN, IKEv2, IPSec, WireGuard
• Objects — IP, IPv6, MAC, port, protocol, domain, time object groups
• Wireless — Wi-Fi configuration and management
• QoS — bandwidth control and traffic shaping
• System — config, schedules, remote access, VRRP, backup, upgrade, web admin
• Log — system logs and audit trails
• Interactive shell — repl mode with multi-level tab completion
• Structured output — table by default; --format json/yaml or --raw for machines; --human-time for timestamps; --wide / --columns for column control
• Consistent pagination — collection commands use --page / --page-size while adapting to each API’s query contract

Output

Default output is a human-readable table. When stdout is not a TTY (piped or redirected), output automatically switches to JSON.

List commands show a curated set of default columns in table mode. Use --wide to see all fields, or --columns to pick specific ones. Columns auto-fit to your terminal width.

ikuai-cli monitor system                     # Table (human)
ikuai-cli monitor system --format json       # JSON (scripts, jq, agents)
ikuai-cli monitor system --format yaml       # YAML
ikuai-cli monitor system --raw               # Full API envelope (debug)
ikuai-cli log system list --human-time       # Human-readable timestamps
ikuai-cli security acl list --wide           # Show all columns
ikuai-cli security acl list --columns id,src_addr,action  # Custom columns

--raw and --format are mutually exclusive. --wide and --columns are mutually exclusive.

Session Storage

Credentials are saved to ~/.ikuai-cli/config.json. Override with:

export IKUAI_CLI_CONFIG_FILE=/path/to/config.json

Priority: session file > environment variables > none.

Environment variables (IKUAI_CLI_BASE_URL / IKUAI_CLI_TOKEN) are never written to disk.

Use with AI Agents

ikuai-cli ships with a SKILL.md and domain-specific skills that teach AI agents how to manage iKuai routers.

Install Skills

Skills CLI (Recommended):

npx skills add ikuaidev/ikuai-cli

Manual:

mkdir -p .agents/skills
git clone https://github.com/ikuaidev/ikuai-cli.git .agents/skills/ikuai-cli

Agent Output

Use --format json for structured output:

ikuai-cli monitor system --format json
ikuai-cli users online --format json | jq '.data[] | {id, ip_addr, mac, username}'

Use --format yaml for token-efficient output when full JSON fidelity is not required.

Development

git clone https://github.com/ikuaidev/ikuai-cli.git
cd ikuai-cli
make test       # run all tests (with race detector)
make lint       # golangci-lint
make build      # build binary
make smoke      # smoke test

Cross-compile:

make linux-amd64    make linux-arm64    make linux-armv7
make darwin-amd64   make darwin-arm64

Community

• Issues — bug reports and feature requests
• Contributing — how to contribute
• Security — how to report vulnerabilities
• Code of Conduct

License

MIT — see LICENSE