Setiap klik di UI Sharkly adalah keputusan yang dibuat manusia: buat Task ini, tugaskan Agent itu, pantau sebuah run. Itulah antarmuka yang tepat untuk pengambilan keputusan. Namun antarmuka itu salah untuk pengulangan keputusan yang sama hingga keseribu kalinya. Begitu tim Anda memutuskan bahwa setiap build malam yang gagal harus menjadi Task, orang yang mengklik layar demi layar berhenti menjadi bagian dari alur kerja dan mulai menjadi pekerjaan rutin yang melelahkan.
Di sinilah antarmuka programatik berperan. CLI Sharkly memungkinkan manusia, agent, dan skrip bekerja dengan Sharkly dari terminal: mengelola sumber daya organisasi, mendaftarkan Computer untuk eksekusi agent, memeriksa layanan lokal, dan mengotomatiskan alur kerja yang berulang. Di belakangnya berdiri REST API di api.sharkly.ai yang menerima personal access token yang sama dengan yang dipakai CLI.
Hal ini lebih penting bagi Sharkly dibandingkan alat PM pada umumnya, karena Sharkly bukan sekadar tempat pekerjaan diuraikan. Sharkly adalah tempat pekerjaan dieksekusi. Sharkly menambahkan lapisan task bersama, Computer, konteks, kontrol, dan tinjauan di sekitar alat coding seperti Claude Code dan Codex, sehingga sharkly task create yang dijalankan lewat skrip tidak hanya mengajukan tiket. Jika Task tersebut ditugaskan ke sebuah Agent dan berada dalam status siap, perintah itu dapat memulai run sungguhan di Computer sungguhan. Menuliskan skrip untuk antarmuka ini berarti menuliskan skrip untuk tenaga kerja Anda.
TL;DR
CLI Sharkly (perintah sharkly) memungkinkan manusia, agent, dan skrip bekerja dengan Sharkly dari terminal, dan CLI ini juga menjadi cara layanan lokal dipasang di host remote dan Linux agar bisa bergabung ke armada Anda sebagai Computer. Autentikasinya sengaja dipisah: personal access token (awalan shk_) untuk login manusia atau skrip, install token sekali pakai (awalan sit_) untuk mendaftarkan Computer, dan run Agent menggunakan kredensial eksekusi terbatas yang disediakan Sharkly. Dengan token yang sudah siap, skrip dapat membuat dan mengedit Task, memberi komentar padanya, memeriksa run dan log, serta mengelola Computer, semuanya dengan --output json agar mudah diurai. Token shk_ yang sama berfungsi sebagai bearer token terhadap REST API, dan pemicu webhook Automation memungkinkan CI serta sistem eksternal lain memulai run Agent dengan permintaan POST.
Satu platform, dua antarmuka
UI Sharkly dan antarmuka programatiknya adalah dua pintu masuk ke sistem yang sama. Task yang dibuat skrip Anda adalah Task yang sama yang dilihat rekan tim di board, dengan status, Workflow, komentar, dan riwayat eksekusi yang sama. Penulisan skrip tidak pernah memintas catatan bersama: otomatisasi justru mengisi sistem pencatatan.
Cara yang berguna untuk membedakan keduanya adalah berdasarkan siapa yang mengambil keputusan. Gunakan UI ketika manusia sedang menilai: merumuskan kebutuhan, meninjau diff, menerima hasil. Gunakan CLI atau API ketika keputusan sudah diambil dan hanya mekanismenya yang berulang: mengajukan Task dari sistem pemantauan, menarik log run ke dasbor, memeriksa kesehatan Computer dari cron job. Skrip bisa membuat Task dan bahkan memicu run, tetapi penerimaan hasil tetap di tangan manusia.
Memasang CLI, dan apa yang dipasangnya
Di macOS atau Linux, installer resminya cukup satu perintah:
curl -fsSL https://file-assets.sharkly.ai/download/install.sh | bash
Windows memiliki installer PowerShell resmi, saat ini hanya untuk AMD64. Di platform apa pun, verifikasi dan pelihara instalasinya dengan:
sharkly version
sharkly update
CLI memainkan peran kedua di luar fungsinya sebagai klien. Dokumentasi menjelaskan dua jalur untuk menghubungkan Computer: pasang Sharkly Desktop di komputer pribadi yang didukung, atau pasang CLI Sharkly dan layanan lokal di host remote atau komputer Linux. Jalur kedua inilah yang membuat build server, komputer Linux cadangan, atau container menjadi kapasitas eksekusi bagi Agent Anda. Layanan lokal yang disiapkannya akan mendaftarkan Computer, mendeteksi Runtime yang terpasang, mengirim heartbeat, menerima run yang diantrekan, menyiapkan direktori task, dan mengalirkan progres kembali, sekaligus memulai koneksinya sendiri sehingga tidak diperlukan port masuk.
Jika Anda masih menghubungkan mesin pertama lewat UI, panduan memulai membahas alur tersebut.
Tiga kredensial, tiga fungsi
Sharkly menggunakan kredensial terpisah untuk tujuan yang berbeda, dan pemisahan ini perlu benar-benar dipahami sebelum Anda mengotomatiskan apa pun.
Personal access token diawali dengan shk_ dan memungkinkan CLI, skrip, atau klien tepercaya lain bertindak sebagai akun pengguna Anda. Anda membuatnya di Settings, memilih masa berlaku 30 hari, 90 hari, 1 tahun, atau tanpa kedaluwarsa, lalu menyalin nilai lengkapnya sekali saat pembuatan. Login dengan alur berbasis prompt agar token tidak pernah tercatat di riwayat shell:
sharkly login --token
sharkly auth status
Computer install token diawali dengan sit_, kedaluwarsa setelah 30 menit, dan hanya bisa dipakai satu kali. Tugasnya cuma satu: mendaftarkan Computer:
sharkly computer register --install-token sit_...
Kredensial ketiga tidak pernah Anda tangani sama sekali: run Agent yang aktif menerima kredensial eksekusi terbatas yang disediakan Sharkly, dibatasi pada kelompok perintah yang diizinkan oleh konteks eksekusinya.
Dokumentasi menegaskan batasnya secara gamblang: personal access token tidak mendaftarkan computer, dan install token tidak membuat login CLI untuk manusia. Pendaftaran membuat sesi layanan lokal yang independen, itulah sebabnya mencabut personal token Anda nanti tidak membuat Computer yang sudah terdaftar menjadi offline. Serupa dengan itu, sharkly auth logout hanya menghapus token dari profil lokal Anda; token tetap valid di server sampai Anda mencabutnya di Settings.
Untuk CI, lewati saja alur login sepenuhnya. CLI membaca token dari variabel lingkungan SHARKLY_TOKEN, yang diprioritaskan di atas profil apa pun yang tersimpan. Isi variabel itu dari penyimpanan rahasia yang terlindungi, misalnya GitHub Actions secrets, alih-alih menuliskannya ke dalam berkas workflow, dan nyatakan organisasi secara eksplisit dengan --organization-id.
Mengelola armada Computer dari terminal
Setelah host terdaftar, grup perintah sharkly computer menangani pemeriksaan dan pemeliharaan tanpa perlu browser:
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 menampilkan Computer yang terdaftar untuk organisasi saat ini, show mengembalikan satu Computer beserta Runtime-nya, usage memeriksa Runtime tertentu, ping memeriksa apakah Runtime tersebut bisa menyelesaikan round trip, dan update meminta pembaruan CLI untuk sebuah Runtime. Perbedaan inilah alasan ping ada: Computer yang online hanya berarti layanan lokalnya sedang mengirim heartbeat, bukan berarti Runtime tertentu dapat menjalankan run saat itu juga.
Di host itu sendiri, diagnosis rutin menggunakan perintah untuk pengguna:
sharkly computer status --output json
sharkly computer logs --lines 100
Namespace daemon menyediakan kontrol siklus hidup proses dan disk, termasuk sharkly daemon disk-usage dan sharkly daemon cleanup, yang merupakan dry run kecuali Anda menambahkan --confirm. Aturan keputusan menurut dokumentasi: utamakan computer status dan computer logs untuk diagnosis rutin, dan gunakan daemon hanya saat Anda memerlukan siklus hidup proses, laporan disk, atau pembersihan. Artikel Computers dalam seri ini membahas lebih dalam soal kepemilikan, visibilitas, dan kebijakan pembersihan.
Menulis skrip untuk Task: pekerjaan yang datang tanpa rapat
Task adalah tempat CLI membuktikan nilainya dalam sebuah pipeline. Keluarga perintahnya terasa seperti versi board yang bisa diskrip:
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
Kasus penggunaan CI yang paling jelas adalah mengajukan pekerjaan secara otomatis. Job malam yang mendeteksi rilis gagal tidak perlu manusia yang mengisi formulir:
sharkly task create \
--title "Investigate the failed release" \
--body-file ./task-body.md \
--output json
Gunakan --body-file atau --body-stdin setiap kali isi yang persis itu penting, karena bentuk singkat --body melakukan dekode terhadap escape sequence. Dan karena Task yang ditugaskan ke Agent akan memulai run saat berada dalam status siap, satu perintah itu bisa menjadi ujung depan dari siklus yang sepenuhnya otomatis: skrip mengajukan Task, Agent yang ditugaskan mengambilnya, lalu eksekusi, hambatan, dan hasilnya kembali ke Task tempat manusia meninjaunya keesokan paginya.
Skrip pelaporan mendapat filter sungguhan, bukan penyaringan di sisi klien. Anda bisa memfilter berdasarkan usia status dengan --status-changed-within 7d, dan berdasarkan custom field:
sharkly task list --space HF --field "Customer Tier=VIP" --output json
Flag --field yang diulang digabungkan dengan logika AND, pencocokannya sadar tipe dan bersifat persis, serta pemfilteran terjadi di server sebelum paginasi. Terapkan konvensi penulisan skrip dari dokumentasi secara menyeluruh: minta --output json secara eksplisit, tambahkan --color never dan --quiet, biarkan --organization-id terlihat, dan gunakan set -euo pipefail. Kode keluar bersifat mengikat: 0 untuk keberhasilan, 1 untuk kesalahan perintah, validasi, autentikasi, atau API jarak jauh, dan 2 untuk kondisi sementara pada layanan lokal atau jaringan, sehingga logika retry menjadi mudah.
CLI juga mendeskripsikan dirinya sendiri. sharkly schema task create --format json menampilkan registri perintah dalam bentuk yang bisa dibaca mesin, dan sharkly tldr task menyajikan skenario pilihan, yang penting ketika yang menulis skrip itu sendiri adalah sebuah agent.
Memantau run tanpa membuka dasbor
Eksekusi dapat diamati melalui antarmuka yang sama:
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
Flag --since membuat polling tetap masuk akal: skrip pemantauan mencatat nomor urut terakhir yang sudah diproses dan hanya mengambil pesan yang lebih baru pada setiap putaran. Padukan dengan sharkly agent list, sharkly automation view, dan sharkly automation runs, maka Anda bisa membuat halaman status untuk armada agent Anda hanya dari shell script dan jq.
REST API dan webhook
Semua yang dilakukan CLI berjalan di atas REST API, dan dokumentasi menunjukkan jalur langsungnya: kirim personal access token Anda sebagai bearer token melalui HTTPS.
curl -fsS https://api.sharkly.ai/rest/v1/users/current \
-H "Authorization: Bearer ${SHARKLY_TOKEN}"
Akses melalui API dibatasi oleh izin pengguna di balik token tersebut; model token saat ini tidak menyediakan pemilihan scope per token, yang menjadi alasan kuat untuk membuat token terpisah bagi setiap layanan dengan masa berlaku yang jelas. Referensi endpoint tersedia di docs.sharkly.ai, dan respons --output json dari CLI adalah pratinjau yang akurat atas struktur data yang akan Anda gunakan.
Lalu lintas data juga mengalir ke arah sebaliknya. Sebuah Automation dapat membawa pemicu webhook: Sharkly menghasilkan URL rahasia yang menerima permintaan POST, dan permintaan yang valid akan memulai run Agent atau Crew milik Automation tersebut. URL lengkapnya ditampilkan sekali dan secara default berfungsi sebagai bearer secret, dengan verifikasi tanda tangan sebagai opsi. Inilah separuh bagian masuk dari kisah CI: pipeline Anda memberi tahu Sharkly "ada yang terjadi, jalankan Agent triage."
Perlu juga diperjelas apa yang bukan merupakan antarmuka ini. CLI Sharkly bukan coding agent lain, dan API-nya bukan endpoint model. Runtime seperti Claude Code dan Codex yang melakukan eksekusi; antarmuka programatik Sharkly mengelola lapisan di sekitarnya. Netralitas itulah yang membedakannya dari opsi yang terikat ekosistem seperti GitHub Agent HQ, tempat antarmuka otomatisasi dan eksekusi berada di dalam dinding satu vendor.
Mulai dari mana
Mulailah lebih kecil dari yang Anda bayangkan. Buat personal access token dengan masa berlaku 90 hari, jalankan sharkly login --token, lalu skripkan pembacaan paling membosankan yang Anda lakukan setiap hari, misalnya daftar Task yang dialirkan melalui jq menjadi ringkasan pagi. Operasi baca itu aman, dan mengajarkan Anda struktur JSON. Setelah itu, otomatiskan satu operasi tulis dengan pemicu yang jelas, seperti membuat Task dari job CI yang gagal. Sambungkan pemicu webhook hanya setelah keduanya terasa rutin.
Pola yang harus dijaga adalah pola yang menjadi fondasi seluruh platform ini: skrip dan Agent menghasilkan serta mengeksekusi pekerjaan, sementara konteks, progres, hambatan, hasil, dan tinjauan manusia tetap terlihat dari permintaan hingga rilis. Otomatiskan pintu masuknya. Pertahankan tinjauannya.
FAQ
Apakah saya perlu CLI untuk menggunakan Sharkly?
Tidak. Sharkly Desktop menangani koneksi komputer pribadi, dan aplikasi web menangani pekerjaan Task sehari-hari. CLI menjadi wajib saat Anda menghubungkan host remote atau komputer Linux, karena memasang CLI Sharkly dan layanan lokal adalah jalur penyiapan yang didokumentasikan untuk itu, dan CLI menjadi berharga setiap kali sebuah alur kerja cukup sering berulang sehingga mengkliknya satu per satu menjadi biaya tersendiri.
Apa perbedaan personal access token dan install token?
Personal access token (awalan shk_) mengautentikasi manusia atau skrip sebagai akun pengguna Anda, untuk login CLI, job CI, dan permintaan API langsung. Computer install token (awalan sit_) bersifat sekali pakai dan berumur pendek, kedaluwarsa setelah 30 menit, dan hanya untuk mendaftarkan Computer. Keduanya tidak bisa saling menggantikan.
Bisakah saya memanggil REST API Sharkly secara langsung alih-alih menggunakan CLI?
Bisa. Kirim personal access token sebagai bearer token melalui HTTPS ke api.sharkly.ai; dokumentasi menunjukkan curl -fsS https://api.sharkly.ai/rest/v1/users/current dengan header Authorization: Bearer sebagai polanya. Token tersebut membawa izin dari akun pengguna Anda.
Bagaimana cara membuat Task dari pipeline CI?
Simpan token shk_ sebagai secret CI yang terlindungi dan ekspos sebagai variabel lingkungan SHARKLY_TOKEN, yang dibaca otomatis oleh CLI. Lalu jalankan sharkly task create dengan --title, --body-file untuk konten multibaris yang persis, --organization-id yang eksplisit, dan --output json agar job dapat menangkap ID Task yang dibuat.
Apakah mencabut personal access token saya menghentikan Computer yang sudah terdaftar?
Tidak. Pendaftaran Computer membuat sesi layanan lokal yang independen melalui install token, jadi mencabut personal access token tidak menghentikan Computer tersebut. Pencabutan memang membuat token tidak berlaku di semua tempat yang memakainya untuk permintaan CLI, API, dan otomatisasi, karena itu rotasi harus memperbarui skrip yang bergantung padanya sebelum token lama dicabut.
