Cada clique na interface do Sharkly é uma decisão tomada por uma pessoa: criar esta Task, atribuir aquele Agent, verificar uma execução. Essa é a interface certa para decisões que exigem julgamento. É a interface errada para a milésima repetição da mesma decisão. Quando sua equipe decide que todo build noturno com falha deve se tornar uma Task, uma pessoa clicando por telas deixa de ser um fluxo de trabalho e passa a ser uma obrigação.
É aqui que entra a superfície programática. A CLI do Sharkly permite que pessoas, agents e scripts trabalhem com o Sharkly a partir de um terminal: gerenciar recursos da organização, registrar um Computer para execução de agents, inspecionar o serviço local e automatizar fluxos de trabalho repetíveis. Por trás dela existe uma API REST em api.sharkly.ai que aceita os mesmos personal access tokens usados pela CLI.
Isso importa mais para o Sharkly do que para uma ferramenta de gestão de projetos típica, porque o Sharkly não é apenas onde o trabalho é descrito. É onde o trabalho é executado. O Sharkly adiciona a camada compartilhada de tarefas, Computers, contexto, controle e revisão em torno de ferramentas de programação como Claude Code e Codex, então um sharkly task create scriptado não apenas abre um chamado. Se a Task estiver atribuída a um Agent e em um status de prontidão, ela pode iniciar uma execução real em um Computer real. Scriptar a superfície significa scriptar a força de trabalho.
Resumo rápido
A CLI do Sharkly (comando sharkly) permite que pessoas, agents e scripts trabalhem com o Sharkly a partir de um terminal, e é também como o serviço local é instalado em hosts remotos e Linux para que possam se juntar à sua frota como Computers. A autenticação é deliberadamente dividida: um personal access token (prefixo shk_) autentica uma pessoa ou um script, um token de instalação de uso único (prefixo sit_) registra um Computer, e execuções de Agent usam uma credencial de execução com escopo fornecida pelo Sharkly. Com um token em mãos, scripts podem criar e editar Tasks, comentá-las, inspecionar execuções e logs, e gerenciar Computers, tudo com --output json para facilitar o parsing. O mesmo token shk_ funciona como bearer token contra a API REST, e os gatilhos de webhook de Automation permitem que CI e outros sistemas externos iniciem execuções de Agent com uma requisição POST.
Uma plataforma, duas superfícies
A UI do Sharkly e sua superfície programática são duas entradas para o mesmo sistema. A Task que seu script cria é a mesma Task que um colega vê no quadro, com o mesmo status, Workflow, comentários e histórico de execução. Scriptar nunca contorna o registro compartilhado: a automação alimenta o sistema de registro.
Uma forma útil de dividir as duas é por quem está decidindo. Use a UI quando uma pessoa está tomando uma decisão que exige julgamento: moldar um requisito, revisar um diff, aceitar um resultado. Use a CLI ou a API quando a decisão já foi tomada e apenas a mecânica se repete: abrir Tasks a partir de um sistema de monitoramento, puxar logs de execução para um dashboard, verificar a saúde de um Computer a partir de um cron job. Um script pode criar a Task e até disparar a execução, mas a aceitação permanece com uma pessoa.
Instalando a CLI, e o que ela instala
No macOS ou Linux, o instalador oficial é um único comando:
curl -fsSL https://file-assets.sharkly.ai/download/install.sh | bash
O Windows tem um instalador oficial em PowerShell, atualmente apenas AMD64. Em qualquer plataforma, verifique e mantenha a instalação com:
sharkly version
sharkly update
A CLI tem um segundo papel além de ser um cliente. A documentação descreve dois caminhos para conectar um Computer: instalar o Sharkly Desktop em um computador pessoal compatível, ou instalar a CLI do Sharkly e o serviço local em um host remoto ou computador Linux. Esse segundo caminho é como um servidor de build, uma máquina Linux sobrando ou um contêiner se torna capacidade de execução para seus Agents. O serviço local que ela configura registra o Computer, detecta Runtimes instalados, envia heartbeats, recebe execuções na fila, prepara diretórios de tarefas e transmite o progresso de volta, iniciando a conexão por conta própria para que nenhuma porta de entrada seja necessária.
Se você ainda está conectando sua primeira máquina pela UI, o guia de primeiros passos cobre esse fluxo.
Três credenciais, três funções
O Sharkly usa credenciais separadas para finalidades separadas, e vale internalizar essa separação antes de automatizar qualquer coisa.
Um personal access token começa com shk_ e permite que a CLI, um script ou outro cliente confiável atue como sua conta de usuário. Você cria um em Configurações, escolhe uma expiração de 30 dias, 90 dias, 1 ano ou sem expiração, e copia o valor completo uma única vez na criação. Faça login com o fluxo baseado em prompt para que o token nunca acabe no histórico do shell:
sharkly login --token
sharkly auth status
Um token de instalação de computador começa com sit_, expira após 30 minutos e só pode ser usado uma vez. Sua única função é registrar um Computer:
sharkly computer register --install-token sit_...
A terceira credencial você nunca manipula: uma execução de Agent ativa recebe uma credencial de execução com escopo fornecida pelo Sharkly, limitada às famílias de comandos que seu contexto de execução permite.
A documentação traça a fronteira de forma clara: um personal access token não registra um computador, e um token de instalação não cria um login humano na CLI. O registro cria uma sessão independente do serviço local, e é por isso que revogar seu token pessoal depois não derruba seus Computers registrados. Da mesma forma, sharkly auth logout apenas limpa o token do seu perfil local; o token continua válido no servidor até que você o revogue em Configurações.
Para CI, pule completamente o fluxo de login. A CLI lê o token da variável de ambiente SHARKLY_TOKEN, que tem precedência sobre qualquer perfil salvo. Preencha-a a partir de um armazenamento de segredos protegido, como segredos do GitHub Actions, em vez de escrevê-la no arquivo de workflow, e mantenha a organização explícita com --organization-id.
Gerenciando uma frota de Computers pelo terminal
Depois que os hosts estiverem registrados, o grupo de comandos sharkly computer cobre inspeção e manutenção sem precisar de navegador:
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 mostra os Computers registrados na organização atual, show retorna um Computer com seus Runtimes, usage inspeciona um Runtime específico, ping verifica se esse Runtime consegue completar uma ida e volta, e update solicita uma atualização da CLI para um Runtime. A distinção pela qual ping existe: um Computer estar online significa apenas que seu serviço local está enviando heartbeats, não que determinado Runtime consiga executar uma run naquele momento.
No próprio host, o diagnóstico de rotina usa os comandos voltados ao usuário:
sharkly computer status --output json
sharkly computer logs --lines 100
O namespace daemon expõe controles de ciclo de vida de processo e de disco, incluindo sharkly daemon disk-usage e sharkly daemon cleanup, que é uma simulação a menos que você adicione --confirm. A regra de decisão da documentação: prefira computer status e computer logs para diagnóstico de rotina, e recorra ao daemon apenas quando precisar de ciclo de vida de processo, relatório de disco ou limpeza. O post sobre Computers desta série aprofunda questões de propriedade, visibilidade e políticas de limpeza.
Scriptando Tasks: trabalho que chega sem uma reunião
As Tasks são onde a CLI conquista seu lugar em um pipeline. A família de comandos se lê como uma versão scriptável do quadro:
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
O caso de uso óbvio em CI é abrir trabalho automaticamente. Um job noturno que detecta uma release com falha não precisa de uma pessoa preenchendo um formulário:
sharkly task create \
--title "Investigate the failed release" \
--body-file ./task-body.md \
--output json
Use --body-file ou --body-stdin sempre que o conteúdo exato importar, já que a forma curta --body decodifica sequências de escape. E como uma Task atribuída a um Agent inicia uma execução quando está em um status de prontidão, esse único comando pode ser o topo de um ciclo totalmente automatizado: o script abre a Task, o Agent atribuído a assume, e a execução, os bloqueios e o resultado retornam à Task, onde uma pessoa os revisa na manhã seguinte.
Scripts de relatório ganham filtros reais em vez de triagem no lado do cliente. Você pode filtrar por tempo no status com --status-changed-within 7d, e por campos personalizados:
sharkly task list --space HF --field "Customer Tier=VIP" --output json
Flags --field repetidas são combinadas com AND, a correspondência é sensível ao tipo e exata, e a filtragem acontece no servidor antes da paginação. Adote as convenções de script da documentação na íntegra: solicite --output json explicitamente, adicione --color never e --quiet, mantenha --organization-id visível e use set -euo pipefail. Os códigos de saída são contratuais: 0 para sucesso, 1 para erros de comando, validação, autenticação ou API remota, e 2 para condições transitórias do serviço local ou de rede, o que torna a lógica de retry direta.
A CLI também é autodescritiva. sharkly schema task create --format json expõe o registro de comandos em formato legível por máquina, e sharkly tldr task apresenta cenários curados, o que importa quando quem está escrevendo o script é ele mesmo um agent.
Acompanhando execuções sem abrir um dashboard
A execução é observável pela mesma superfície:
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
A flag --since torna o polling sensato: um script de monitoramento registra o último número de sequência processado e recupera apenas as mensagens mais recentes a cada passagem. Combine isso com sharkly agent list, sharkly automation view e sharkly automation runs e você pode montar uma página de status para sua força de trabalho de agents a partir de um shell script e jq.
A API REST e webhooks
Tudo o que a CLI faz se apoia na API REST, e a documentação mostra o caminho direto: envie seu personal access token como bearer token via HTTPS.
curl -fsS https://api.sharkly.ai/rest/v1/users/current \
-H "Authorization: Bearer ${SHARKLY_TOKEN}"
O acesso pela API é limitado pelas permissões do usuário por trás do token; o modelo atual de token não tem seleção de escopo por token, o que é um bom motivo para criar um token separado para cada serviço, com uma expiração definida. A referência de endpoints fica em docs.sharkly.ai, e as respostas --output json da CLI são uma prévia fiel dos formatos com que você vai trabalhar.
O tráfego também flui no sentido contrário. Uma Automation pode carregar um gatilho de webhook: o Sharkly gera uma URL secreta que aceita uma requisição POST, e uma requisição válida inicia a execução do Agent ou da Crew da Automation. A URL completa é mostrada uma única vez e funciona como segredo bearer por padrão, com verificação de assinatura opcional. Essa é a metade de entrada da história de CI: seu pipeline dizendo ao Sharkly "algo aconteceu, execute o Agent de triagem".
Vale ser preciso sobre o que essa superfície não é. A CLI do Sharkly não é outro agent de programação, e a API não é um endpoint de modelo. Runtimes como Claude Code e Codex realizam a execução; a superfície programática do Sharkly gerencia a camada ao redor deles. Essa neutralidade a separa de opções vinculadas a um ecossistema, como o GitHub Agent HQ, onde a superfície de automação e a execução vivem dentro dos muros de um único fornecedor.
Por onde começar
Comece menor do que você imagina. Crie um personal access token com expiração de 90 dias, execute sharkly login --token e scripte a leitura mais entediante que você faz todos os dias, como uma lista de tarefas canalizada por jq para um resumo matinal. Leituras são seguras, e ensinam os formatos JSON. Depois automatize uma escrita com um gatilho óbvio, como criar uma Task a partir de um job de CI com falha. Configure um gatilho de webhook só depois que ambos parecerem rotineiros.
O padrão a preservar é aquele sobre o qual toda a plataforma é construída: scripts e Agents geram e executam o trabalho, e o contexto, o progresso, os bloqueios, os resultados e a revisão humana permanecem visíveis da solicitação até a entrega. Automatize as entradas. Mantenha a revisão.
Perguntas frequentes
Preciso da CLI para usar o Sharkly?
Não. O Sharkly Desktop cobre a conexão de um computador pessoal, e o aplicativo web cobre o trabalho diário com Tasks. A CLI se torna necessária quando você conecta um host remoto ou computador Linux, já que instalar a CLI do Sharkly e o serviço local é o caminho de configuração documentado nesse caso, e ela se torna valiosa sempre que um fluxo de trabalho se repete o suficiente para que clicar por ele seja um custo.
Qual é a diferença entre um personal access token e um token de instalação?
Um personal access token (prefixo shk_) autentica uma pessoa ou um script como sua conta de usuário, para logins na CLI, jobs de CI e requisições diretas à API. Um token de instalação de computador (prefixo sit_) é de uso único e de curta duração, expirando após 30 minutos, e apenas registra um Computer. Nenhum substitui o outro.
Posso chamar a API REST do Sharkly diretamente em vez de usar a CLI?
Sim. Envie um personal access token como bearer token via HTTPS para api.sharkly.ai; a documentação mostra curl -fsS https://api.sharkly.ai/rest/v1/users/current com um cabeçalho Authorization: Bearer como padrão. O token carrega as permissões da sua conta de usuário.
Como crio uma Task a partir de um pipeline de CI?
Armazene um token shk_ como segredo protegido de CI e exponha-o como a variável de ambiente SHARKLY_TOKEN, que a CLI lê automaticamente. Depois execute sharkly task create com --title, --body-file para conteúdo multilinha exato, um --organization-id explícito e --output json para que o job possa capturar o ID da Task criada.
Revogar meu personal access token interrompe meus Computers registrados?
Não. O registro de Computer cria uma sessão independente do serviço local por meio do token de instalação, então revogar um personal access token não interrompe esses Computers. A revogação, no entanto, invalida o token em todos os lugares em que ele é usado para requisições de CLI, API e automação, e é por isso que a rotação deve atualizar os scripts dependentes antes que o token antigo seja revogado.
