JSON Çıktı Referansı

Tüm rdc komutları yapılandırılmış JSON çıktısı üretir. Bir betiğe pipe edin ya da doğrudan bir ajana besleyin.

JSON Çıktısını Etkinleştirme

Açık Bayrak

rdc machine status prod-1 --output json
rdc machine status prod-1 -o json

Otomatik Algılama

rdc TTY olmayan bir ortamda (boru hattı, alt kabuk veya AI ajanı tarafından başlatılmış) çalıştığında, çıktı otomatik olarak JSON’a geçer. Bayrak gerekmez.

# Produces JSON automatically
result=$(rdc machine status prod-1)

JSON Zarfı

Her JSON yanıtı tutarlı bir zarf kullanır:

{
  "success": true,
  "command": "machine query",
  "data": {
    "name": "prod-1",
    "status": "running",
    "repositories": []
  },
  "errors": null,
  "warnings": [],
  "metrics": {
    "duration_ms": 142
  }
}

Alan	Tür	Açıklama
success	boolean	Komutun başarıyla tamamlanıp tamamlanmadığı
command	string	Tam komut yolu (ör. "machine query", "repo up")
data	object | array | null	Başarıda komuta özel veri, hatada null
errors	array | null	Başarısızlıkta hata nesneleri, başarıda null
warnings	string[]	Yürütme sırasında toplanan önemli olmayan uyarılar
metrics	object	Yürütme meta verileri

Hata Yanıtları

Başarısız komutlar, kurtarma ipuçlarıyla yapılandırılmış hatalar döndürür:

{
  "success": false,
  "command": "machine query",
  "data": null,
  "errors": [
    {
      "code": "NOT_FOUND",
      "message": "Machine \"prod-2\" not found",
      "retryable": false,
      "guidance": "Verify the resource name with \"rdc machine status\" or \"rdc repo list\""
    }
  ],
  "warnings": [],
  "metrics": {
    "duration_ms": 12
  }
}

Hata Alanları

Alan	Tür	Açıklama
code	string	Makine tarafından okunabilir hata kodu (kanonik liste için ERROR_CODES sabitlerine bakın)
message	string	İnsan tarafından okunabilir açıklama
retryable	boolean	Aynı komutun yeniden denenmesinin başarılı olup olamayacağı
guidance	string	Serbest metin ipucu (eski. Yapılandırılmış eylem verisi için next tercih edin)
next	object?	Yapılandırılmış sonraki eylem ipucu (varsa). Aşağıya bakın

Yapılandırılmış next Eylem İpuçları

PRECONDITION_MISMATCH gibi yüksek değerli hata kodlarında, hata kullanıcıya sunulacak tam komutları içeren bir next alanı taşır. Her hata kodu bu alanı içermez; yalnızca tanımlı bir kurtarma yolu olanlar içerir. Ajanlar, next.options[].run değerini olduğu gibi kullanıcıya iletmeli, kendi komutlarını türetmemelidir. Bu, ajanın var olmayan bir komut uydurma hata modunu ortadan kaldırır. Tahmin ettiğinizden daha sık yaşanır.

{
  "errors": [{
    "code": "PRECONDITION_MISMATCH",
    "message": "--current digest mismatch (expected 3264f8ee…, got 611dfd8a…)",
    "next": {
      "summary": "Provide the current value or acknowledge rotation.",
      "options": [
        {
          "description": "Re-read current digest, then retry with --current",
          "run": "rdc repo secret get mail --key STRIPE_KEY"
        },
        {
          "description": "Skip the precondition (rotation, audited)",
          "run": "rdc repo secret set mail --key STRIPE_KEY --value <new> --mode file --rotate-secret"
        }
      ]
    }
  }]
}

Şema:

Alan	Tür	Açıklama
next.summary	string	Kullanıcının karar vermesi gereken şeyin tek satırlık açıklaması
next.options[]	array	Somut eylemler; her biri kullanıcının seçebileceği bir alternatiftir
next.options[].description	string	Bu seçeneğin insan tarafından okunabilir açıklaması
next.options[].run	string	Tam CLI komutu. Kullanıcıya olduğu gibi iletin

Yeniden Denenebilir Hatalar

Bu hata türleri retryable: true olarak işaretlenir:

• NETWORK_ERROR, SSH bağlantısı veya ağ hatası
• RATE_LIMITED, Çok fazla istek, bekleyip yeniden deneyin
• API_ERROR, Geçici arka uç hatası

Yeniden denenemez hatalar (kimlik doğrulama, bulunamadı, geçersiz argümanlar) yeniden denemeden önce düzeltici eylem gerektirir.

Çıktı Filtreleme

Çıktıyı belirli anahtarlarla sınırlamak ve token kullanımını azaltmak için --fields kullanın:

rdc machine status prod-1 --containers -o json --fields name,status,repository

Kuru Çalıştırma Çıktısı

Yıkıcı komutlar, ne olacağını önizlemek için --dry-run destekler:

rdc repo delete mail@prod-1 --dry-run -o json

{
  "success": true,
  "command": "repo delete",
  "data": {
    "dryRun": true,
    "repository": "mail",
    "machine": "prod-1",
    "guid": "a1b2c3d4-..."
  },
  "errors": null,
  "warnings": [],
  "metrics": {
    "duration_ms": 8
  }
}

--dry-run desteği olan komutlar: repo up, repo down, repo delete, snapshot delete, sync upload, sync download.

Ayrıştırma Örnekleri

Shell (jq)

status=$(rdc machine status prod-1 -o json | jq -r '.data.status')

Python

import subprocess, json

result = subprocess.run(
    ["rdc", "machine", "query", "--name", "prod-1", "-o", "json"],
    capture_output=True, text=True
)
envelope = json.loads(result.stdout)

if envelope["success"]:
    print(envelope["data"]["status"])
else:
    error = envelope["errors"][0]
    if error["retryable"]:
        # retry logic
        pass
    else:
        print(f"Error: {error['message']}")
        print(f"Fix: {error['guidance']}")

Node.js

import { execFileSync } from 'child_process';

const raw = execFileSync('rdc', ['machine', 'query', '--name', 'prod-1', '-o', 'json'], { encoding: 'utf-8' });
const { success, data, errors } = JSON.parse(raw);

if (!success) {
  const { message, retryable, guidance } = errors[0];
  throw new Error(`${message} (retryable: ${retryable}, fix: ${guidance})`);
}