Tuya Smart Control CLI Technical Documentation: IoT Device CLI Tool for AI Agents

Overview

tuya-smart-control-cli is Tuya’s open-source IoT device management command-line tool. Built on the Tuya End-user API, it provides developers and AI Agents with a complete CLI interface covering device queries, control, notifications, and data statistics.

The CLI is a fundamental infrastructure form for the AI Agent era — the command line is the most mature interaction model for programmatic Agents, which are natively suited to executing structured CLI instructions. tuya-smart-control-cli wraps control over Tuya’s 3,000+ device categories into a standard command-line interface, making IoT device control for AI Agents work exactly like calling git, docker, or any other CLI tool.

Dimension	Specification
Device categories	3,000+ smart hardware categories
Global reach	200+ countries and regions, 7 data centers
Runtime	Node.js >= 18
License	Open source on GitHub
Output formats	Human-readable table / JSON (--json)

1. Architecture

1.1 Relationship Between the End-user API and the CLI

┌─────────────────────────────────────┐
│         AI Agent / Developer         │
└──────────────┬──────────────────────┘
               │ CLI invocation
┌──────────────▼──────────────────────┐
│      tuya-smart-control-cli         │
│  ┌──────────────────────────────┐   │
│  │ Built-in auth (sign/token)   │   │
│  │ Parameter formatting/        │   │
│  │   validation                 │   │
│  │ Output formatting (Table/JSON│   │
│  │ Regional auto-routing        │   │
│  └──────────────────────────────┘   │
└──────────────┬──────────────────────┘
               │ HTTPS
┌──────────────▼──────────────────────┐
│        Tuya End-user API            │
│  (Device management / control /     │
│   notifications / statistics)       │
│        Global 7 Data Centers        │
└─────────────────────────────────────┘

Layer responsibilities:

Layer	Responsibility
End-user API	Underlying capability layer: full API for device listing, control, data queries, message notifications, etc.
CLI	Wrapper layer: built-in authentication flow, parameter formatting, regional routing — ready to use out of the box

The CLI eliminates the need to write code, handle signatures, or construct requests manually. Authentication and permission management are identical to calling the API directly — credentials such as the API Key still need to be configured.

1.2 Regional Auto-Routing

The API Key format is sk-<PREFIX><rest>. The prefix automatically maps to one of the seven global data centers:

Prefix	Data Center Region
cn	China
us	US West
eu	Europe
in	India
…	Other regions

The CLI automatically identifies the region from the key prefix and matches the corresponding server endpoint — no manual configuration needed.

2. Installation and Configuration

2.1 Requirements

Dependency	Version
Node.js	>= 18
API Key	China: tuyasmart.com / International: tuya.ai

2.2 Installation

git clone https://github.com/tuya/tuya-smart-control-cli.git
cd tuya-smart-control-cli
npm install
npm link

After running npm link, the tuya command is available globally.

2.3 Configuration

# Interactive setup (recommended)
tuya init

tuya init guides you through entering an API Key and automatically handles region detection and server endpoint matching.

2.4 Connectivity Check

tuya doctor

Checks in sequence: configuration file → API Key validity → network connectivity → account home data.

Tuya CLI Doctor
✔ Configuration file found
✔ API Key valid
✔ Network connectivity OK
✔ Home data accessible

All ✔ means setup is complete.

3. Command Reference

3.1 Device Management (Core)

# List all devices
tuya device list

# View device details (current attribute state)
tuya device detail <device_id>

# View device Thing Model (operable attribute definitions)
tuya device model <device_id>

# Control a device
tuya device control <device_id> --code <property> --value <value>

Typical debugging workflow:

device list    (locate the device)
  → device detail  (confirm current state)
  → device model   (view operable attributes)
  → device control (dispatch command)

Four steps to complete a full device debugging cycle — no code required.

3.2 Home and Room Management

# List all homes
tuya home list

# View rooms in a home
tuya home rooms <home_id>

# View devices in a room
tuya room devices <room_id>

3.3 Weather Query

# Query weather by coordinates
tuya weather --lat <latitude> --lon <longitude>

3.4 Message Notifications

Four notification channels are supported, all delivered to the currently logged-in user:

# SMS notification
tuya notify sms --content "Device offline alert"

# Voice call
tuya notify voice --content "Critical alert"

# Email notification
tuya notify email --subject "Daily Report" --content "..."

# App push notification
tuya notify push --content "Device status changed"

3.5 Data Statistics

# View available statistics configurations for a device
tuya stats list <device_id>

# Query device statistics data (e.g., energy consumption)
tuya stats query <device_id> --code <stat_code> --start <date> --end <date>

3.6 JSON Output

All query commands support the --json flag for structured JSON output:

# Export device list as JSON
tuya device list --json

# Pipe into jq
tuya device list --json | jq '.[] | select(.online == true)'

4. Supported Control Types

Category	Supported Operations
Lighting	On/off, brightness, color temperature, color mode
AC / HVAC	On/off, temperature, mode, fan speed
Outlets / switches	On/off, timer, power statistics
Curtains / motors	On/off, position percentage
Sensors	State query, historical data
Cleaning appliances	On/off, mode, status
Kitchen appliances	On/off, temperature, mode, timer
…	3,000+ categories unified via Thing Model

Currently unsupported operations: door lock operations, image processing, firmware upgrades, device provisioning/removal. These require the Tuya App or the full API.

5. AI Agent Integration

5.1 Direct Agent Invocation

AI Agents (such as Claude Code, Cursor, OpenClaw, etc.) can execute CLI commands directly in the terminal, exactly as they would with any other CLI tool:

# Agent queries device state before making a decision
tuya device detail <id> --json | agent_process

# Agent executes a control command
tuya device control <id> --code switch_1 --value true

5.2 Batch Operations and Automation Scripts

Combine with shell scripts and cron jobs for lightweight automated operations:

#!/bin/bash
# Check device online status every hour; send an alert for offline devices
offline=$(tuya device list --json | jq '.[] | select(.online == false) | .name')
if [ -n "$offline" ]; then
  tuya notify sms --content "Device offline: $offline"
fi

5.3 Typical Use Cases

Role	Scenario	CLI Value
Hardware developer	Device debugging during integration	One command replaces writing test scripts
Solution provider	Bulk device management for hotels/apartments	Shell scripts replace building a management portal
AI Agent developer	Adding physical device control to an Agent	Native CLI interface matches Agent execution patterns
QA engineer	Repeated device functionality verification	Run test cases in bulk from the terminal

6. Troubleshooting

Run tuya doctor to automatically detect most configuration issues. Common error codes:

Error Code	Cause	Resolution
1000	API Key invalid or expired	Obtain a new API Key
1001	Signature verification failed	Check that the Key was copied in full
1100	Network connection timeout	Check network environment and proxy settings
2000	Device not found	Verify the device_id is correct
2001	Device offline	Check the device’s network status

7. Technical Analysis

7.1 Comparison with Traditional IoT Development

Dimension	Traditional (direct API calls)	tuya-smart-control-cli
Debug a single device	Write script → import SDK → handle signing → make request → parse response (~15 min)	One command, done in seconds
Authentication	Manually manage signing logic and token lifecycle	Built into the CLI, handled transparently
Region configuration	Manually look up and configure server endpoint	API Key prefix auto-routes
Output handling	Parse JSON response manually	Built-in table / JSON dual format
AI Agent integration	Must wrap API calls into executable scripts	Native CLI, ready to use immediately
Bulk operations	Build a management portal	Shell scripts + cron

7.2 Design Advantages

Feature	Technical Value
Open source	Auditable, customizable, and contribution-friendly
Global coverage	7 data centers with automatic routing — no manual switching
Category breadth	3,000+ categories unified via Thing Model; one set of commands covers all devices
Agent-friendly	Structured CLI output natively fits the AI Agent execution paradigm
JSON output	--json flag enables pipeline processing and programmatic integration
Self-diagnosis	tuya doctor diagnoses configuration and connectivity issues in one command

8. Resources

Resource	URL
GitHub	https://github.com/tuya/tuya-smart-control-cli
API Key (Mainland China)	tuyasmart.com
API Key (International)	tuya.ai
Issue tracker	GitHub Issues