Configuração e perfis

Use um perfil para cada conta ou integração. Você pode conectar o CLI pelo navegador com OAuth ou associar uma chave de API a uma variável de ambiente. A configuração guarda as referências necessárias; os segredos ficam fora do arquivo de perfis.

Conectar pelo navegador

Para usar sua conta no terminal, escolha um nome de perfil e o ambiente:

raims login --profile pessoal --environment sandbox
raims profile use pessoal

O CLI abre a página de login da Raims. Confira a conta e o aplicativo Raims CLI, escolha as permissões, revise os ambientes autorizados e conclua a confirmação de segurança. Volte ao terminal quando a autorização terminar. Você não precisa copiar uma chave de API nem informar sua senha ao CLI.

Ao repetir o login, o CLI confere a autorização no servidor. Se a sessão continuar válida, ele reutiliza a conexão. Se ela tiver expirado ou sido revogada, abre um novo consentimento. Uma indisponibilidade temporária não cria outra conexão: aguarde e tente novamente. Para conectar outra conta, escolha outro nome de perfil.

O acesso continua limitado às permissões concedidas e ao acesso atual de quem autorizou. A sessão é renovada automaticamente enquanto a conexão permanecer válida. As credenciais são protegidas pelo armazenamento seguro do sistema operacional. Se ele estiver indisponível, corrija seu acesso ou use um perfil de chave de API; o CLI não salva a sessão em texto aberto.

Antes de cada requisição, o CLI confere se o token continua válido durante o prazo definido por --timeout e o renova quando necessário. Se a validade continuar insuficiente, a requisição não é enviada. Consulte a orientação de OAUTH_TOKEN_LIFETIME_INSUFFICIENT em Diagnóstico.

Para conferir os metadados locais da sessão sem acessar a rede:

raims --profile pessoal auth status

Essa consulta não confirma o acesso atual no servidor. Use auth check para fazer uma leitura autenticada.

Se preferir abrir o navegador manualmente, execute:

raims login --profile pessoal --environment sandbox --no-browser

Abra o endereço apresentado e mantenha o comando em execução até concluir. O navegador precisa alcançar o retorno local na máquina que executa o CLI. A opção não transforma o login em um fluxo por código para outro dispositivo. Login exige um terminal interativo; para pipelines, use uma chave de API.

Selecionar o ambiente

No login OAuth, --environment sandbox ou --environment production define o ambiente inicial do perfil. Os comandos seguintes usam essa escolha. Para executar um comando em outro ambiente autorizado, informe a opção:

raims --profile pessoal --environment sandbox customers list
raims --profile pessoal --environment production accounts fees

A opção só seleciona um ambiente já autorizado. Ela não amplia o acesso nem altera os ambientes da conexão. Confira a conta e o ambiente antes de enviar uma escrita em Produção.

Em perfis de chave de API, a própria chave determina o ambiente. Use a chave do ambiente desejado; uma opção de ambiente não converte a credencial.

Encerrar a sessão

Para revogar a conexão OAuth do perfil:

raims logout --profile pessoal

Após confirmar a revogação, o CLI remove a sessão e o perfil locais. Se a revogação falhar, eles são preservados para você tentar novamente.

Você também pode revogar o acesso em

Integração, Aplicativos autorizados. Sair da sessão do Dashboard não encerra a conexão do CLI. Para conectar novamente, execute raims login e revise as permissões.

Criar um perfil

Para scripts e integrações que usam uma chave de API:

O nome sandbox não define o ambiente de uma requisição. A chave validada pela API determina o ambiente e a empresa, conforme o guia de autenticação.

Para uma credencial de Produção, você pode criar outro perfil com uma variável separada:

raims profile set production --api-key-env RAIMS_PRODUCTION_API_KEY

Disponibilize o valor da chave nessa variável para o processo do CLI. Requisições de ambos os perfis usam https://api.raims.com. O CLI não aceita outro endereço por flag, variável de ambiente ou configuração do perfil.

Verificar o acesso à API

raims --profile sandbox --output json auth check

O comando lê GET /v1/accounts/fees em https://api.raims.com com a credencial do perfil selecionado, sem alterar a conta. Ele aceita os perfis OAuth e de chave de API. No sucesso, retorna:

{
  "status_code": 200,
  "data": {
    "authenticated": true,
    "profile": "sandbox"
  }
}

Esse resultado confirma acesso à leitura de tarifas. Cada outro endpoint valida suas próprias permissões e condições. Uma recusa nesse comando também pode indicar falta de permissão para essa leitura; ela não comprova, sozinha, que a credencial é inválida. Confira o status HTTP e error.code retornados.

Em um perfil de chave de API, uma variável ausente ou vazia impede o envio da requisição. O CLI não lê a chave de um argumento nem grava seu valor no perfil.

Escolher o perfil da execução

A seleção segue esta ordem:

Para selecionar somente nesta execução:

raims --profile sandbox profile show

A flag não altera o padrão salvo. Um perfil informado em --profile tem prioridade sobre RAIMS_PROFILE.

raims profile show NOME consulta o perfil informado no argumento, mesmo quando outro perfil está selecionado. A listagem preserva a identificação do padrão salvo e informa também a seleção da execução na saída JSON.

$env:RAIMS_PROFILE = 'sandbox'
raims profile show

Remover um perfil

Para retirar um perfil antigo da configuração local:

raims profile remove old-project

Perfis OAuth exigem raims logout antes da remoção ou da substituição por um perfil de chave de API.

Informe o nome exato do perfil de chave. A remoção não revoga a chave na API nem altera a variável de ambiente que a contém. Se o perfil removido era o padrão salvo, o CLI limpa essa seleção e não escolhe outro perfil. Use raims profile use NOME para salvar um novo padrão.

Repetir o comando para um perfil já ausente termina com sucesso. Com --output json, o resultado informa name e configured: false. Se RAIMS_PROFILE ainda apontar para o perfil removido, atualize ou remova essa seleção no seu terminal antes de executar outro comando que use perfil.

Preparar o autocompletar

Use o assistente para detectar o shell e ver as instruções de ativação:

raims completion setup

Sem --save, o comando apresenta o plano sem criar arquivos. Se a detecção não identificar um shell compatível, informe --shell powershell|bash|zsh|fish. Para ver o plano de gravação e depois salvar o script de PowerShell:

raims completion setup --shell powershell --save ./raims-completion.ps1 --dry-run
raims completion setup --shell powershell --save ./raims-completion.ps1

O diretório deve existir e o arquivo deve ser novo. O CLI não sobrescreve arquivos nem altera o perfil ou o arquivo de inicialização do shell. Depois de gravar, siga as instruções apresentadas para ativar o autocompletar na sessão desejada, respeitando a política do seu terminal.

O assistente funciona sem perfil, chave ou rede e não ativa atualizações. Com --output json, retorna o shell escolhido, a origem dessa escolha, o caminho quando informado, os indicadores de gravação e prévia e as instruções. Os comandos existentes, como raims completion powershell, continuam gerando o script em stdout para quem prefere configurar manualmente.

Local da configuração

Consulte o caminho usado pelo CLI:

raims config path

Por padrão, o arquivo fica na pasta raims do diretório de configurações do usuário. Defina RAIMS_CONFIG_DIR com um caminho absoluto para usar outra pasta, por exemplo em uma automação com configuração isolada.

Mantenha essa pasta sob as permissões do usuário que executa o CLI. O arquivo de perfis contém referências e metadados de autenticação, sem segredos em texto aberto. A sessão OAuth permanece cifrada e depende do armazenamento seguro do sistema para ser lida.