toolkit-cli

日常效率 CLI 工具集，所有命令支持 --json 结构化输出，方便 AI Agent 通过命令行调用。

安装

npm install -g @jason.bourne/toolkit-cli

要求 Node.js >= 20。

命令

ip — 查询本机外网 IP 及归属地

toolkit-cli ip                # 输出 IP 及归属地，如：1.2.3.4 中国 上海 中国电信
toolkit-cli ip --no-geo       # 只输出 IP：1.2.3.4
toolkit-cli ip --ipv6         # 查询 IPv6 地址
toolkit-cli ip --check-proxy  # 末尾标注代理使用情况，如：1.2.3.4 中国 上海 中国电信 (直连)
toolkit-cli ip --json         # {"ip":"1.2.3.4","version":4,"source":"ipify","geo":{"country":"中国","region":"上海","city":"上海","isp":"中国电信","source":"ip-api"}}

IP 查询依次尝试 ipify、ip.sb、icanhazip，单个服务超时 5 秒自动切换，全部失败时退出码为 1。 归属地依次尝试 ip-api.com（中文）、ipwho.is（英文），查询失败时自动降级为只输出 IP（不报错）；JSON 模式下归属地失败或 --no-geo 时省略 geo 字段。

port — 查询或关闭指定端口

toolkit-cli port show 8080                    # 展示 TCP/UDP 监听应用
toolkit-cli port show 8080 --protocol tcp     # 仅查询 TCP
toolkit-cli port show 8080 --json             # 结构化输出
toolkit-cli port kill 8080                    # 正常终止所有监听进程
toolkit-cli port kill 8080 --force            # 强制终止
toolkit-cli port kill 8080 --protocol udp --json

查询结果包含协议、监听地址、端口、PID、进程名及可获取的可执行路径。同一 PID 只终止一次；正常终止后仍被占用时命令失败并提示使用 --force，不会自动升级为强制终止。端口未被占用时 show 与 kill 都返回成功，便于脚本重复调用。

支持 Windows、Linux 和 macOS。Windows 使用 PowerShell 网络命令；Linux 需要 ss（通常由 iproute2 提供）；macOS 需要 lsof。查看其他用户或终止受保护进程可能需要管理员/root 权限，工具不会自动提权。UDP 结果表示绑定该本地端口的端点。

代理

所有命令的网络请求默认尊重 HTTP_PROXY / HTTPS_PROXY / NO_PROXY 环境变量（含小写变体，同名大小写并存时小写优先），行为与 curl/git 一致。

toolkit-cli ip --proxy http://127.0.0.1:7890  # 强制走指定代理（优先于环境变量）
toolkit-cli ip --no-proxy                     # 强制直连，忽略代理环境变量
toolkit-cli ip --check-proxy --json           # JSON 增加 proxy 字段：{"used":true,"url":"http://127.0.0.1:7890","source":"HTTPS_PROXY"}

已知边界：仅支持 http/https 代理（不支持 SOCKS）；--check-proxy 标注基于代理配置推断 IP 主查询（HTTPS）的链路，若 NO_PROXY 排除了 IP 查询服务域名，或 HTTP/HTTPS 代理配置不同导致归属地请求走不同链路，标注可能与个别请求的实际链路不一致。

AI Agent 调用约定

• stdout 只输出结果数据；错误与提示输出到 stderr
• 成功退出码 0，失败退出码 1
• 加 --json 后 stdout 保证可被直接 JSON.parse；失败时 stderr 为 {"error":"..."}

License

MIT