涂鸦CLI正式开源：让AI Agent一行命令管理3000+品类智能设备

最近，CLI（命令行工具）正在成为 AI Agent时代的基础设施。

飞书、企业微信、钉钉等多家主流办公协作平台，相继开源了各自的CLI工具，将消息、文档、日程等产品能力封装为命令行 接口 ，供 开发者 和AI Agent直接调用。

背后的逻辑很明确：命令行是AI 编程 Agent最成熟的交互方式，Agent天生适合执行结构化的CLI指令。

办公场景的CLI化已经走在前面。但对AI+ IoT 开发者来说，一个问题随之浮现： 消息可以CLI了，文档可以CLI了，日程可以CLI了——设备控制呢？

查看设备在线状态、调整空调温度、批量关闭某个房间的灯光、查询用电数据——这些日常开发中的高频操作，以往只能通过编写代码调用A PI ，或者打开 手机 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

设备调试效率大幅提升

开发者在硬件联调阶段需要频繁查看设备状态、测试指令下发。以往的流程是：编写脚本→引入 SD K →处理签名→发起请求→解析返回，一轮调试往往需要十几分钟。

使用CLI后，一条命令即可完成：

tuy ad evice detail0620068884f3eb414579

几秒内即可看到设备当前的属性状态——开关状态、亮度值、工作模式等。切换到下一台设备，只需更改device_id重新执行。

02

批量操作无需开发管理后台

方案商在酒店、公寓、办公楼等场景下，往往需要同时管理大量设备。CLI配合Shell脚本，可以实现轻量化的批量运维：

# 查询某个房间下的所有设备tuya device list --room 333
# 批量关闭房间内所有灯光tuya device list --room 333 --json | jq -r'.[].device_id'|\ whilere adi d;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
# 提取所有设备 IDt uya 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: /Use rs /you/.tuya-cli/config.json API Key: sk-AY****xxxx (fromconfigfile) Base URL: ac (China) API connec ti on: 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. te mp","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进入物理世界的万千应用爆发才刚刚开始。