Diagnóstico

Use raims doctor para conferir a configuração do CLI e identificar o que precisa ser corrigido na sua instalação.

Executar o diagnóstico

raims doctor

As verificações abrangem a leitura da configuração e do perfil selecionado, as permissões dos arquivos locais, a identidade do executável e a política de atualização. O resultado de cada verificação informa a condição encontrada e a orientação aplicável.

Uma verificação com error faz o comando terminar com código 3. Avisos permitem concluir o diagnóstico com código 0.

Para escolher outro perfil ou capturar o resultado em uma automação:

raims --profile sandbox --output json doctor

O JSON reúne status, build, interactive, o profile selecionado quando houver um e a lista checks. Cada verificação contém name, status e message. Os nomes são configuration, profile, permissions, installation e updates.

O diagnóstico não envia requisições à API nem confirma a validade da credencial, as permissões da empresa ou a conectividade com o serviço. Consulte os guias de autenticação e chaves de API para essas condições.

Conferir a arquitetura

Para consultar o sistema e a arquitetura do executável em uso:

raims --output json version

No CLI nativo para Windows ARM64, o resultado contém os: "windows" e arch: "arm64". Essa consulta é local e não exige perfil, chave ou rede.

Se instalou pelo npm, confira também o Node.js usado no mesmo terminal:

node -p "process.platform + '/' + process.arch"

Para usar o pacote nativo no Windows ARM64, tenha Node.js 22 ou superior para ARM64. O comando acima deve retornar win32/arm64. Um Node.js x64 seleciona o pacote x64, inclusive quando o Windows é ARM64. Com o Node.js ARM64 disponível, instale ou atualize com npm install -g @raimshq/cli@latest e confira novamente a versão do CLI.

Na instalação direta, escolha o instalador da arquitetura desejada e confira o executável pelo caminho completo. O instalador não substitui uma instalação de outra versão ou arquitetura. Se precisar manter ambas, escolha outro diretório do usuário com -directory CAMINHO, preserve a instalação existente e use o caminho completo da nova. Consulte Instalação direta.

Conferir o acesso à API

raims --profile sandbox --output json auth check --timeout 30s

Esse comando envia GET /v1/accounts/fees a https://api.raims.com com a sessão OAuth ou a chave de API associada ao perfil. Ele não altera a conta. O resultado de sucesso contém data.authenticated: true e o nome do perfil, confirmando acesso a essa leitura. Os demais endpoints continuam sujeitos às suas permissões e condições.

Chaves de Sandbox e de Produção usam o mesmo endereço. Em um perfil de chave, a API determina o ambiente pela credencial. Em um perfil OAuth, use o ambiente escolhido no login ou informe --environment sandbox|production. Para conferir o acesso a outro recurso, use seu comando de leitura e consulte o status HTTP e error.code se houver uma recusa. auth check não concede permissões nem executa escritas de teste.

Para conferir somente os metadados locais de uma sessão OAuth, sem acessar o cofre ou a rede, use raims --profile pessoal auth status. Essa consulta não substitui a verificação de acesso no servidor.

Fazer login novamente no mesmo perfil do CLI

Execute raims login --profile pessoal --environment sandbox. O CLI confere a autorização no servidor e reutiliza uma sessão válida. Se ela tiver expirado ou sido revogada, abre um novo consentimento no navegador. Confira o nome do perfil, a conta e os acessos antes de autorizar. Para outra conta, use outro perfil.

Renovação de sessão temporariamente indisponível

Se receber OAUTH_SERVICE_UNAVAILABLE, aguarde e repita o comando. Essa recusa temporária da renovação preserva a sessão para outra tentativa, sem exigir um novo consentimento. Se o erro informar que a renovação não pôde ser confirmada, siga a orientação apresentada antes de tentar novamente.

Cancelamento do CLI e código de saída

Interromper o comando com Ctrl+C retorna CANCELLED e o código de saída 130, inclusive durante o login ou a renovação da sessão. Cancelar uma requisição não desfaz o que a API já aceitou. Se ela alterava um recurso, consulte o resultado antes de repetir.

Investigar uma falha

Quando você digita um nome próximo de um comando conhecido, o CLI sugere a grafia correta e mostra como abrir a ajuda do grupo. Por exemplo, raims customers creat pode sugerir raims customers create. A sugestão não é executada. O erro mantém o código UNKNOWN_COMMAND e o código de saída 2.

Quando uma opção estiver escrita de forma próxima a uma opção conhecida, o CLI pode sugerir a correção, como --full-name ao receber --full_name. Se faltar um valor ou seu formato estiver incorreto, a mensagem indica o tipo ou os valores aceitos e a ajuda do comando, como raims charges create --help. Sugestões ambíguas são omitidas.

Para metadata, use --metadata chave=valor; pontos na chave fazem parte do nome, sem criar opções aninhadas. Os erros de opções mantêm INVALID_ARGUMENT, a categoria usage e o código de saída 2, sem repetir os valores informados. Esses erros não executam a requisição.

OAUTH_TOKEN_LIFETIME_INSUFFICIENT indica que o CLI não obteve um token válido por todo o prazo da requisição, mesmo após tentar renová-lo. A requisição à API não foi enviada. Use um --timeout menor que ainda seja adequado ao comando ou execute raims logout e raims login para renovar a autorização. Esse erro usa o código de saída 4.

Compartilhar um diagnóstico

Acrescente --debug para obter detalhes de uma execução em stderr:

raims --debug --output json doctor

O diagnóstico preserva o resultado do comando em stdout e oculta os valores das credenciais. Revise caminhos, nomes de perfis e outras informações locais antes de compartilhar os arquivos. Nunca envie chaves de API, tokens ou o endereço completo de um login em andamento junto do relato. Para requisições à API, inclua o código de saída, error.code e, quando disponíveis, error.status_code e error.request_id. Revise também a resposta capturada em stdout, pois ela pode conter dados da conta ou segredos do recurso consultado.

Para identificar os textos legais incluídos na versão em execução, use raims licenses --output json. Essa consulta local não exige perfil nem rede; veja Avisos e licenças.