Skip to content

CLI Guide

Jump to bottom
Justin Gu edited this page May 1, 2026 · 1 revision

CLI 使用指南

mijia-control 是一个独立的命令行工具，通过 HTTP 调用 REST API 控制米家设备，不依赖 Flask 运行环境。

安装

pip install -e ".[dev]"

安装后即可直接使用 mijia-control 命令。

也可通过 Flask CLI 调用：flask mijia <command>

跨平台说明

平台 入口路径 使用方式
Windows venv\Scripts\mijia-control.exe 激活 venv 后直接可用
Linux / macOS venv/bin/mijia-control 激活 venv 后直接可用

全局使用（不激活 venv）：

# Linux / macOS
sudo ln -s /path/to/mijia-control/venv/bin/mijia-control /usr/local/bin/mijia-control

# Windows — 将 venv\Scripts 目录添加到系统 PATH

配置

CLI 默认连接 http://127.0.0.1:5000/api，可通过环境变量覆盖：

变量 说明 默认值
MIJIA_API_URL API 服务地址 http://127.0.0.1:5000/api
MIJIA_TOKEN JWT Token（优先级高于本地文件） —

Token 存储位置：~/.config/mijia-control/token.json

命令总览

mijia-control --help                       # 查看所有命令

├── login                                  # 登录
├── logout                                 # 退出登录
├── whoami                                 # 查看当前用户
├── xiaomi                                 # 小米账号管理
│   ├── status                             #   绑定状态
│   └── unlink                             #   解绑
├── device                                 # 设备控制
│   ├── list                               #   列出设备
│   ├── show <did>                         #   设备详情
│   ├── get <did> <prop>                   #   读取属性
│   ├── set <did> <prop> <value>           #   设置属性
│   └── action <did> <action>              #   执行动作
├── scene                                  # 场景管理
│   ├── list                               #   列出场景
│   └── run <scene_id>                     #   执行场景
└── home                                   # 家庭管理
    ├── list                               #   列出家庭
    └── show <home_id>                     #   家庭详情

用户管理

登录

mijia-control login
# 交互式输入用户名和密码（密码隐藏显示）
# 登录成功后 Token 自动保存到 ~/.config/mijia-control/token.json

查看当前用户

mijia-control whoami

退出登录

mijia-control logout
# 清除本地保存的 Token

小米账号

查看绑定状态

mijia-control xiaomi status

解绑

mijia-control xiaomi unlink

小米账号绑定需通过 Web UI 扫码完成，CLI 仅支持查询和解绑。

设备控制

列出设备

mijia-control device list
mijia-control device list --home-id 123456    # 按家庭过滤
mijia-control device list --refresh            # 强制刷新缓存

查看设备详情

mijia-control device show <did>
# 返回设备信息及完整规格（属性列表、动作列表）

读取设备属性

mijia-control device get <did> <prop_name>

# 示例：读取灯的亮度
mijia-control device get 12345 brightness

设置设备属性

mijia-control device set <did> <prop_name> <value>

# 示例
mijia-control device set 12345 power on           # 字符串
mijia-control device set 12345 brightness 80       # 数字
mijia-control device set 12345 power true           # 布尔值
mijia-control device set 12345 color '{"r":255}'   # JSON 对象

CLI 会自动推断值类型：

输入 解析类型
true / false 布尔值
123 整数
12.5 浮点数
{"key": "val"} JSON 对象
其他 字符串

执行设备动作

mijia-control device action <did> <action_name>

# 带参数
mijia-control device action <did> <action_name> --value '{"speed": 2}'

场景管理

列出场景

mijia-control scene list
mijia-control scene list --home-id 123456    # 按家庭过滤
mijia-control scene list --refresh            # 强制刷新

执行场景

mijia-control scene run <scene_id>

家庭管理

列出家庭

mijia-control home list
mijia-control home list --refresh

查看家庭详情

mijia-control home show <home_id>
# 返回家庭信息及该家庭下的设备列表

脚本集成示例

Shell 脚本批量操作

#!/bin/bash
# 批量关闭所有灯

DEVICES=$(mijia-control device list 2>/dev/null)
# 解析 JSON 获取灯设备 did 并逐一关闭
for did in $(echo "$DEVICES" | jq -r '.data[] | select(.model | contains("light")) | .did'); do
    mijia-control device set "$did" power off
done

定时任务（crontab）

# 每天早上 7 点打开客厅灯
0 7 * * * /path/to/mijia-control device set 12345 power on

配合环境变量远程使用

# 连接远程服务器
export MIJIA_API_URL=https://your-server.com/api
export MIJIA_TOKEN=eyJhbGci...
mijia-control device list

故障排除

问题 解决方案
未登录，请先运行 mijia-control login 执行 mijia-control login
连接失败 检查服务是否启动，确认 MIJIA_API_URL 配置
Token 过期 重新执行 mijia-control login
命令未找到 激活 venv 或使用完整路径

下一步：AI Integration — AI Agent 集成指南。

Clone this wiki locally