家里米家设备攒到几十台之后，我一直想要一件事：能在终端里、在脚本里、在自动化里直接控制它们，而不是每次都掏出手机点开 App。米家官方 App 是给手机点的，不是给脚本用的；上 Home Assistant 又嫌重。于是我写了 mi —— 一个专门用命令行控制米家（Xiaomi Home）设备的工具。
分享几个我自己每天在用、也是我最想做好的点。
一、一行装好，开箱即用
已经发到 PyPI，装一次就有全局 mi 命令：
uv tool install --with zeroconf mi-home-cli
# 或 pipx install "mi-home-cli[mdns]"
然后浏览器登录一次小米账号、同步一下设备清单，就能开始：
mi auth login
mi device sync
mi device list
二、不用记 did，属性能当「积木」拼
传统米家/MIoT 工具最劝退的一点是：控制设备要记一串 did，改属性要背 siid.piid 数字编号。mi 把这些全省了——设备用名字、别名、房间/名称 都能指，属性直接写人话：
mi light 台灯 --ct 4000 --color 暖 # 用人话
mi set 净化器 mode=睡眠 # 枚举值直接写中文
mi on 客厅灯
更关键的是它能当脚本积木：-o json 输出结构稳定、字段是英文原始类型，退出码也分好了类（设备不存在、歧义、值越界、离线……各有各的码），可以直接接管道、写进 shell 判断：
mi -o plain get 台灯 brightness # 只输出 "60"，直接 $(...) 拿来用
mi -o json device list | jq '.[] | select(.online)'
# 当自动化触发器：门锁一开就干点什么
mi watch 门锁 -o json | while read -r line; do
echo "$line" | jq -r 'select(.kind=="event")'
done
实时那条 mi watch 走的是云端 MQTT 长连接，不是傻轮询；支持的设备还能走局域网直连，延迟从 1~2 秒降到几十毫秒。
三、可以直接交给 AI agent
这是我后来越用越喜欢的部分。因为输出是结构化的、错误是分类的、取值范围来自设备自己的 spec，mi 天生适合让大模型来调。仓库里带了一个 Claude Code 的 skill，在项目里跑 AI agent 会自动加载，它会教 agent 怎么定位设备、查能力、按退出码分支处理，以及控制真实设备时该怎么谨慎（匹配到多盏灯要先问、写操作有物理效果、别去反复开关设备验证）。
于是我可以直接跟 agent 说「屋里现在多少度、空气怎么样」，它会自己把净化器、温湿度计挨个读一遍再综合回答；说「有人回家提醒我」，它会挂一个 mi watch 门锁 上去。人念叨一句，剩下的交给它翻译成命令。
四、只用 OAuth2，凭据只留在本地
控制家里的东西，安全我不敢含糊，所以从设计上就划了条硬边界：全程只走 OAuth2。授权在浏览器里完成，mi 只拿到一个有期限、可随时撤销的 token，从头到尾不碰你的账号密码。token 用掉 70% 有效期会自动续期。
所有凭据只存在本机 ~/.config/mi-home-cli/，文件权限 0600，不上传任何第三方服务；设备的局域网 token 等价于控制权，默认在所有输出里打码，只有显式加 --show-secrets 才明文。代价是米家场景/自动化、摄像机录像回放这些需要「账号密码那套身份」的接口用不了——我认为拿这些换「不碰密码」是值得的。
项目在这里，MIT 协议，欢迎试用和提 issue：
https://github.com/slightc/mi_home_cli
（与小米公司无关，协议行为参考官方 Home Assistant 集成独立实现，不含其任何源码。）
