Tuya Smart Control CLI: Terminalden Akıllı Ev Yönetimi Dönemi Başladı

Tuya kısa süre önce web tabanlı kontrol panelini kullanıma açmıştı; şimdi de bir adım daha öteye giderek geliştiriciler, sistem entegratörleri ve ileri seviye kullanıcılar için resmi komut satırı aracını (CLI — Command Line Interface) yayınladı: tuya-smart-control-cli. Bu araç sayesinde mobil uygulama ya da tarayıcı açmadan, doğrudan terminal üzerinden evinizdeki tüm Tuya uyumlu cihazları sorgulayabilir, kontrol edebilir, otomasyon betikleri yazabilir ve enerji istatistiklerini tek satır komutla çekebilirsiniz.

Açık kaynak olarak GitHub’da yayınlanan proje (github.com/tuya/tuya-smart-control-cli), Tuya’nın 2C son kullanıcı API’leri üzerine inşa edilmiş; 200’den fazla ülkede 3.000+ akıllı cihaz kategorisiyle uyumlu çalışıyor. Yazılım Node.js tabanlı, MIT lisansı ile dağıtılıyor ve kurulumu yalnızca dakikalar sürüyor.

Neden CLI? Telefon ve Web Yetmediğinde…

Tuya mobil uygulaması günlük kullanım için, web paneli ise birden çok cihazın aynı ekrandan yönetimi için ideal. Peki ya:

• Bir sunucu üzerinde çalışan cron job ile her sabah 06:30’da kombiyi çalıştırmak,
• Home Assistant ya da n8n gibi araçlar yerine doğrudan bash scripti ile bir Zigbee Su Baskını Sensörü (ZSB-01) tetiklendiğinde WKM02 kuru kontak röleyi kapatmak,
• Bir Python projesinden Tuya cihazlarını sorgulayıp JSON çıktısını başka bir API’ye yönlendirmek,
• Onlarca cihazı tek seferde toplu olarak yeniden adlandırmak veya raporlamak,
• DevOps disiplinine sahip mühendislerin akıllı ev altyapısını “infrastructure as code” mantığıyla yönetmesi…

…söz konusu olduğunda klasik arayüzler yetersiz kalıyor. İşte tam bu noktada CLI devreye giriyor: tıklamak yerine yazıyorsunuz, ve yazdığınız her şey otomatikleştirilebilir, versiyon kontrolüne alınabilir, başka sistemlerle entegre edilebilir.

Kurulum: 4 Komutta Hazır

Aracı çalıştırmak için sistemde Node.js 18 veya üzeri ve bir Tuya API Key yeterli. Türkiye’den kullanıcılar için ilgili API anahtarı tuya.ai adresinden, Çin bölgesi için ise tuyasmart.com üzerinden alınabiliyor. Kurulum adımları:

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

npm link komutundan sonra tuya komutu sistem genelinde her terminalde kullanılabilir hale geliyor. Ardından:

tuya init

komutu ile interaktif kurulum başlatılıyor; API anahtarınızı giriyorsunuz, sistem prefix’ine bakarak bölgeyi otomatik tespit ediyor ve doğru endpoint’e yönlendiriyor. Türkiye kullanıcıları için genellikle Orta Avrupa (sk-EU… → openapi.tuyaeu.com) ya da Batı Avrupa (sk-WE… → openapi-weaz.tuyaeu.com) endpoint’i otomatik seçilir.

Konfigürasyonu doğrulamak için:

tuya doctor

komutu çalıştırıldığında sistem, config dosyasını, API key’in geçerliliğini, bölge eşleşmesini ve API bağlantısını test eder. Başarılı bir çıktı şuna benzer:

  Tuya CLI Doctor
  ───────────────
  ✔ Config file: /Users/you/.tuya-cli/config.json
  ✔ API Key: sk-EU****xxxx (from config file)
  ✔ Base URL: https://openapi.tuyaeu.com (Central Europe)
  ✔ API connection: OK (2 home(s) found)

Bu, devreye almadan önce çalıştırılması gereken kritik bir adım; tıpkı bir Zigbee gateway’i (ZGW-08 Matter/Zigbee/Thread Gateway gibi) ilk kez ağa eklemeden önce sinyal seviyesini kontrol etmek kadar önemli.

Ana Komutlar: Pratik Bir Bakış

CLI, mantıksal olarak şu komut gruplarına ayrılmış:

Komut	İşlevi
tuya home	Ev ve oda yönetimi
tuya device	Cihaz sorgulama, kontrol etme, yeniden adlandırma
tuya weather	Konuma göre hava durumu sorgulama
tuya notify	SMS / sesli arama / e-posta / push bildirimi gönderme
tuya stats	Cihaz bazlı veri istatistikleri (enerji, sıcaklık vb.)
tuya doctor	Konfigürasyon ve bağlantı tanılama

Tüm sorgu komutlarına eklenebilen --json bayrağı, çıktıyı makineye okutulabilir biçimde döndürür — bu, betik yazımında en önemli yapı taşıdır.

tuya home — Ev ve Oda Listesi

$ tuya home list
┌─────────┬──────────────────┬───────┬──────────────────┐
│ Home ID │ Name             │ Role  │ Location         │
├─────────┼──────────────────┼───────┼──────────────────┤
│ 123456  │ Bahçeşehir Daire │ admin │ 41.08, 28.97     │
│ 789012  │ Yazlık           │ owner │ -                │
└─────────┴──────────────────┴───────┴──────────────────┘

Bir evin oda listesini almak için:

$ tuya home rooms 123456
┌─────────┬──────────────┐
│ Room ID │ Name         │
├─────────┼──────────────┤
│ 111     │ Oturma Odası │
│ 222     │ Yatak Odası  │
│ 333     │ Mutfak       │
└─────────┴──────────────┘

Tıpkı Tuya web panelinin “Spatial Panel” ekranında olduğu gibi, evdeki tüm mekânlar tek tablo halinde görüntüleniyor — sadece bu kez Excel’e kopyalayıp düzenlemek ya da bir scripte input olarak vermek son derece kolay.

tuya device — Cihaz Yönetiminin Merkezi

CLI’nın en güçlü yönü hiç şüphesiz device komutu. Tüm cihazları listelemek için:

$ tuya device list
Total: 3 device(s)

┌──────────────────────┬─────────────────────────┬──────────────┬───────────┐
│ Device ID            │ Name                    │ Category     │ Status    │
├──────────────────────┼─────────────────────────┼──────────────┼───────────┤
│ 0620068884f3eb414579 │ Oturma Odası Lambası    │ Aydınlatma   │ ● online  │
│ 1830045562a1bc223456 │ Yatak Odası Klima       │ Klima        │ ● online  │
│ 2940012345b6de789012 │ Mutfak Akıllı Priz      │ Priz         │ ○ offline │
└──────────────────────┴─────────────────────────┴──────────────┴───────────┘

Belirli bir odanın cihazlarını filtrelemek için --room parametresi kullanılır:

tuya device list --room 222

Bir cihazın anlık durumunu (mevcut parametre değerleri ile birlikte) görmek için:

$ tuya device detail 0620068884f3eb414579

  Oturma Odası Lambası
  ─────────────────────────────
  ID:        0620068884f3eb414579
  Category:  Light Source
  Product:   WiFi Smart Light
  Status:    ● online
  Firmware:  1.0.0

  Properties:
  ┌──────────────┬─────────┐
  │ Code         │ Value   │
  ├──────────────┼─────────┤
  │ switch_led   │ true    │
  │ bright_value │ 100     │
  │ work_mode    │ colour  │
  └──────────────┴─────────┘

Bu çıktı, web panelinin “Device Details > Status” ekranında gördüğünüz canlı verilerin terminal karşılığı. Cihazın hangi parametreleri desteklediğini, yani Thing Model‘ini görmek için:

$ tuya device model 0620068884f3eb414579

  Properties (2):
  ┌──────────────┬────────────┬────────┬───────┬───────────────────────┐
  │ Code         │ Name       │ Access │ Type  │ Spec                  │
  ├──────────────┼────────────┼────────┼───────┼───────────────────────┤
  │ switch_led   │ Switch     │ rw     │ bool  │ bool                  │
  │ bright_value │ Brightness │ rw     │ value │ 10~1000 step:1        │
  └──────────────┴────────────┴────────┴───────┴───────────────────────┘

Bu, özellikle bir Tuya geliştirme dokümantasyonu okumadan bir cihazın “ne yapabildiğini” keşfetmek için çok kıymetli; mesela bir ZRM02 Zigbee çift çıkışlı rölenin switch_1, switch_2, countdown_1, countdown_2 gibi tüm DP kodlarını tek komutla görmek mümkün.

Cihaz Kontrolü: Tek Satırda Komut Gönderme

CLI’nın en eğlenceli kısmı: cihazları doğrudan komut satırından kontrol etmek. JSON formatında bir komut göndermek yeterli:

# Lambayı aç
tuya device control 0620068884f3eb414579 '{"switch_led":true}'

# Parlaklığı 500'e ayarla
tuya device control 0620068884f3eb414579 '{"bright_value":500}'

# Aynı anda hem aç hem parlaklık ver
tuya device control 0620068884f3eb414579 '{"switch_led":true,"bright_value":800}'

# Klimayı 26 derecede soğutmaya al
tuya device control 1830045562a1bc223456 '{"mode":"cold","temp_set":26}'

Burada gönderilen JSON’un anahtarları, tuya device model çıktısında gördüğünüz DP kodları ile birebir uyumlu olmalı. WiFi Sensörlü IR Kumanda (WAK-02) üzerinden bir klimayı kontrol ediyorsanız aynı mantıkla mode, temp_set, fan_speed gibi parametreleri tek komutla setleyebilirsiniz. ZPM01 Zigbee Perde Panjur Rölesi için {"control":"open"} ya da {"percent_control":35} gibi komutlarla perdenizi tam istediğiniz konuma alabilirsiniz.

Cihazı yeniden adlandırmak da bir o kadar pratik:

tuya device rename 0620068884f3eb414579 "Salon Tavan Spotu"

tuya weather — Konuma Göre Hava Durumu

Tuya altyapısı sadece cihaz kontrolü değil, hava durumu servisi de sunuyor. CLI üzerinden:

# İstanbul için (Bahçeşehir koordinatları)
tuya weather 41.08 28.97

# Sadece sıcaklık ve nem değerlerini al
tuya weather 41.08 28.97 --codes '["w.temp","w.humidity"]'

Bu, özellikle bir senaryoyu hava durumu ile tetiklemek istediğinizde altın değerindedir: “Eğer dışarıdaki nem %80’in üzerindeyse balkondaki Zigbee Stor Perde Motorunu indir” gibi bir mantığı bir bash scripti ile dakikalar içinde kurabilirsiniz.

tuya notify — Kendinize Bildirim Gönderin

Tüm bildirim komutları self-send modunda çalışır; yani sadece o anki Tuya hesabınıza giriş yapmış kullanıcıya gider:

# SMS
tuya notify sms "Su baskını sensörü tetiklendi, vana kapatıldı"

# Sesli arama (kritik alarm için ideal)
tuya notify voice "Dikkat: kazan dairesinde anormal sıcaklık"

# E-posta
tuya notify mail "Günlük Rapor" "Tüm cihazlar normal çalışıyor"

# Uygulama push bildirimi
tuya notify push "Güvenlik" "Salon hareket sensörü hareket algıladı"

Bir ZSOS-01 SOS düğmesi basıldığında doğrudan sesli arama ile uyarı almak; veya WAS-63 akıllı sigortanın güç tüketimini izleyen bir scriptin belirli bir eşiği aştığında e-posta göndermesi… Olasılıklar bir scriptin hayal gücü kadar geniş.

tuya stats — Enerji ve Veri İstatistikleri

Akıllı enerji ölçer kullanan herkes için en kritik komut bu. Hangi cihazların hangi metrikleri raporladığını görmek için:

tuya stats config

Belirli bir cihazın belirli bir saat aralığındaki tüketimini almak için:

tuya stats data 0620068884f3eb414579 ele_usage SUM 2026051300 2026051323

Buradaki ele_usage Zigbee Akıllı Enerji Ölçer ya da ZAS-63 akıllı sigorta gibi cihazlardan gelen elektrik tüketim DP kodu; SUM operatörü ile saatlik toplamlar alınır. Çıktıyı --json ile alıp doğrudan bir Python pandas dataframe’e yüklemek, ya da awk/jq ile parse edip Grafana’ya beslemek… CLI’nın gerçek gücü tam burada parlıyor.

JSON Çıktısı ve Otomasyon: Asıl Güç Burada

Komut satırı araçlarının ekosistemde değer kazandığı asıl nokta, diğer araçlarla birleşebilmeleridir. CLI’nın --json bayrağı tam bu amaca hizmet ediyor:

# Tüm cihazların ID'lerini al ve jq ile filtrele
tuya device list --json | jq '.[].device_id'

# Çıktıyı bir dosyaya yaz, sonra başka bir scriptten oku
tuya home list --json > homes.json

Mesela bir bash scripti ile çevrimdışı tüm cihazları otomatik tespit edip Slack’e bildirim atmak:

tuya device list --json \
  | jq -r '.[] | select(.online==false) | .name' \
  | while read name; do
      curl -X POST -d "text=Cihaz çevrimdışı: $name" $SLACK_WEBHOOK
    done

Bu satırlar, mobil uygulamaya gün boyu bakmadan tüm sistemin sağlığını izleyen bir gözcüye dönüşüyor.

Tipik Bir İş Akışı

Bir cihazı keşfedip kontrol etmek için izlenecek pratik yol şu:

# 1. Cihazları listele, hedef cihazı bul
tuya device list

# 2. Mevcut durumunu kontrol et
tuya device detail <device_id>

# 3. Hangi parametreleri desteklediğini gör
tuya device model <device_id>

# 4. Komut gönder
tuya device control <device_id> '{"switch":true}'

Web panelindeki “Tıkla → Aç → İncele” işleminin, terminalde 4 satırlık bir reçeteye indirgenmiş hali.

Desteklenen Komut Tipleri

CLI dört temel parametre tipini destekliyor:

Tip	Açıklama	Örnek
bool	Aç/Kapa	{"switch_led": true}
enum	Mod seçimi	{"mode": "cold"}
value	Sayısal değer	{"bright_value": 500}
string	Metin değeri	{"display_text": "Hello"}

Desteklenmeyen işlemler de var ve bunları bilmek önemli: kapı kilidi kontrolü, kamera/video işlemleri, görüntü ile ilgili komutlar, firmware yükseltme, cihaz eşleştirme/ekleme/çıkarma. Bu işlemler için hâlâ Tuya/Smart Life mobil uygulamasını ya da web panelini kullanmak gerekiyor. Örneğin AKK-01 akıllı kapı kilidinizi CLI üzerinden açıp kapatamazsınız (güvenlik gereği bu makul bir kısıtlama), ancak durum bilgilerini ve log kayıtlarını sorgulayabilirsiniz.

Hata Kodları ve Sorun Giderme

tuya doctor ile karşılaşabileceğiniz tipik problemler ve çözümleri şöyle:

Sorun	Çözüm
API Key tanımlı değil	tuya init çalıştırın
Authentication failed (kod 1010)	API Key süresi dolmuş, tuya.ai‘den yenisini alın
URI path invalid (kod 1108)	Base URL bölgenizle eşleşmiyor, yeniden kontrol edin
Network error	İnternet bağlantısı ya da güvenlik duvarı engeli

Cihaz seviyesinde:

• 40000901 — Device not found: Cihaz ID’sini doğrulayın.
• 40000903 — Device model not found: Cihaz Thing Model’i desteklemiyor olabilir.

Kurumsal Senaryolar İçin Neler Mümkün?

Otel zincirleri, AVM’ler, üretim tesisleri, akıllı bina projeleri… Bu CLI’nın asıl gücünü kurumsal kurulumlarda gösteriyor:

• Toplu raporlama: Tüm cihazların durumunu her sabah cron job ile alıp Excel/CSV’ye yazan bir betik.
• Anomali tespiti: Belirli bir koridorda 10 dakikadan uzun çevrimdışı kalan bir ZTA-01 Zigbee mekanik anahtarı tespit edip teknik servise mail atan bir Python betiği.
• Enerji kontrolü: Her saat başı WAS-63 akıllı sigortadan tüketim verisini çekip, eşik aşıldığında otomatik olarak prizleri kapatan bir n8n veya Node-RED akışı.
• Toplu yeniden adlandırma: Yeni teslim edilen 50 odalı bir oteldeki tüm cihazları, oda numarasına göre tek scriptle isimlendiren bir helper.
• CI/CD benzeri devreye alma: Akıllı senaryoları ve cihaz konfigürasyonlarını git deposunda tutmak, yeni şubeler için tekrar çalıştırabilir hale getirmek.

Novato olarak, bu tip kurumsal projelerde sadece donanım tedariki ile kalmıyor, özel scriptleri, API entegrasyonlarını ve kendi markanıza özel kontrol panellerini Tuya altyapısının üzerine inşa ediyoruz. Tuya’nın açık kaynak CLI’sı bu sürecin önemli bir tuğlası — ama bütün bir sistem değil. Mühendislik ekibimiz, projenizin ölçeğine göre CLI’yi bir başlangıç olarak kullanıp üzerine size özel iş kuralları, raporlama ve yetki katmanları ekleyebiliyor.

Sonuç: Akıllı Ev “Geliştirilebilir” Bir Sisteme Dönüşüyor

Mobil uygulama, son kullanıcının dostudur; web paneli, profesyonel kullanıcının; CLI ise geliştiricinin ve otomasyon mühendisinin dostudur. Tuya’nın bu üç ayrı ekosistem katmanını paralel olarak desteklemesi, platformun neden 200’den fazla ülkede 3.000’i aşkın cihaz kategorisinde standart haline geldiğini anlatıyor.

Hem temel ev kurulumunuz için doğru donanımı seçmek, hem de bu donanımları CLI/API üzerinden otomatize etmek isterseniz; ürün seçiminden devreye alımına, kurumsal entegrasyondan özel script yazımına kadar süreci Novato güvencesiyle birlikte planlayabiliriz. novato.com.tr üzerinden Tuya uyumlu WiFi, Zigbee ve Bluetooth ürünlerimizi inceleyebilir ya da teklif formu doldurabilirsiniz.

Proje GitHub Linki: github.com/tuya/tuya-smart-control-cli Tuya API Key Başvurusu (uluslararası): tuya.ai

---