CLI (linha de comando)

A CLI tracker (pacote @aquarela/tracker no npm) leva o tracker para o terminal. É o caminho mais simples para agentes que rodam comandos, como Claude Code e Codex: eles já sabem usar uma CLI, leem a ajuda sozinhos e não carregam as tools do MCP no contexto. Por baixo é a API REST, com as mesmas regras e permissões da tela, em nome de quem entrou.

Instalar e entrar

npm install -g @aquarela/tracker
tracker login

Precisa do Node.js 20 ou mais novo (sem instalar: npx @aquarela/tracker). tracker login abre o navegador: a pessoa autoriza a CLI numa tela como a do MCP, escolhendo as empresas e se ela pode escrever. O login fica em ~/.config/tracker, só legível pela pessoa, e se renova sozinho; tracker logout sai e desconecta. Sem navegador (servidor, contêiner, CI), use um token pessoal: TRACKER_TOKEN no ambiente, ou tracker login --with-token com o token na entrada padrão. tracker whoami mostra quem entrou, as empresas e o acesso. A pessoa encontra estes comandos, prontos para copiar, em https://tracker.aquarela.app/account/cli (Sua conta → Apps e API → CLI).

Comandos

• tracker issues list: a busca de GET /issues, com os mesmos filtros (-p projeto, --open, --mine, -s status, -q texto, --query consulta avançada, --filter filtro salvo, --limit, --offset).
• tracker issues view <código>: a issue, com --comments para os comentários e --fields para só algumas partes.
• tracker issues create: cria (-p, -t, -d ou -D com um arquivo, --type, --severity, --priority, -a, -l, --field, --external-id, --similar).
• tracker issues update <código>: edita só o que vier (--assignee, --add-label, --remove-label, --sprint, --release, --fix-notes, --edit-version e outros).
• tracker issues status <código> <status>: muda o status pela chave do fluxo do projeto (--reason ao fechar).
• tracker issues comment <código>: comenta (-b texto, -B arquivo ou a entrada padrão, --reply-to, --attach).
• tracker issues attach <código> <arquivos>: anexa; acima de 15 MB, pelo envio direto de POST /uploads.
• tracker projects list e tracker projects view <prefixo>: os projetos, com os status, os tipos e os campos de cada um.
• tracker similar "<texto>" (ou --issue <código>): "Já aconteceu antes?", pelo GET /search.
• tracker docs list, tracker docs search "<pergunta>" e tracker docs view <slug>: a base de conhecimento.
• tracker org list e tracker org use <slug>: as empresas do login e a padrão.
• tracker api <rota>: qualquer rota da API, com o login da CLI, como o gh api: -X o método, -f e -F (com tipo) montam o corpo JSON, --input manda um corpo pronto.
• tracker llms: este manual, sem login.

tracker <comando> --help mostra as opções e os exemplos de cada comando.

Para agentes e scripts

• --json em qualquer comando imprime a resposta da API como veio, com os campos documentados aqui. Os erros saem na saída de erro, em JSON com --json (error, message, status).
• Códigos de saída: 0 deu certo, 1 erro da API ou da rede, 2 uso errado, 4 sem login ou login vencido.
• --org <slug> (ou TRACKER_ORG) escolhe a empresa da chamada, pelo cabeçalho X-Tracker-Organization, quando o login cobre mais de uma.
• No limite de chamadas (429), a CLI espera o Retry-After e tenta de novo.
• Ambiente: TRACKER_TOKEN, TRACKER_ORG, TRACKER_HOST (padrão https://tracker.aquarela.app) e TRACKER_LANG (pt, en ou es; sem ele, o idioma da conta).

Exemplo de instrução para o AGENTS.md ou o CLAUDE.md de um repositório:

As tarefas deste repositório ficam no tracker, projeto MOB. Use a CLI `tracker` com --json:
`tracker issues list -p MOB --open --json`, `tracker issues view` e `tracker issues comment`.
Antes de criar uma tarefa, rode `tracker similar`.