Dropstone CLI

Guia de solução de problemas

Diagnostique problemas do Dropstone CLI de forma sistemática. Colete as informações certas, encontre os logs e isole a causa antes de entrar em contato com o suporte.

A maioria dos problemas se enquadra em uma de quatro coisas: uma build antiga, um cache desatualizado, credenciais inválidas ou a rede. Esta página é a ordem em que você deve verificá-los e o que coletar quando nenhum deles for a causa.

Para uma mensagem de erro específica, comece com Problemas comuns. Para comportamento em tempo de execução e depuração por recurso, veja Solução de problemas do CLI.

Primeiras três coisas a tentar

Execute estas antes de qualquer outra coisa. Elas resolvem uma parcela surpreendente dos relatos.

# 1. Obtenha a versão atual
dropstone update

# 2. Veja o que o Dropstone está realmente fazendo
dropstone --log-level DEBUG --print-logs
  1. Se a falha ocorrer no meio da sessão e a causa não estiver clara, limpe o cache e reinicie:
rm -rf ~/.cache/dropstone

No Windows, pressione WIN+R e exclua %USERPROFILE%\.cache\dropstone.

Antes de excluir qualquer outra coisa

Os três comandos acima são seguros. Excluir ~/.local/share/dropstone não é — é lá que suas credenciais e histórico de sessão ficam. Veja Onde os dados ficam antes de remover esse diretório.

Onde os dados ficam

Tudo o que o Dropstone mantém em disco fica em dois diretórios.

O quêmacOS / LinuxWindows
Credenciais e sessões~/.local/share/dropstone/%USERPROFILE%\.local\share\dropstone
Logs~/.local/share/dropstone/log/%USERPROFILE%\.local\share\dropstone\log
Cache~/.cache/dropstone/%USERPROFILE%\.cache\dropstone

Dentro do diretório de dados:

  • auth.json — suas credenciais. Exclua isso apenas para forçar um login limpo.
  • log/ — logs com carimbo de data/hora. Os dez mais recentes são mantidos.
  • project/ — histórico de sessão, com escopo por projeto.

Um arquivo de log é nomeado pela data em que foi gravado, por exemplo 2026-05-23T123456.log. O mais recente é o que você quer.

Obtenha um log que vale a pena ler

Por padrão, o nível de log é silencioso. Duas flags mudam isso:

# Saída detalhada gravada no arquivo de log
dropstone --log-level DEBUG

# A mesma saída transmitida para o seu terminal conforme acontece
dropstone --print-logs

Use ambas juntas quando quiser observar a falha ocorrer e ainda ter o arquivo depois.

Se o problema for uma falha na inicialização, --print-logs é o que ajuda: o arquivo de log pode nem ser gravado antes de o processo morrer, mas o stderr sempre é.

O que incluir em um relato

Um relato com estas cinco coisas geralmente precisa de uma resposta para ser resolvido. Um relato sem elas geralmente precisa de quatro.

  1. O comando exato que você executou. Não uma paráfrase — a linha literal, incluindo flags.

  2. O que você esperava e o que aconteceu. Ambas as partes. "Falhou" não restringe nada.

  3. Sua versão e plataforma.

    dropstone --version

    Além do seu sistema operacional e versão, e se você está no Windows nativo ou dentro do WSL.

  4. O trecho relevante do log. Algumas linhas de cada lado do erro, não o arquivo inteiro. Redija qualquer coisa sensível — logs de sessão podem conter caminhos de arquivo e código.

  5. Se é reproduzível. Sempre, às vezes ou uma vez. "Às vezes" vale a pena dizer; aponta para tempo ou estado, em vez de uma entrada ruim.

Envie para dropstone.io/contact.

Restringindo o problema

Se a causa ainda não estiver óbvia, elimine variáveis uma de cada vez. Cada uma destas remove uma categoria inteira.

É o projeto? Execute o Dropstone em um diretório vazio. Se funcionar lá, o problema é específico do projeto — provavelmente um arquivo de configuração, um arquivo de regras ou algo no repositório que o agente está lendo.

É a sua configuração? Mova temporariamente dropstone.json para o lado e reinicie. Veja Configuração para saber onde ficam os arquivos de configuração global e do projeto.

É um servidor MCP? Um servidor que trava na inicialização vai parar a sessão inteira. Liste-os e desabilite-os, depois reabilite um de cada vez:

dropstone mcp list

É a rede? Proxies corporativos são a causa mais comum de falhas que parecem outra coisa. Verifique:

curl -I https://dropstone.io

Se isso falhar ou retornar algo inesperado, veja Rede e proxy. A correção usual é definir HTTPS_PROXY e, importantemente, NO_PROXY=localhost,127.0.0.1 — o Dropstone usa um loopback local durante sessões interativas, e rotear isso por um proxy causa um loop.

São suas credenciais? Saia e entre novamente:

dropstone auth logout
dropstone auth login

É o terminal? No Linux, copiar e colar precisam de um utilitário de área de transferência instalado. Veja Solução de problemas do CLI.

É o Windows? Acesso lento a arquivos, falhas de terminal e problemas de caminho no Windows nativo geralmente desaparecem sob o WSL. Veja Windows e WSL.

Antes de entrar em contato com o suporte

Relacionados

Ctrl+I