最近，CLI（命令行工具）正在成为AI Agent时代的基础设施。
飞书、企业微信、钉钉等多家主流办公协作平台，相继开源了各自的CLI工具，将消息、文档、日程等产品能力封装为命令行接口，供开发者和AI Agent直接调用。
背后的逻辑很明确：命令行是AI编程Agent最成熟的交互方式，Agent天生适合执行结构化的CLI指令。
办公场景的CLI化已经走在前面。但对AI+IoT开发者来说，一个问题随之浮现：消息可以CLI了，文档可以CLI了，日程可以CLI了——设备控制呢？
查看设备在线状态、调整空调温度、批量关闭某个房间的灯光、查询用电数据——这些日常开发中的高频操作，以往只能通过编写代码调用API，或者打开手机App手动完成。
今天，涂鸦正式开源tuya-smart-control-cli，为AI+IoT开发者提供了一套完整的设备管理命令行工具。
一、Enduser API与CLI是什么关系？
在介绍CLI之前，有必要先厘清两个概念。
Tuya Enduser API是涂鸦开放给开发者的官方接口，用于获取设备列表、控制设备、查询数据、发送通知等。能力完整，覆盖3000+设备品类、200+国家和地区。使用API需要编写代码、处理签名逻辑、管理Token生命周期、构造HTTP请求，适合二次开发和系统集成。
tuya-smart-control-cli是基于上述Enduser API封装的命令行工具。底层调用的是同一套API能力，但开发者无需编写完整代码，在终端输入命令即可完成设备查询、控制、通知等操作。CLI内置了鉴权流程和参数格式化，适合快速调试、批量操作和轻量级脚本编排。
需要特别说明：API Key等凭证仍然必须配置。CLI不会内置密钥，也不支持免密使用。CLI省去的是编写代码、处理签名和构造请求的步骤，身份验证和权限管理与直接调用API完全一致。
简而言之：API是底层能力，CLI是基于这套API打造的开箱即用的命令行工具。
二、AI+IoT开发者为什么需要CLI？
01
设备调试效率大幅提升
开发者在硬件联调阶段需要频繁查看设备状态、测试指令下发。以往的流程是：编写脚本→引入SDK →处理签名→发起请求→解析返回，一轮调试往往需要十几分钟。
使用CLI后，一条命令即可完成：
tuyadevice detail0620068884f3eb414579
几秒内即可看到设备当前的属性状态——开关状态、亮度值、工作模式等。切换到下一台设备，只需更改device_id重新执行。
02
批量操作无需开发管理后台
方案商在酒店、公寓、办公楼等场景下，往往需要同时管理大量设备。CLI配合Shell脚本，可以实现轻量化的批量运维：
# 查询某个房间下的所有设备tuya device list --room 333
# 批量关闭房间内所有灯光tuya device list --room 333 --json | jq -r'.[].device_id'|\ whilereadid;do tuya device control"$id"'{"switch_led":false}' done
无需单独开发管理系统，一个Shell脚本配合cron定时任务即可满足基础运维需求。
03
为AI Agent提供设备操作入口
当前各类AI Agent的核心交互方式就是执行Shell命令。当涂鸦的设备控制能力被封装为CLI后，AI Agent便可以在终端中直接操控智能设备——与它调用git、docker等工具的方式完全一致。
04
支持JSON输出，便于数据处理与集成
所有查询命令均支持--json参数，输出结构化JSON数据，方便与jq等工具配合使用，或作为管道数据传递给其他程序：
# 导出设备列表tuyadevice list --json > devices.json
# 提取所有设备IDtuya device list --json | jq'.[].device_id'
# 筛选在线设备tuya device list --json | jq'[.[] | select(.online==true)]'
三、5分钟完成安装与配置
环境要求
Node.js >= 18
涂鸦API Key（中国区：tuyasmart.com｜ 海外区：tuya.ai）
安装
gitclonehttps://github.com/tuya/tuya-smart-control-cli.gitcdtuya-smart-control-clinpm installnpmlink
执行npm link后，tuya命令将在全局可用。
配置
# 交互式配置（推荐）tuya init
# 或通过环境变量配置exportTUYA_API_KEY="sk-AYxxxxxxxxxxxx"
运行tuya init会引导开发者输入API Key。CLI根据Key前缀自动识别所属区域并匹配对应的服务端地址，全球7个数据中心无需手动配置：
验证连通性
tuyadoctor
该命令会依次检查配置文件、API Key有效性、网络连通性以及账号下的家庭数据：
Tuya CLI Doctor─────────────── Configfile: /Users/you/.tuya-cli/config.json API Key: sk-AY****xxxx (fromconfigfile) Base URL: https://openapi.tuyacn.com (China) API connection: OK (2home(s) found)
全部显示即表示配置完成。
四、完整命令参考
▍设备管理（核心功能）
# 列出所有设备tuyadevice list
# 按家庭或房间筛选tuyadevice list --home tuyadevice list --room
# 查看设备详情（含当前属性状态）tuyadevice detail
# 查看设备物模型（了解设备支持的操作能力）tuyadevice model
# 控制设备——单属性tuyadevice control '{"switch_led":true}'
# 控制设备——多属性同时设置tuyadevice control '{"switch_led":true,"bright_value":800}'
# 重命名设备tuyadevice rename "客厅主灯"
典型调试流程：device list定位设备→ device detail确认当前状态→ device model查看可操作属性→ device control下发指令。四步完成一轮调试，全程无需编写代码。
▍家庭与房间管理
# 列出所有家庭tuyahome list
# 列出指定家庭下的房间tuya home rooms
▍天气查询
# 按经纬度查询天气tuyaweather39.90116.40
# 指定查询字段tuyaweather39.90116.40--codes '["w.temp","w.humidity"]'
▍消息通知
支持短信、语音电话、邮件、App推送四种通知方式，均为发送给当前登录用户：
# 短信通知tuyanotify sms"设备已关闭"
# 语音电话通知tuya notify voice"警告：检测到异常温度"
# 邮件通知tuya notify mail"设备日报""所有设备运行正常"
# App推送通知tuya notify push"安防提醒""客厅检测到异常移动"
在设备告警场景中，可以结合cron定时任务实现自动化监控——例如每小时检查一次设备状态，发现离线设备即自动发送短信通知。
▍数据统计
# 查看可用的统计配置tuyastats config
# 查询某设备的用电量数据（按小时维度）tuyastats data ele_usage SUM20250331002025033123
五、支持的控制类型
说明：当前CLI暂不支持门锁操作、视频/摄像头访问、图像处理、固件升级、设备配网/移除等功能。这些操作请通过涂鸦App或完整API实现。
六、常见问题排查
运行tuya doctor即可自动检测大部分配置问题。常见错误码及处理方式：
七、适用场景与目标开发者
涂鸦生态开发者：硬件联调阶段的设备调试效率将大幅提升——无需反复编写测试脚本，终端命令即可完成查询和控制。
方案商：酒店、公寓、办公楼等商业场景下的设备批量管理，可以通过CLI脚本实现轻量化运维，降低管理系统的开发成本。
AI Agent开发者：为Agent项目提供物理设备控制能力。CLI的命令行接口天然适配AI Agent的执行方式，可以与其他CLI工具组合使用。
硬件测试工程师：设备功能的反复测试不再依赖手机App的手动操作，终端中即可批量运行测试用例。
回到文章开头的观察：办公协作平台集体CLI化，本质上是在回答同一个问题——AI Agent时代，软件应该长什么样？
答案正在变得清晰：每一个软件都需要两种形态。GUI服务于人，CLI服务于AI。当软件把自身能力封装为命令行接口的那一刻，它就从一个"需要人来操作的工具"，变成了"可以被AI Agent直接调用的能力模块"。
这个趋势在办公软件领域已经发生。而AI+IoT领域的CLI化，意味着AI Agent的能力边界正在从数字世界延伸到物理世界——从"帮你发消息、写文档"，到"帮你管理真实空间中的每一台设备"。
tuya-smart-control-cli的开源，是涂鸦推动AI进入物理世界迈出的坚实一步。
当这些物理设备控制的能力，以命令行的形式向AI Agent敞开时，AI进入物理世界的万千应用爆发才刚刚开始。
