Sharkly UI'daki her tıklama, bir kişinin verdiği bir karardır: bu Task'ı oluştur, şu Agent'a ata, bir run'ı kontrol et. Bu, değerlendirme gerektiren kararlar için doğru arayüzdür. Aynı çağrının bininci tekrarı içinse yanlış arayüzdür. Ekibiniz başarısız gece derlemelerinin her birinin bir Task'a dönüşmesi gerektiğine karar verdikten sonra, ekranlarda tıklayıp duran bir kişi artık bir workflow değil, bir angarya haline gelir.
İşte programatik yüzey burada devreye girer. Sharkly CLI, insanların, Agent'ların ve betiklerin Sharkly ile bir terminalden çalışmasını sağlar: organizasyon kaynaklarını yönetin, Agent yürütmesi için bir Computer kaydedin, yerel servisi inceleyin ve tekrarlanabilir workflow'ları otomatikleştirin. Arkasında, CLI'nın kullandığı aynı kişisel erişim token'larını kabul eden bir REST API, api.sharkly.ai adresinde bulunur.
Bu, Sharkly için tipik bir proje yönetimi aracından daha önemlidir; çünkü Sharkly yalnızca işin tanımlandığı yer değildir. İşin yürütüldüğü yerdir. Sharkly, Claude Code ve Codex gibi kodlama araçlarının etrafına paylaşılan task, Computer, bağlam, kontrol ve inceleme katmanını ekler; böylece betiklenmiş bir sharkly task create yalnızca bir bilet açmaz. Task bir Agent'a atanmışsa ve hazır durumda bekliyorsa, gerçek bir Computer üzerinde gerçek bir run başlatabilir. Yüzeyi betiklemek, iş gücünü betiklemek anlamına gelir.
Kısa Özet
Sharkly CLI (sharkly komutu), insanların, Agent'ların ve betiklerin Sharkly ile bir terminalden çalışmasını sağlar; ayrıca yerel servisin uzak ve Linux ana makinelere kurulma yoludur, böylece bu makineler Computer olarak filonuza katılabilir. Kimlik doğrulama bilinçli olarak ayrılmıştır: bir kişisel erişim token'ı (shk_ öneki) bir insanın veya betiğin oturum açmasını sağlar, tek kullanımlık bir kurulum token'ı (sit_ öneki) bir Computer kaydeder ve Agent run'ları Sharkly tarafından sağlanan kapsamlandırılmış bir yürütme kimlik bilgisi kullanır. Bir token hazır olduğunda betikler Task oluşturabilir ve düzenleyebilir, onlara yorum yapabilir, run'ları ve logları inceleyebilir ve Computer'ları yönetebilir; hepsi temiz ayrıştırma için --output json ile yapılabilir. Aynı shk_ token'ı REST API'ye karşı bearer token olarak çalışır ve Automation webhook tetikleyicileri, CI ve diğer harici sistemlerin bir POST isteğiyle Agent run'ları başlatmasını sağlar.
Tek platform, iki yüzey
Sharkly'nin UI'si ve programatik yüzeyi, aynı sisteme açılan iki kapıdır. Betiğinizin oluşturduğu Task, bir ekip arkadaşınızın panoda gördüğü aynı Task'tır; aynı durum, Workflow, yorumlar ve yürütme geçmişine sahiptir. Betikleme, paylaşılan kaydın etrafından asla dolaşmaz: otomasyon, kayıt sistemini besler.
İkisini ayırmanın faydalı bir yolu, kararı kimin verdiğine bakmaktır. Bir kişi değerlendirme gerektiren bir karar verirken UI'yı kullanın: bir gereksinimi şekillendirmek, bir diff'i incelemek, bir sonucu kabul etmek. Karar zaten verilmişse ve yalnızca mekanik işler tekrarlanıyorsa CLI veya API'yi kullanın: bir izleme sisteminden Task kaydetmek, run loglarını bir gösterge paneline çekmek, bir cron job'dan Computer sağlığını kontrol etmek. Bir betik Task'ı oluşturabilir ve hatta run'ı tetikleyebilir, ancak kabul bir kişide kalır.
CLI'yı kurmak ve kurduğu bileşenler
macOS veya Linux'ta resmi yükleyici tek komuttur:
curl -fsSL https://file-assets.sharkly.ai/download/install.sh | bash
Windows için resmi bir PowerShell yükleyicisi vardır, şu anda yalnızca AMD64. Her platformda kurulumu şunlarla doğrulayın ve bakımını yapın:
sharkly version
sharkly update
CLI, bir istemci olmanın ötesinde ikinci bir rol oynar. Dokümanlar bir Computer'ı bağlamak için iki yol tanımlar: desteklenen bir kişisel bilgisayara Sharkly Desktop kurun veya uzak bir ana makineye ya da Linux bilgisayara Sharkly CLI ve yerel servisi kurun. Bu ikinci yol, bir build sunucusunun, yedek bir Linux makinesinin veya bir konteynerin Agent'larınız için yürütme kapasitesi haline gelme yoludur. Kurduğu yerel servis Computer'ı kaydeder, kurulu Runtime'ları algılar, kalp atışı sinyalleri gönderir, kuyruktaki run'ları alır, task dizinlerini hazırlar ve ilerlemeyi geri akıtır; bağlantıyı kendisi başlattığı için gelen bağlantı portu gerekmez.
İlk makinenizi hâlâ UI üzerinden bağlıyorsanız, başlangıç kılavuzu bu akışı ele alır.
Üç kimlik bilgisi, üç iş
Sharkly, farklı amaçlar için ayrı kimlik bilgileri kullanır ve herhangi bir şeyi otomatikleştirmeden önce bu ayrımı özümsemeye değer.
Bir kişisel erişim token'ı shk_ ile başlar ve CLI'nın, bir betiğin veya başka bir güvenilir istemcinin kullanıcı hesabınız olarak hareket etmesini sağlar. Ayarlar'da bir tane oluşturur, 30 gün, 90 gün, 1 yıl veya süresiz bir son kullanma tarihi seçer ve oluşturma sırasında tam değeri bir kez kopyalarsınız. Token'ın shell geçmişine düşmemesi için istem tabanlı akışla oturum açın:
sharkly login --token
sharkly auth status
Bir bilgisayar kurulum token'ı sit_ ile başlar, 30 dakika sonra sona erer ve tam olarak bir kez kullanılabilir. Tek işi bir Computer kaydetmektir:
sharkly computer register --install-token sit_...
Üçüncü kimlik bilgisini hiç elinize almazsınız: aktif bir Agent run'ı, Sharkly tarafından sağlanan ve yürütme bağlamının izin verdiği komut aileleriyle sınırlı, kapsamlandırılmış bir yürütme kimlik bilgisi alır.
Dokümanlar sınırı net bir şekilde çizer: kişisel erişim token'ı bir bilgisayar kaydetmez ve kurulum token'ı bir insan CLI oturumu oluşturmaz. Kayıt, bağımsız bir yerel servis oturumu oluşturur; bu nedenle kişisel token'ınızı sonradan iptal etmeniz kayıtlı Computer'larınızı çevrimdışı bırakmaz. Aynı şekilde, sharkly auth logout yalnızca token'ı yerel profilinizden temizler; siz Ayarlar'da iptal edene kadar token sunucuda geçerli kalır.
CI için oturum açma akışını tamamen atlayın. CLI, token'ı SHARKLY_TOKEN ortam değişkeninden okur; bu değişken kayıtlı herhangi bir profilden önceliklidir. Token'ı workflow dosyasına yazmak yerine GitHub Actions secrets gibi korumalı bir gizli bilgi deposundan doldurun ve organizasyonu --organization-id ile açıkça belirtin.
Computer filosunu terminalden yönetmek
Ana makineler kaydedildikten sonra sharkly computer komut grubu, tarayıcı olmadan inceleme ve bakımı kapsar:
sharkly computer list --output json
sharkly computer show <computer-id> --output json
sharkly computer usage <computer-id> <runtime-id> --days 30 --output json
sharkly computer ping <computer-id> <runtime-id> --wait --output json
sharkly computer update <computer-id> <runtime-id>
list geçerli organizasyon için kayıtlı Computer'ları gösterir, show Runtime'larıyla birlikte tek bir Computer döndürür, usage belirli bir Runtime'ı inceler, ping o Runtime'ın gidiş-dönüşü tamamlayıp tamamlayamadığını kontrol eder ve update bir Runtime için CLI güncellemesi ister. ping'in var olma nedeni şu ayrımdır: Bir Computer'ın çevrimiçi olması yalnızca yerel servisinin kalp atışı gönderdiği anlamına gelir; belirli bir Runtime'ın şu anda bir run yürütebileceği anlamına gelmez.
Ana makinenin kendisinde rutin teşhis, kullanıcıya yönelik komutları kullanır:
sharkly computer status --output json
sharkly computer logs --lines 100
daemon ad alanı süreç yaşam döngüsü ve disk kontrollerini sunar; buna sharkly daemon disk-usage ve sharkly daemon cleanup dahildir; ikincisi --confirm eklemediğiniz sürece kuru çalıştırmadır. Dokümanların karar kuralı: Rutin teşhis için computer status ve computer logs tercih edin; daemon komutuna yalnızca süreç yaşam döngüsü, disk raporlama veya temizleme gerektiğinde başvurun. Bu serideki Computers yazısı sahiplik, görünürlük ve temizleme politikalarına daha derinlemesine iner.
Task'ları betiklemek: toplantı olmadan gelen iş
CLI'nın bir pipeline'da yer edinmesini sağlayan şey Task'lardır. Komut ailesi, panonun betiklenebilir bir sürümü gibi görünür:
sharkly task list --output json
sharkly task search "authentication error" --output json
sharkly task create --title "Investigate authentication error" --output json
sharkly task edit <task-id> --status <status> --output json
sharkly task comment <task-id> --body "Investigation started." --output json
Bariz CI kullanım senaryosu, işi otomatik olarak kaydetmektir. Başarısız bir sürümü algılayan gece çalışan bir iş, formu dolduran bir kişiye ihtiyaç duymaz:
sharkly task create \
--title "Investigate the failed release" \
--body-file ./task-body.md \
--output json
Tam içerik önemli olduğunda --body-file veya --body-stdin kullanın; çünkü kısa --body biçimi kaçış dizilerini çözer. Üstelik bir Agent'a atanan bir Task hazır durumda beklediğinde bir run başlattığı için bu tek komut, tamamen otomatikleştirilmiş bir döngünün başlangıcı olabilir: Betik Task'ı kaydeder, atanan Agent onu üstlenir ve yürütme, engeller ve sonuç Task'a döner; ertesi sabah bir kişi bunları inceler.
Raporlama betikleri, istemci tarafında ayıklama yerine gerçek filtreler alır. Durum yaşına göre --status-changed-within 7d ile ve özel alanlara göre filtreleyebilirsiniz:
sharkly task list --space HF --field "Customer Tier=VIP" --output json
Yinelenen --field bayrakları AND ile birleştirilir; eşleştirme türüne duyarlı ve tamdır ve filtreleme sayfalamadan önce sunucuda gerçekleşir. Dokümanların betikleme kurallarını olduğu gibi benimseyin: açıkça --output json isteyin, --color never ve --quiet ekleyin, --organization-id görünür tutun ve set -euo pipefail kullanın. Çıkış kodları sözleşmeseldir: başarı için 0, komut, doğrulama, kimlik doğrulama veya uzak API hataları için 1 ve geçici yerel servis ya da ağ koşulları için 2; bu da yeniden deneme mantığını kolaylaştırır.
CLI ayrıca kendini tanımlar. sharkly schema task create --format json komut kayıt defterini makine tarafından okunabilir biçimde sunar ve sharkly tldr task derlenmiş senaryoları gösterir; bu, betiği yazan şeyin kendisi bir Agent olduğunda önemlidir.
Gösterge panelini açmadan run'ları izlemek
Yürütme, aynı yüzey üzerinden gözlemlenebilir:
sharkly run list --task <task-id> --output json
sharkly run view <run-id> --output json
sharkly run log <run-id> --since <sequence> --output json
sharkly run cancel <run-id> --output json
--since bayrağı yoklamayı mantıklı hale getirir: bir izleme betiği, işlenen son dizi numarasını kaydeder ve her geçişte yalnızca daha yeni mesajları alır. Bunu sharkly agent list, sharkly automation view ve sharkly automation runs ile birleştirin; bir shell betiği ve jq ile Agent iş gücünüz için bir durum sayfası oluşturabilirsiniz.
REST API ve webhook'lar
CLI'nın yaptığı her şey REST API üzerinden çalışır ve dokümanlar doğrudan yolu gösterir: kişisel erişim token'ınızı HTTPS üzerinden bearer token olarak gönderin.
curl -fsS https://api.sharkly.ai/rest/v1/users/current \
-H "Authorization: Bearer ${SHARKLY_TOKEN}"
API üzerinden erişim, token'ın arkasındaki kullanıcının izinleriyle sınırlıdır; mevcut token modelinde token başına kapsam seçimi yoktur; bu da her servis için tanımlı bir son kullanma süresine sahip ayrı bir token oluşturmak için iyi bir nedendir. Uç nokta referansı docs.sharkly.ai adresinde bulunur ve CLI'nın --output json yanıtları, üzerinde çalışacağınız şekillerin sadık bir önizlemesidir.
Trafik ters yönde de akar. Bir Automation bir webhook tetikleyicisi taşıyabilir: Sharkly, POST isteğini kabul eden gizli bir URL üretir ve geçerli bir istek, Automation'ın Agent veya Crew run'ını başlatır. Tam URL bir kez gösterilir ve varsayılan olarak bir bearer secret işlevi görür; isteğe bağlı imza doğrulaması vardır. Bu, CI hikâyesinin gelen yarısıdır: pipeline'ınız Sharkly'ye “bir şey oldu, triage Agent'ını çalıştır” der.
Bu yüzeyin ne olmadığı konusunda net olmakta fayda var. Sharkly CLI başka bir kodlama Agent'ı değildir ve API bir model uç noktası değildir. Claude Code ve Codex gibi Runtime'lar yürütmeyi gerçekleştirir; Sharkly'nin programatik yüzeyi ise onların etrafındaki katmanı yönetir. Bu tarafsızlık, onu GitHub Agent HQ gibi ekosisteme bağlı seçeneklerden ayırır; orada otomasyon yüzeyi ve yürütme tek bir satıcının duvarları içinde yaşar.
Nereden başlamalı
Düşündüğünüzden daha küçük başlayın. 90 gün geçerli bir kişisel erişim token'ı oluşturun, sharkly login --token çalıştırın ve her gün yaptığınız en sıkıcı okuma işini betikleyin; örneğin bir task listesini jq üzerinden sabah özetine aktarmak gibi. Okumalar güvenlidir ve size JSON şekillerini öğretir. Ardından bariz bir tetikleyiciyle bir yazma işlemini otomatikleştirin; örneğin başarısız bir CI işinden Task oluşturmak gibi. Webhook tetikleyicisini yalnızca her ikisi de rutin hale geldikten sonra bağlayın.
Korunması gereken desen, tüm platformun üzerine inşa edildiği desendir: Betikler ve Agent'lar işi üretir ve yürütür; bağlam, ilerleme, engeller, sonuçlar ve insan incelemesi istekten sürüme kadar görünür kalır. Giriş noktalarını otomatikleştirin. İnsan incelemesini koruyun.
SSS
Sharkly'yi kullanmak için CLI'ya ihtiyacım var mı?
Hayır. Sharkly Desktop kişisel bir bilgisayarı bağlamayı kapsar ve web uygulaması günlük Task işlerini kapsar. CLI, uzak bir ana makineyi veya Linux bilgisayarı bağladığınızda gerekli hale gelir; çünkü orada belgelenen kurulum yolu Sharkly CLI ve yerel servisi kurmaktır. Bir workflow, tıklayarak geçmek maliyet haline gelecek kadar sık tekrarlanıyorsa da CLI değerli hale gelir.
Kişisel erişim token'ı ile kurulum token'ı arasındaki fark nedir?
Kişisel erişim token'ı (shk_ öneki) bir insanı veya betiği kullanıcı hesabınız olarak doğrular; CLI oturum açmaları, CI işleri ve doğrudan API istekleri için kullanılır. Bilgisayar kurulum token'ı (sit_ öneki) tek kullanımlıktır ve kısa ömürlüdür; 30 dakika sonra sona erer ve yalnızca bir Computer kaydeder. Biri diğerinin yerini tutmaz.
CLI'yı kullanmak yerine Sharkly REST API'sini doğrudan çağırabilir miyim?
Evet. Kişisel erişim token'ınızı HTTPS üzerinden api.sharkly.ai adresine bearer token olarak gönderin; dokümanlar desen olarak Authorization: Bearer başlığıyla birlikte curl -fsS https://api.sharkly.ai/rest/v1/users/current komutunu gösterir. Token, kullanıcı hesabınızın izinlerini taşır.
Bir CI pipeline'ından nasıl Task oluştururum?
Bir shk_ token'ını korumalı bir CI gizli bilgisi olarak saklayın ve CLI'nın otomatik olarak okuduğu SHARKLY_TOKEN ortam değişkeni olarak açığa çıkarın. Ardından sharkly task create komutunu --title, tam çok satırlı içerik için --body-file, açık bir --organization-id ve işin oluşturulan Task'ın kimliğini yakalayabilmesi için --output json ile çalıştırın.
Kişisel erişim token'ımı iptal etmek kayıtlı Computer'larımı durdurur mu?
Hayır. Computer kaydı, kurulum token'ı aracılığıyla bağımsız bir yerel servis oturumu oluşturur; bu nedenle kişisel erişim token'ının iptal edilmesi o Computer'ları durdurmaz. Ancak iptal, token'ı CLI, API ve otomasyon isteklerinde kullanıldığı her yerde geçersiz kılar; bu nedenle rotasyon, eski token iptal edilmeden önce bağımlı betikleri güncellemelidir.
