Autenticação e ambientes

Quase todo fluxo da CLI depende de duas coisas: uma sessão válida e a resolução correta do ambiente.

Fluxo principal de autenticação

O caminho recomendado usa navegador:

tunnelhub login

Nesse fluxo, a CLI:

• solicita o Tenant ID;

• abre a autenticação no frontend do TunnelHub;

• recebe tokens ao final do login;

• salva a sessão localmente para reutilização;

• usa refresh automático quando necessário.

Fallback por usuário e senha

Em cenários específicos, a CLI ainda aceita fallback por usuário e senha:

tunnelhub login --password

Esse modo é útil quando o fluxo por navegador não é o mais prático, mas o padrão recomendado continua sendo OAuth pelo browser.

Como validar a sessão

tunnelhub login-check

Use esse comando quando você quiser confirmar rapidamente se a sessão ainda é válida antes de listar recursos ou iniciar um deploy.

Como encerrar a sessão

tunnelhub logout

Esse comando remove as credenciais locais salvas pela CLI.

Como a CLI resolve ambientes

Comandos como list-packages, list-automations, create-automation e deploy-automation usam --env.

Você pode informar:

• o nome do ambiente;

• ou o UUID do ambiente.

A CLI resolve esse valor para o identificador correto antes de chamar a API.

Descobrindo ambientes válidos

tunnelhub list-environments

Se você quiser usar saída de máquina:

tunnelhub list-environments --json

Erros comuns

• Sessão inválida: execute tunnelhub login novamente.

• Ambiente não encontrado: valide o nome/UUID com tunnelhub list-environments.

• Tenant incorreto no login: confirme se o Tenant ID corresponde ao tenant certo antes de autenticar.

• Sessão antiga em máquina compartilhada: rode tunnelhub logout antes de iniciar novo login.

Recomendações

• prefira nome de ambiente apenas quando a nomenclatura do tenant for estável;

• use UUID em scripts quando quiser reduzir ambiguidade;

• valide a sessão antes de deploys importantes;

• evite reaproveitar máquinas com sessões antigas sem conferir o tenant e o ambiente ativo.