AI Agent CLI Tasarımı: JSON, Exit Code'ları ve Bekleme

Bir AI agent CLI, yalnızca bir model tarafından çağrılabilen bir command-line aracı değildir. Bu, operasyonel bir protokoldür. Agent'ın deterministik girdilere, yapılandırılmış çıktılara, anlamlı exit code'larına, kararlı hata kategorilerine ve asynchronous altyapının nihai duruma ulaşmasını bekleyebileceği bir yönteme ihtiyacı vardır.

Bu contract olmadığında agent, başarıyı “deployment başlatıldı” gibi açıklamalardan çıkarsamak zorunda kalır. Bu çıkarım tehlikelidir; çünkü kabul edilen bir istek daha sonra build, health check, container başlatma veya traffic cutover sırasında başarısız olabilir.

Tahmin edilen deployment başarısı neden tehlikelidir?

Çoğu altyapı işlemi asynchronous çalışır. Bir API deployment'ı kabul edip milisaniyeler içinde bir ID döndürebilir; ancak gerçek build birkaç dakika sürebilir. Agent, başarıyı kabul aşamasında raporlarsa sonraki her adım yanlış bir varsayım üzerine kurulmuş olur.

Aradaki farkı düşünün:

Event	Kanıtladığı şey	Kanıtlamadığı şey
İstek kabul edildi	Platform isteği anladı	Kodun build edildiği
Build tamamlandı	Bir image veya artifact oluşturuldu	Uygulamanın başlatıldığı
Health gate geçti	Yeni instance gerektiği şekilde yanıt verdi	Business flow'ların çalıştığı
Traffic değiştirildi	Release aktif hâle geldi	Sağlıklı kalacağı
Uptime gözlemi	Service'a erişilmeye devam edildiği	Her özelliğin doğru çalıştığı

Bir insan dashboard'daki bu ayrımı fark edebilir. Metin üzerinden çalışan bir agent için bu ayrımın interface'e kodlanması gerekir.

Dockup'ın command contract'ı queueing ile completion'ı birbirinden ayırır. --wait olmadan çalıştırılan bir deploy, waited:false ile hemen döner; --wait içeren bir deploy ise başarı, hata veya timeout gerçekleşene kadar bekler:

dockup deploy production/api --wait --json

Varsayılan timeout 900 saniyedir. Command yalnızca başarılı bir terminal durumdan sonra 0 exit code'u ile tamamlanır. Sonuç başarılı olmadığında deploy_failed veya deploy_timeout ile non-zero exit code döner.

Yapılandırılmış JSON CLI, AI agent'a ne sağlar?

Yapılandırılmış JSON, prose yorumlamanın yerini adlandırılmış alanlarla doldurur. Agent; noktalama işaretlerine, renklere, sütun genişliğine veya kullanılan ifadelere bağlı kalmak yerine status, deploymentId, target ya da code alanlarını doğrudan bulabilir.

Başarılı bir sonuç data olarak işlenebilir:

{
  "ok": true,
  "target": "production/api",
  "deploymentId": "dep_123",
  "waited": true,
  "status": "success",
  "durationMs": 142381,
  "url": "https://api.dockup.tech"
}

Hatalar da aynı transport yapısını kullanır:

{
  "ok": false,
  "error": "Deployment failed",
  "code": "deploy_failed"
}

Önemli tasarım kuralı şudur: JSON stdout'a yazılır; parsing işlemini bozmaması gereken uyarılar ise stderr'e gönderilir. Follow-mode log'ları NDJSON—satır başına bir JSON object—kullanır. Böylece çağıran taraf, tek ve dev bir array'i beklemek zorunda kalmadan stream'i parça parça işleyebilir.

Dockup, command yüzeyinin tamamında --json desteği sunar. 135 command varken bir agent'ın flag'leri hafızadan çıkarmasını beklemek kırılgan olurdu. CLI reference ve paketlenmiş skill, agent'ın izlemesi gereken version-aligned command talimatlarını sağlar.

Önemli olan tasarım özelliği akıllı discovery değildir. Önemli olan, agent'ın güncel ve yapılandırılmış çalışma yönlendirmelerini alması ve eski bir prompt'tan flag uydurmamasıdır.

Gerçek exit code'ları deployment otomasyonunu nasıl kontrol eder?

İşletim sistemi exit code'u; shell script'leri, CI runner'ları ve coding agent'lar için mevcut en taşınabilir başarı sinyalidir. 0 exit code'u, command'ın tanımlanan sonucu elde ettiği anlamına gelir. Non-zero code ise çağıran tarafın recovery, escalation veya termination akışına geçmesi gerektiğini belirtir.

Bu shell fragment'ı özellikle sade tutulmuştur:

if dockup deploy production/api --wait --json > result.json; then
  echo "deployment reached success"
else
  dockup logs production/api --build --json
  exit 1
fi

stdout içinde “success” kelimesini aramaz. HTTP 202 yanıtının production'ın hazır olduğu anlamına geldiğini varsaymaz. Başarı tanımını CLI'a bırakır ve hatayı parent process'e iletir.

Gerçek exit code'ları container içindeki one-shot command'lar için de aynı derecede önemlidir. Dockup'ın PRO exec command'ı stdout, stderr ve gerçek command exit code'unu döndürür:

dockup exec "npm run migrate" \
  -s production/api \
  --json

Böylece agent, tamamlanan bir migration ile yalnızca başlatılmış bir command'ı birbirinden ayırabilir. Bu, AI agent production guardrail'eri için temel bir ilkedir.

Terminal durumu bekleme, kırılgan polling'in yerini nasıl alır?

Elle yazılan polling loop'ları, gizli policy kararları doğurur: Ne sıklıkla polling yapılmalı, hangi state'ler terminal kabul edilmeli, ne kadar beklenmeli, geçici bir network hatası timer'ı sıfırlamalı mı ve bir container yeniden başlatıldığında ne yapılmalı?

Bir agent'ın bu kararları yanlış verme ihtimali özellikle yüksektir; çünkü platformun tüm state machine'ini bilmiyor olabilir. Wait semantiğinin sahibi platform olmalıdır.

Dockup iki kullanışlı pattern sunar:

dockup deploy production/api --wait --timeout 1800 --json
dockup push --json

deploy --wait açıkça bekler. push, push işlemi ve release tetiklendikten sonra varsayılan olarak bekler; --no-wait ise bu davranıştan çıkmak için kullanılır. Her ikisi de terminal sonucu yansıtan bir exit code döndürür.

Log following de aynı yaklaşımı izler:

dockup logs production/api --build -f --json

Stream, build başarıya veya hataya ulaştığında sona erer. Son NDJSON object'i done:true bilgisini taşır ve başarısız bir build non-zero exit code ile tamamlanır. Çağıran tarafın ikinci bir polling implementation'ı yazmasına gerek kalmaz.

Deployment sonrasında uygulamanın erişilebilirliği için Dockup'ın uptime command'ı dakika seviyesinde check'ler, ortalama response time ve p95 değerini döndürür:

dockup uptime production/api --hours 24 --json

Bekleme ve monitoring farklı kavramlardır. --wait, bu deployment'ın terminal bir sonuca ulaşıp ulaşmadığını yanıtlar; uptime ise çalışan service'ın zaman içinde nasıl davrandığını gösterir.

Bir agent hangi error code'larını anlamalı?

Kararlı hata kategorileri, agent'ın her olası mesajı yorumlamadan sınırlı ve belirli bir action alabilmesini sağlar. Dockup şu code'lar gibi değerler sunar:

Error code	Anlamı	Güvenli agent yanıtı
not_logged_in	Kullanılabilir token yok	Durun ve authentication isteyin
not_linked	push için .dockup target'ı yok	Target'ı resolve edin veya iletin
no_target	Service tanımlanamadı	services --json çalıştırın
needs_confirm	Destructive action için approval yok	Bir insandan onay isteyin
deploy_trigger_failed	Deployment başlatılamadı	API hatasını raporlayın
deploy_failed	Build veya deploy başarısız oldu	Build log'larını okuyun
deploy_timeout	Bekleme limiti dolduğunda işlem hâlâ sürüyordu	Belirsizliği raporlayın veya bilinçli şekilde süreyi uzatın

Error message yararlı bir bağlam sağlamaya devam eder; ancak ilk branch'i code belirler. Bu sayede otomasyon, daha açık ifadeler veya localization değişiklikleri karşısında dayanıklı olur.

Confirmation da protokolün bir parçasıdır. Destructive bir command, caller non-interactive olduğu için sessizce devam etmemelidir. Dockup, bu tür işlemleri --yes olmadan reddeder ve needs_confirm döndürür. Autonomous agent bir soruyla karşılaşır; aşılması gereken bir engelle değil.

Güvenlik modeli security best practices içinde daha ayrıntılı olarak ele alınır.

Production'a hazır bir CLI için minimum contract nedir?

Production'a hazır bir AI agent CLI küçük ama katı bir contract'ı karşılamalıdır:

1. Her read ve write işlemi machine-readable output üretir.
2. Hata, non-zero process exit ile sonuçlanır.
3. Asynchronous mutation'lar, dokümante edilmiş bir terminal state için bekleyebilir.
4. Secret değerleri read command'ları tarafından hiçbir zaman döndürülmez.
5. Destructive action'lar explicit confirmation gerektirir.
6. Hatalar branching için uygun, kararlı code'lara sahiptir.
7. CLI package ile agent talimatları version-aligned kalır.
8. Mutation'lar bir audit trail içinde kaydedilir.

Dockup'ın skill'i bu kuralları Claude Code ve Codex için varsayılan davranışa dönüştürür. Agent'a JSON kullanmasını, DOCKUP_TOKEN ile authenticate olmasını, tam target'ları keşfetmesini, --wait ile deploy etmesini, credential'ları korumasını ve needs_confirm durumunda durmasını söyler.

Bu modeli agent skills vs MCP içindeki daha geniş kavramlarla karşılaştırın. Skill operating knowledge sağlar; CLI ise exit status ve output'u gerçeği tanımlayan executable interface olarak kalır.

Agent-facing command için test matrix'i

Herhangi bir altyapı command'ını agent'a sunmadan önce happy path'ten fazlasını test edin:

Test	Beklenen davranış
Geçerli istek	JSON sonucu ve 0 exit code'u
Geçersiz token	Kararlı auth code'u ve non-zero exit
Bilinmeyen target	Kararlı target code'u ve mutation olmaması
Uzun süren deploy	Terminal state veya timeout gerçekleşene kadar beklemesi
Başarısız deploy	Non-zero exit ve teşhis edilebilir deployment ID
Eksik destructive approval	needs_confirm, deletion yapılmaması
Secret read	Key metadata görünür, değer maskeli
JSON output sırasında warning	Warning stderr'de, geçerli JSON stdout'ta

Bu matrix, şık bir progress spinner'dan daha değerlidir. Human formatting sonradan bunun üzerine eklenebilir; deterministic bir machine contract ise sonradan yeniden oluşturulamaz.

Dockup CLI documentation, bu modelin arkasındaki concrete command'ları gösterirken AI-powered development, manuel tool kullanımından agent-directed workflow'lara geçişi daha geniş bağlamıyla açıklar.

Observability'yi command contract'ının bir parçası olarak ele alın

Agent-facing bir mutation, daha sonra investigation yapılmasını mümkün kılan identifier'lar döndürmelidir. Bir deployment response'u target ve deployment ID bilgilerini; oluşturulan bir database kararlı bir slug'ı; volume snapshot ise snapshot ID'sini içermelidir. Bu referanslar olmadan agent bir olayı açıklayabilir; ancak güvenilir şekilde inspect, retry veya reverse edemez.

Audit trail contract'ı tamamlar. Structured output tek bir invocation'ı açıklarken audit record'ları birden fazla invocation'ı zaman içinde birbirine bağlar. Birlikte kullanıldıklarında operatörlerin agent'ın hedeflenen resource üzerinde işlem yapıp yapmadığını ve sonraki recovery command'ının aynı production event'ine referans verip vermediğini yanıtlamasını sağlar.

Interface'i sade tutun

Güvenilir bir AI agent CLI, success, failure, timeout ve retry durumlarında şaşırtıcı olmamalıdır.

Son interface testi

AI agent CLI gerçeği olduğu gibi yansıtacak şekilde başarısız olmalıdır.

Workflow'u production'a taşıyın

Production erişimini devretmeden önce contract'ı bir shell üzerinden test edin: JSON parsing'i, başarılı exit'i, zorunlu bir failure'ı, timeout'u ve engellenmiş bir destructive operation'ı doğrulayın.

npm install -g dockup-cli
dockup skill install

İlk command CLI'ı yükler. İkinci command, Claude Code ve Codex için eşleşen Dockup skill'ini yükler. app.dockup.ai üzerinden ücretsiz başlayın.

SSS

Bir CLI'ı AI agent'lar için uygun kılan nedir?

Yapılandırılmış output, gerçek exit code'ları, terminal state bekleme, kararlı error code'ları, secret masking ve destructive operation'lar için explicit confirmation gerekir.

Agent'lar için JSON neden human-formatted CLI output'tan daha iyidir?

JSON, kararlı field adları ve type'lar sağlar. Agent'ın anlamı renklerden, tablolardan, noktalama işaretlerinden veya değişen prose ifadelerinden çıkarması gerekmez.

Kabul edilmiş bir deployment request'i neden başarı sayılmaz?

Kabul edilmesi yalnızca platformun işlemi queue'ya aldığını kanıtlar. Daha sonraki build, startup, health gate ve traffic cutover adımları hâlâ başarısız olabilir.

Varsayılan Dockup deployment wait timeout değeri nedir?

dockup deploy --wait için varsayılan timeout 900 saniyedir ve dokümante edilen --timeout option'ı ile değiştirilebilir.

Agent needs_confirm durumuna nasıl tepki vermeli?

Durmalı ve explicit approval istemelidir. Bu code, istenen action'ın destructive olduğu ve bilerek çalıştırılmadığı anlamına gelir.