Mỗi cú nhấp trong giao diện Sharkly là một quyết định mà một người đã đưa ra: tạo Task này, gán Agent kia, kiểm tra một lượt chạy. Đó là giao diện phù hợp cho những quyết định cần phán đoán. Đó là giao diện sai cho lần lặp thứ một nghìn của cùng một quyết định. Một khi nhóm của bạn quyết định rằng mọi bản build hằng đêm thất bại đều phải trở thành một Task, việc một người nhấp qua các màn hình không còn là quy trình làm việc nữa mà trở thành việc vặt.
Đây là lúc bề mặt lập trình xuất hiện. Sharkly CLI cho phép con người, agent và script làm việc với Sharkly từ terminal: quản lý tài nguyên tổ chức, đăng ký một Computer để agent thực thi, kiểm tra dịch vụ cục bộ và tự động hóa các quy trình có thể lặp lại. Đằng sau nó là REST API tại api.sharkly.ai, chấp nhận cùng loại personal access token mà CLI sử dụng.
Điều này quan trọng hơn đối với Sharkly so với một công cụ quản lý dự án thông thường, bởi Sharkly không chỉ là nơi công việc được mô tả. Đó là nơi công việc được thực thi. Sharkly bổ sung lớp task chung, Computer, ngữ cảnh, kiểm soát và đánh giá xung quanh các công cụ lập trình như Claude Code và Codex, vì vậy một lệnh sharkly task create được script hóa không chỉ tạo một ticket. Nếu Task được gán cho một Agent và đang ở trạng thái sẵn sàng, nó có thể bắt đầu một lượt chạy thực sự trên một Computer thực sự. Script hóa bề mặt cũng chính là script hóa lực lượng lao động.
Tóm tắt nhanh
Sharkly CLI (lệnh sharkly) cho phép con người, agent và script làm việc với Sharkly từ terminal, đồng thời cũng là cách dịch vụ cục bộ được cài đặt trên các host từ xa và Linux để chúng có thể tham gia đội Computer của bạn. Xác thực được tách một cách có chủ đích: personal access token (tiền tố shk_) đăng nhập cho con người hoặc script, install token dùng một lần (tiền tố sit_) đăng ký một Computer, và các lượt chạy Agent sử dụng thông tin xác thực thực thi có phạm vi do Sharkly cung cấp. Khi đã có token, script có thể tạo và chỉnh sửa Task, bình luận về chúng, kiểm tra các lượt chạy và log, đồng thời quản lý Computer, tất cả với --output json để phân tích sạch. Cùng token shk_ hoạt động như bearer token với REST API, và trigger webhook của Automation cho phép CI cùng các hệ thống bên ngoài khác bắt đầu các lượt chạy Agent bằng một yêu cầu POST.
Một nền tảng, hai bề mặt
Giao diện Sharkly và bề mặt lập trình của nó là hai lối vào cùng một hệ thống. Task mà script của bạn tạo cũng chính là Task mà đồng đội nhìn thấy trên bảng, với cùng trạng thái, Workflow, bình luận và lịch sử thực thi. Script hóa không bao giờ đi vòng qua bản ghi chung: tự động hóa cung cấp dữ liệu cho hệ thống bản ghi.
Một cách hữu ích để phân biệt hai bề mặt là dựa vào việc ai đang quyết định. Dùng UI khi một người đang đưa ra phán đoán: định hình yêu cầu, xem xét một diff, chấp nhận kết quả. Dùng CLI hoặc API khi quyết định đã được đưa ra và chỉ còn các thao tác lặp lại: tạo Task từ hệ thống giám sát, kéo log lượt chạy vào dashboard, kiểm tra tình trạng Computer từ một cron job. Một script có thể tạo Task và thậm chí kích hoạt lượt chạy, nhưng việc chấp nhận vẫn thuộc về con người.
Cài đặt CLI và những gì nó cài đặt
Trên macOS hoặc Linux, trình cài đặt chính thức chỉ gồm một lệnh:
curl -fsSL https://file-assets.sharkly.ai/download/install.sh | bash
Windows có trình cài đặt PowerShell chính thức, hiện chỉ hỗ trợ AMD64. Trên mọi nền tảng, hãy xác minh và duy trì bản cài đặt bằng:
sharkly version
sharkly update
CLI còn đóng một vai trò thứ hai ngoài việc là một client. Tài liệu mô tả hai cách để kết nối một Computer: cài Sharkly Desktop trên một máy tính cá nhân được hỗ trợ, hoặc cài Sharkly CLI và dịch vụ cục bộ trên một host từ xa hoặc máy Linux. Cách thứ hai là cách một máy chủ build, một máy Linux nhàn rỗi hoặc một container trở thành năng lực thực thi cho các Agent của bạn. Dịch vụ cục bộ mà nó thiết lập sẽ đăng ký Computer, phát hiện các Runtime đã cài đặt, gửi heartbeat, nhận các lượt chạy trong hàng đợi, chuẩn bị thư mục task và truyền tiến độ trở lại, đồng thời tự khởi tạo kết nối nên không cần cổng vào.
Nếu bạn vẫn đang kết nối máy đầu tiên qua UI, hướng dẫn bắt đầu sẽ trình bày luồng đó.
Ba loại thông tin xác thực, ba nhiệm vụ
Sharkly sử dụng các thông tin xác thực riêng biệt cho từng mục đích riêng, và bạn nên nắm rõ sự tách biệt này trước khi tự động hóa bất cứ thứ gì.
Personal access token bắt đầu bằng shk_ và cho phép CLI, script hoặc một client đáng tin cậy khác hoạt động như tài khoản người dùng của bạn. Bạn tạo token trong Cài đặt, chọn thời hạn 30 ngày, 90 ngày, 1 năm hoặc không hết hạn, và sao chép toàn bộ giá trị ngay khi tạo. Đăng nhập bằng luồng dựa trên prompt để token không bao giờ lọt vào lịch sử shell:
sharkly login --token
sharkly auth status
Install token cho computer bắt đầu bằng sit_, hết hạn sau 30 phút và chỉ có thể dùng đúng một lần. Nhiệm vụ duy nhất của nó là đăng ký một Computer:
sharkly computer register --install-token sit_...
Thông tin xác thực thứ ba mà bạn không bao giờ phải xử lý: một lượt chạy Agent đang hoạt động sẽ nhận được thông tin xác thực thực thi có phạm vi do Sharkly cung cấp, giới hạn trong các nhóm lệnh mà ngữ cảnh thực thi của nó cho phép.
Tài liệu vạch rõ ranh giới: personal access token không đăng ký computer, và install token không tạo đăng nhập CLI cho con người. Việc đăng ký tạo ra một phiên dịch vụ cục bộ độc lập, đó là lý do vì sao việc thu hồi personal token sau này không khiến các Computer đã đăng ký của bạn offline. Tương tự, sharkly auth logout chỉ xóa token khỏi profile cục bộ của bạn; token vẫn hợp lệ trên server cho đến khi bạn thu hồi nó trong Cài đặt.
Với CI, hãy bỏ qua hoàn toàn luồng đăng nhập. CLI đọc token từ biến môi trường SHARKLY_TOKEN, biến này được ưu tiên hơn mọi profile đã lưu. Hãy nạp nó từ một kho bí mật được bảo vệ, chẳng hạn như GitHub Actions secrets, thay vì ghi nó vào tệp workflow, và chỉ rõ organization bằng --organization-id.
Quản lý đội Computer từ terminal
Sau khi các host được đăng ký, nhóm lệnh sharkly computer đảm nhiệm việc kiểm tra và bảo trì mà không cần trình duyệt:
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 hiển thị các Computer đã đăng ký cho tổ chức hiện tại, show trả về một Computer cùng các Runtime của nó, usage kiểm tra một Runtime cụ thể, ping kiểm tra xem Runtime đó có thể hoàn thành một vòng khứ hồi hay không, và update yêu cầu cập nhật CLI cho một Runtime. Sự khác biệt mà ping tồn tại để làm rõ: một Computer đang online chỉ có nghĩa là dịch vụ cục bộ của nó đang gửi heartbeat, chứ không có nghĩa là một Runtime nhất định có thể thực thi một lượt chạy ngay lúc này.
Trên chính host đó, việc chẩn đoán thường ngày sử dụng các lệnh dành cho người dùng:
sharkly computer status --output json
sharkly computer logs --lines 100
Namespace daemon cung cấp các điều khiển vòng đời tiến trình và dung lượng đĩa, bao gồm sharkly daemon disk-usage và sharkly daemon cleanup, trong đó cleanup là chạy thử trừ khi bạn thêm --confirm. Quy tắc quyết định của tài liệu: ưu tiên computer status và computer logs cho chẩn đoán thường ngày, chỉ dùng daemon khi bạn cần vòng đời tiến trình, báo cáo dung lượng đĩa hoặc dọn dẹp. Bài Computers trong loạt bài này đi sâu hơn về quyền sở hữu, khả năng hiển thị và chính sách dọn dẹp.
Script hóa Task: công việc đến mà không cần một cuộc họp
Task là nơi CLI khẳng định vị trí của mình trong một pipeline. Nhóm lệnh này giống như phiên bản có thể script hóa của bảng:
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
Trường hợp sử dụng CI rõ ràng nhất là tự động tạo công việc. Một job chạy hằng đêm phát hiện bản phát hành thất bại không cần người điền vào biểu mẫu:
sharkly task create \
--title "Investigate the failed release" \
--body-file ./task-body.md \
--output json
Dùng --body-file hoặc --body-stdin mỗi khi nội dung chính xác quan trọng, vì dạng --body ngắn sẽ giải mã các chuỗi escape. Và bởi vì một Task được gán cho Agent sẽ khởi động một lượt chạy khi nó ở trạng thái sẵn sàng, chỉ một lệnh đó có thể là điểm đầu của một vòng lặp hoàn toàn tự động: script tạo Task, Agent được gán nhận nó, rồi quá trình thực thi, các điểm chặn và kết quả quay trở lại Task để một người xem xét vào sáng hôm sau.
Các script báo cáo có bộ lọc thực sự thay vì phải sàng lọc phía client. Bạn có thể lọc theo thời gian ở trạng thái với --status-changed-within 7d, và theo trường tùy chỉnh:
sharkly task list --space HF --field "Customer Tier=VIP" --output json
Các cờ --field lặp lại được kết hợp bằng AND, việc khớp là nhận biết kiểu và chính xác, và việc lọc diễn ra trên server trước khi phân trang. Hãy áp dụng toàn bộ quy ước script hóa của tài liệu: yêu cầu --output json một cách rõ ràng, thêm --color never và --quiet, giữ --organization-id hiển thị, và dùng set -euo pipefail. Mã thoát mang tính ràng buộc: 0 là thành công, 1 là lỗi lệnh, kiểm tra hợp lệ, xác thực hoặc API từ xa, và 2 là các điều kiện tạm thời của dịch vụ cục bộ hoặc mạng, giúp logic thử lại trở nên đơn giản.
CLI cũng tự mô tả chính nó. sharkly schema task create --format json hiển thị registry lệnh ở dạng máy đọc được, và sharkly tldr task đưa ra các tình huống được tuyển chọn, điều này quan trọng khi thứ viết script lại chính là một agent.
Theo dõi các lượt chạy mà không cần mở dashboard
Quá trình thực thi có thể quan sát được qua cùng bề mặt đó:
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
Cờ --since giúp việc polling trở nên hợp lý: một script giám sát ghi lại số sequence đã xử lý lần cuối và chỉ lấy các message mới hơn trong mỗi lần chạy. Kết hợp điều đó với sharkly agent list, sharkly automation view và sharkly automation runs, bạn có thể dựng một trang trạng thái cho đội agent của mình chỉ bằng một shell script và jq.
REST API và webhook
Mọi thứ CLI làm đều dựa trên REST API, và tài liệu chỉ ra đường đi trực tiếp: gửi personal access token của bạn dưới dạng bearer token qua HTTPS.
curl -fsS https://api.sharkly.ai/rest/v1/users/current \
-H "Authorization: Bearer ${SHARKLY_TOKEN}"
Quyền truy cập qua API bị giới hạn bởi quyền của người dùng đứng sau token; mô hình token hiện tại không có lựa chọn phạm vi theo từng token, đó là lý do chính đáng để tạo một token riêng cho mỗi service với thời hạn xác định. Tài liệu tham chiếu endpoint nằm tại docs.sharkly.ai, và các phản hồi --output json của CLI là bản xem trước trung thực về các cấu trúc bạn sẽ làm việc cùng.
Lưu lượng cũng chảy theo chiều ngược lại. Một Automation có thể mang trigger webhook: Sharkly tạo một URL bí mật chấp nhận yêu cầu POST, và một yêu cầu hợp lệ sẽ khởi động lượt chạy Agent hoặc Crew của Automation. URL đầy đủ chỉ hiển thị một lần và mặc định hoạt động như một bearer secret, với tùy chọn xác minh chữ ký. Đây là nửa đầu vào của câu chuyện CI: pipeline của bạn thông báo cho Sharkly “có chuyện xảy ra, hãy chạy Agent triage.”
Cần nói chính xác về việc bề mặt này không phải là gì. Sharkly CLI không phải một coding agent khác, và API không phải một model endpoint. Các Runtime như Claude Code và Codex thực hiện việc thực thi; bề mặt lập trình của Sharkly quản lý lớp xung quanh chúng. Tính trung lập đó tách nó khỏi các lựa chọn gắn với hệ sinh thái như GitHub Agent HQ, nơi bề mặt tự động hóa và việc thực thi nằm trong bức tường của một nhà cung cấp.
Bắt đầu từ đâu
Hãy bắt đầu nhỏ hơn bạn nghĩ. Tạo một personal access token có thời hạn 90 ngày, chạy sharkly login --token, và script hóa thao tác đọc nhàm chán nhất bạn làm mỗi ngày, chẳng hạn như danh sách task được pipe qua jq thành bản tóm tắt buổi sáng. Các thao tác đọc thì an toàn và giúp bạn học các cấu trúc JSON. Sau đó tự động hóa một thao tác ghi với trigger rõ ràng, như tạo Task từ một job CI thất bại. Chỉ nối trigger webhook sau khi cả hai đã trở nên quen thuộc.
Mô hình cần giữ lại là mô hình mà toàn bộ nền tảng được xây dựng trên đó: script và Agent tạo ra và thực thi công việc, còn ngữ cảnh, tiến độ, điểm chặn, kết quả và đánh giá của con người vẫn hiển thị từ yêu cầu đến phát hành. Tự động hóa các lối vào. Giữ lại việc đánh giá.
Câu hỏi thường gặp
Tôi có cần CLI để dùng Sharkly không?
Không. Sharkly Desktop đảm nhiệm việc kết nối máy tính cá nhân, còn ứng dụng web đảm nhiệm công việc Task hằng ngày. CLI trở nên cần thiết khi bạn kết nối một host từ xa hoặc máy Linux, vì cài Sharkly CLI và dịch vụ cục bộ là đường thiết lập được tài liệu hóa cho trường hợp đó; và nó trở nên hữu ích bất cứ khi nào một quy trình lặp lại đủ nhiều đến mức việc nhấp qua các màn hình trở thành một khoản chi phí.
Sự khác biệt giữa personal access token và install token là gì?
Personal access token (tiền tố shk_) xác thực một người hoặc một script với tư cách tài khoản người dùng của bạn, dùng cho đăng nhập CLI, job CI và yêu cầu API trực tiếp. Install token cho computer (tiền tố sit_) dùng một lần và có thời gian sống ngắn, hết hạn sau 30 phút, và chỉ đăng ký một Computer. Không loại nào thay thế được loại kia.
Tôi có thể gọi trực tiếp REST API của Sharkly thay vì dùng CLI không?
Có. Gửi personal access token dưới dạng bearer token qua HTTPS đến api.sharkly.ai; tài liệu đưa ra mẫu curl -fsS https://api.sharkly.ai/rest/v1/users/current với header Authorization: Bearer. Token mang quyền của tài khoản người dùng của bạn.
Làm thế nào để tạo Task từ pipeline CI?
Lưu một token shk_ dưới dạng secret CI được bảo vệ và đưa nó ra biến môi trường SHARKLY_TOKEN, biến này CLI tự động đọc. Sau đó chạy sharkly task create với --title, --body-file cho nội dung nhiều dòng chính xác, --organization-id rõ ràng và --output json để job có thể bắt lấy ID của Task đã tạo.
Việc thu hồi personal access token có làm dừng các Computer đã đăng ký của tôi không?
Không. Việc đăng ký Computer tạo ra một phiên dịch vụ cục bộ độc lập thông qua install token, vì vậy thu hồi personal access token không làm dừng các Computer đó. Việc thu hồi có vô hiệu hóa token ở mọi nơi nó được dùng cho các yêu cầu CLI, API và automation, đó là lý do vì sao việc xoay vòng token nên cập nhật các script phụ thuộc trước khi token cũ bị thu hồi.
