Sharkly UI에서 이루어지는 모든 클릭은 사람이 내린 하나의 결정입니다. 이 Task를 만들고, 저 Agent를 배정하고, 실행 상태를 확인하는 것이죠. 판단이 필요한 순간에는 이 인터페이스가 제격입니다. 하지만 똑같은 판단을 천 번째 반복할 때는 맞지 않습니다. 팀에서 실패한 야간 빌드는 모두 Task로 만들기로 정했다면, 사람이 화면을 클릭해 넘기는 일은 더 이상 워크플로가 아니라 잡일이 됩니다.
바로 여기서 프로그래매틱 인터페이스가 필요해집니다. Sharkly CLI를 사용하면 사람, 에이전트, 스크립트가 터미널에서 Sharkly를 다룰 수 있습니다. 조직 리소스를 관리하고, 에이전트 실행을 위한 Computer를 등록하고, 로컬 서비스를 점검하고, 반복 가능한 워크플로를 자동화할 수 있죠. 그 뒤에는 api.sharkly.ai의 REST API가 있으며, CLI가 사용하는 것과 동일한 개인 액세스 토큰을 받아들입니다.
이는 일반적인 PM 도구보다 Sharkly에서 더 중요합니다. Sharkly는 단순히 작업을 기술하는 곳이 아니라, 작업이 실제로 실행되는 곳이기 때문입니다. Sharkly는 Claude Code, Codex 같은 코딩 도구 주위에 공유 Task, Computer, 컨텍스트, 제어, 리뷰 계층을 더해 줍니다. 따라서 스크립트로 실행하는 sharkly task create는 단순히 티켓을 접수하는 데 그치지 않습니다. Task가 Agent에 배정되어 있고 준비 상태에 있다면, 실제 Computer에서 실제 실행이 시작될 수 있습니다. 인터페이스를 스크립팅한다는 것은 곧 인력을 스크립팅한다는 뜻입니다.
TL;DR
Sharkly CLI(명령어 sharkly)를 사용하면 사람, 에이전트, 스크립트가 터미널에서 Sharkly를 다룰 수 있으며, 원격 및 Linux 호스트에 로컬 서비스를 설치해 해당 호스트가 여러분의 플릿에 Computer로 합류하도록 하는 방법이기도 합니다. 인증은 의도적으로 분리되어 있습니다. 개인 액세스 토큰(접두사 shk_)은 사람이나 스크립트를 로그인시키고, 일회성 설치 토큰(접두사 sit_)은 Computer를 등록하며, Agent 실행은 Sharkly가 제공하는 범위 제한된 실행 자격 증명을 사용합니다. 토큰만 준비되면 스크립트로 Task를 생성하고 편집하고, 댓글을 달고, 실행과 로그를 확인하고, Computer를 관리할 수 있으며, 모두 --output json으로 깔끔하게 파싱할 수 있습니다. 동일한 shk_ 토큰을 REST API의 베어러 토큰으로 사용할 수 있고, Automation 웹훅 트리거를 사용하면 CI 및 기타 외부 시스템이 POST 요청으로 Agent 실행을 시작할 수 있습니다.
하나의 플랫폼, 두 개의 인터페이스
Sharkly의 UI와 프로그래매틱 인터페이스는 같은 시스템으로 들어가는 두 개의 입구입니다. 스크립트가 만든 Task는 팀 동료가 보드에서 보는 것과 동일한 Task이며, 상태, 워크플로, 댓글, 실행 이력까지 같습니다. 스크립팅이 공유 기록을 우회하는 일은 없습니다. 자동화가 곧 시스템 오브 레코드에 데이터를 공급합니다.
둘을 나누는 유용한 기준은 ‘누가 결정하는가’입니다. 사람이 판단을 내리는 경우에는 UI를 사용하세요. 요구사항을 다듬고, diff를 리뷰하고, 결과를 승인하는 상황입니다. 결정이 이미 내려졌고 반복되는 작업만 남았을 때는 CLI나 API를 사용하세요. 모니터링 시스템에서 Task를 접수하고, 실행 로그를 대시보드로 가져오고, cron 작업에서 Computer 상태를 확인하는 상황입니다. 스크립트가 Task를 만들고 실행까지 트리거할 수 있지만, 승인은 사람의 몫으로 남습니다.
CLI 설치하기, 그리고 함께 설치되는 것들
macOS나 Linux에서는 공식 설치 프로그램이 명령어 하나면 됩니다:
curl -fsSL https://file-assets.sharkly.ai/download/install.sh | bash
Windows에는 공식 PowerShell 설치 프로그램이 있으며, 현재 AMD64만 지원합니다. 어느 플랫폼에서든 다음 명령으로 설치를 확인하고 유지 관리하세요:
sharkly version
sharkly update
CLI는 단순한 클라이언트 이상의 두 번째 역할을 합니다. 문서에는 Computer를 연결하는 두 가지 경로가 설명되어 있습니다. 지원되는 개인 컴퓨터에 Sharkly Desktop을 설치하거나, 원격 호스트나 Linux 컴퓨터에 Sharkly CLI와 로컬 서비스를 설치하는 것입니다. 두 번째 경로를 통해 빌드 서버나 여분의 Linux 장비, 컨테이너가 여러분의 Agent를 위한 실행 용량이 됩니다. 여기서 설정되는 로컬 서비스는 Computer를 등록하고, 설치된 Runtime을 감지하고, 하트비트를 보내고, 대기 중인 실행을 수신하고, 작업 디렉터리를 준비하고, 진행 상황을 다시 스트리밍합니다. 연결은 로컬 서비스가 먼저 시작하므로 인바운드 포트가 필요하지 않습니다.
아직 UI를 통해 첫 번째 머신을 연결하는 단계라면, 시작 가이드에서 그 흐름을 다룹니다.
세 가지 자격 증명, 세 가지 역할
Sharkly는 용도별로 자격 증명을 분리해 사용하며, 자동화를 시작하기 전에 이 분리를 확실히 이해해 두는 것이 좋습니다.
개인 액세스 토큰은 shk_로 시작하며, CLI나 스크립트 또는 다른 신뢰할 수 있는 클라이언트가 여러분의 사용자 계정으로 동작하도록 합니다. Settings에서 생성하고, 만료 기간은 30일, 90일, 1년 또는 무기한 중에서 선택하며, 생성 시 전체 값을 한 번만 복사할 수 있습니다. 토큰이 셸 기록에 남지 않도록 프롬프트 기반 흐름으로 로그인하세요:
sharkly login --token
sharkly auth status
컴퓨터 설치 토큰은 sit_로 시작하고 30분 후 만료되며, 정확히 한 번만 사용할 수 있습니다. 이 토큰의 유일한 역할은 Computer 등록입니다:
sharkly computer register --install-token sit_...
세 번째 자격 증명은 여러분이 직접 다룰 일이 전혀 없습니다. 활성 Agent 실행에는 Sharkly가 제공하는 범위 제한된 실행 자격 증명이 부여되며, 해당 실행 컨텍스트가 허용하는 명령 계열로 제한됩니다.
문서는 경계를 명확히 긋습니다. 개인 액세스 토큰으로는 컴퓨터를 등록할 수 없고, 설치 토큰으로는 사람용 CLI 로그인을 만들 수 없습니다. 등록은 독립적인 로컬 서비스 세션을 생성하므로, 나중에 개인 토큰을 폐기해도 등록된 Computer가 오프라인이 되지 않습니다. 마찬가지로 sharkly auth logout은 로컬 프로필에서 토큰을 지울 뿐이며, Settings에서 폐기하기 전까지 서버에서는 토큰이 계속 유효합니다.
CI에서는 로그인 흐름을 아예 건너뛰세요. CLI는 SHARKLY_TOKEN 환경 변수에서 토큰을 읽으며, 이는 저장된 프로필보다 우선합니다. 워크플로 파일에 토큰을 적어 넣는 대신 GitHub Actions secrets 같은 보호된 시크릿 저장소에서 값을 가져오고, --organization-id로 조직을 명시적으로 지정하세요.
터미널에서 Computer 플릿 관리하기
호스트를 등록한 뒤에는 sharkly computer 명령 그룹으로 브라우저 없이 점검과 유지 관리를 할 수 있습니다:
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는 현재 조직에 등록된 Computer를 보여주고, show는 Runtime 정보를 포함한 Computer 하나를 반환하며, usage는 특정 Runtime을 조사하고, ping은 해당 Runtime이 왕복 통신을 완료할 수 있는지 확인하고, update는 Runtime의 CLI 업데이트를 요청합니다. ping이 따로 존재하는 이유는 이렇습니다. Computer가 온라인이라는 것은 로컬 서비스가 하트비트를 보내고 있다는 뜻일 뿐, 특정 Runtime이 지금 실행을 수행할 수 있다는 뜻은 아닙니다.
호스트 자체에서는 일상적인 진단에 사용자용 명령을 사용합니다:
sharkly computer status --output json
sharkly computer logs --lines 100
daemon 네임스페이스는 프로세스 수명 주기와 디스크 제어를 노출하며, sharkly daemon disk-usage와 sharkly daemon cleanup이 포함됩니다. cleanup은 --confirm을 추가하지 않으면 드라이런입니다. 문서의 판단 기준은 이렇습니다. 일상적인 진단에는 computer status와 computer logs를 우선 사용하고, 프로세스 수명 주기나 디스크 보고, 정리가 필요할 때만 daemon을 사용하세요. 이 시리즈의 Computers 게시물에서는 소유권, 가시성, 정리 정책을 더 깊이 다룹니다.
Task 스크립팅하기: 회의 없이 도착하는 업무
Task는 CLI가 파이프라인에서 제 역할을 하는 지점입니다. 명령 계열은 보드를 스크립트로 다루는 버전처럼 보입니다:
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
가장 확실한 CI 활용 사례는 업무를 자동으로 접수하는 것입니다. 실패한 릴리스를 감지한 야간 작업에 사람이 폼을 채울 필요는 없습니다:
sharkly task create \
--title "Investigate the failed release" \
--body-file ./task-body.md \
--output json
정확한 내용이 중요할 때는 --body-file 또는 --body-stdin을 사용하세요. 짧은 --body 형식은 이스케이프 시퀀스를 해석하기 때문입니다. 또한 Agent에 배정된 Task는 준비 상태에 있으면 실행이 시작되므로, 이 명령 하나가 완전 자동화 루프의 시작점이 될 수 있습니다. 스크립트가 Task를 접수하고, 배정된 Agent가 이를 가져가며, 실행과 블로커, 결과가 다시 Task로 돌아와 다음 날 아침 사람이 검토합니다.
리포팅 스크립트에는 클라이언트 측에서 걸러내는 대신 실제 필터를 사용할 수 있습니다. --status-changed-within 7d로 상태 변경 시점을 기준으로 필터링하고, 커스텀 필드로도 필터링할 수 있습니다:
sharkly task list --space HF --field "Customer Tier=VIP" --output json
반복된 --field 플래그는 AND로 결합되고, 매칭은 타입을 인식하며 정확하게 이루어지고, 필터링은 페이지네이션 전에 서버에서 수행됩니다. 문서의 스크립팅 관례를 그대로 따르세요. --output json을 명시적으로 요청하고, --color never와 --quiet를 추가하고, --organization-id를 눈에 띄게 유지하고, set -euo pipefail을 사용하세요. 종료 코드는 계약과 같습니다. 0은 성공, 1은 명령·검증·인증·원격 API 오류, 2는 일시적인 로컬 서비스나 네트워크 상태를 나타내므로 재시도 로직을 만들기 쉽습니다.
CLI는 자기 서술적이기도 합니다. sharkly schema task create --format json은 명령 레지스트리를 기계가 읽을 수 있는 형태로 노출하고, sharkly tldr task는 선별된 시나리오를 보여줍니다. 스크립트를 작성하는 주체가 에이전트일 때 특히 중요한 부분입니다.
대시보드를 열지 않고 실행 지켜보기
실행은 동일한 인터페이스를 통해 관찰할 수 있습니다:
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 플래그는 폴링을 합리적으로 만들어 줍니다. 모니터링 스크립트가 마지막으로 처리한 시퀀스 번호를 기록해 두고, 매번 새 메시지만 가져오는 방식입니다. 여기에 sharkly agent list, sharkly automation view, sharkly automation runs를 함께 사용하면 셸 스크립트와 jq만으로 에이전트 워크포스의 상태 페이지를 만들 수 있습니다.
REST API와 웹훅
CLI가 하는 모든 일은 REST API 위에서 이루어지며, 문서는 직접적인 방법을 보여줍니다. 개인 액세스 토큰을 HTTPS를 통해 베어러 토큰으로 보내면 됩니다.
curl -fsS https://api.sharkly.ai/rest/v1/users/current \
-H "Authorization: Bearer ${SHARKLY_TOKEN}"
API를 통한 접근은 토큰 뒤에 있는 사용자의 권한으로 제한됩니다. 현재 토큰 모델에는 토큰별 범위 선택 기능이 없으므로, 서비스마다 만료 기간을 정한 별도 토큰을 만드는 것이 좋습니다. 엔드포인트 레퍼런스는 docs.sharkly.ai에 있으며, CLI의 --output json 응답은 앞으로 다루게 될 형태를 충실히 미리 보여줍니다.
트래픽은 반대 방향으로도 흐릅니다. Automation은 웹훅 트리거를 가질 수 있습니다. Sharkly가 POST 요청을 받는 시크릿 URL을 생성하고, 유효한 요청이 들어오면 Automation의 Agent 또는 Crew 실행이 시작됩니다. 전체 URL은 한 번만 표시되며 기본적으로 베어러 시크릿 역할을 하고, 선택적으로 서명 검증을 사용할 수 있습니다. 이것이 CI 스토리의 인바운드 절반입니다. 파이프라인이 Sharkly에게 “뭔가 발생했으니 트리아지 Agent를 실행해”라고 알려주는 것이죠.
이 인터페이스가 무엇이 아닌지도 정확히 짚고 넘어갈 필요가 있습니다. Sharkly CLI는 또 다른 코딩 에이전트가 아니고, API는 모델 엔드포인트가 아닙니다. Claude Code나 Codex 같은 Runtime이 실행을 담당하고, Sharkly의 프로그래매틱 인터페이스는 그 주위의 계층을 관리합니다. 이러한 중립성 덕분에 자동화 인터페이스와 실행이 한 벤더의 울타리 안에 함께 존재하는 GitHub Agent HQ 같은 생태계 종속적 선택지와 차별화됩니다.
어디서부터 시작할까
생각보다 작게 시작하세요. 90일 만료의 개인 액세스 토큰을 만들고 sharkly login --token을 실행한 다음, 매일 하는 가장 지루한 읽기 작업을 스크립트로 만들어 보세요. 예를 들어 Task 목록을 jq로 파이프해 아침 요약을 만드는 것입니다. 읽기 작업은 안전하고, JSON 형태를 익히는 데도 도움이 됩니다. 그다음에는 실패한 CI 작업에서 Task를 생성하는 것처럼 트리거가 명확한 쓰기 작업 하나를 자동화하세요. 웹훅 트리거는 둘 다 익숙해진 뒤에 연결하세요.
지켜야 할 패턴은 플랫폼 전체가 기반으로 삼는 바로 그것입니다. 스크립트와 Agent가 작업을 생성하고 실행하며, 컨텍스트, 진행 상황, 블로커, 결과, 사람의 리뷰는 요청부터 릴리스까지 계속 보입니다. 입구는 자동화하고, 리뷰는 남겨두세요.
FAQ
Sharkly를 사용하려면 CLI가 꼭 필요한가요?
아니요. 개인 컴퓨터 연결은 Sharkly Desktop으로 해결되고, 일상적인 Task 작업은 웹 앱으로 처리할 수 있습니다. CLI는 원격 호스트나 Linux 컴퓨터를 연결할 때 필요해집니다. 그 경우 Sharkly CLI와 로컬 서비스를 설치하는 것이 문서에 나온 설정 경로이기 때문입니다. 또한 워크플로가 충분히 자주 반복되어 클릭 자체가 비용이 될 때도 CLI가 유용해집니다.
개인 액세스 토큰과 설치 토큰의 차이는 무엇인가요?
개인 액세스 토큰(접두사 shk_)은 사람이나 스크립트를 여러분의 사용자 계정으로 인증하며, CLI 로그인, CI 작업, 직접 API 요청에 사용됩니다. 컴퓨터 설치 토큰(접두사 sit_)은 일회성이며 30분 후 만료되고, 오직 Computer 등록만 수행합니다. 둘은 서로를 대체할 수 없습니다.
CLI 대신 Sharkly REST API를 직접 호출할 수 있나요?
네. 개인 액세스 토큰을 HTTPS를 통해 api.sharkly.ai로 베어러 토큰으로 보내면 됩니다. 문서에는 Authorization: Bearer 헤더와 함께 curl -fsS https://api.sharkly.ai/rest/v1/users/current를 사용하는 패턴이 나와 있습니다. 토큰은 여러분의 사용자 계정 권한을 그대로 갖습니다.
CI 파이프라인에서 Task를 만들려면 어떻게 하나요?
shk_ 토큰을 보호된 CI 시크릿으로 저장하고 SHARKLY_TOKEN 환경 변수로 노출하세요. CLI가 이 변수를 자동으로 읽습니다. 그런 다음 sharkly task create를 --title, 정확한 여러 줄 내용을 위한 --body-file, 명시적인 --organization-id, --output json과 함께 실행하면 작업이 생성된 Task의 ID를 캡처할 수 있습니다.
개인 액세스 토큰을 폐기하면 등록된 Computer도 중단되나요?
아니요. Computer 등록은 설치 토큰을 통해 독립적인 로컬 서비스 세션을 생성하므로, 개인 액세스 토큰을 폐기해도 해당 Computer는 중단되지 않습니다. 다만 폐기하면 CLI, API, 자동화 요청에 사용되는 모든 곳에서 토큰이 무효화되므로, 토큰을 교체할 때는 기존 토큰을 폐기하기 전에 의존하는 스크립트를 먼저 업데이트해야 합니다.
