# 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:

```bash
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:

```bash
tunnelhub login --password
```

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

## Como validar a sessão

```bash
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

```bash
tunnelhub logout
```

Esse comando remove as credenciais locais salvas pela CLI.

## Como a CLI resolve ambientes

Comandos como `list-packages`, `create-package`, `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

```bash
tunnelhub list-environments
```

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

```bash
tunnelhub list-environments --json
```

## Recomendações práticas

* 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;
* confirme o tenant correto quando estiver em máquina compartilhada.

## Erros comuns

* **Sessão inválida**: execute `tunnelhub login` novamente.
* **Ambiente não encontrado**: valide o nome ou 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.

## Check rápido antes de deploy

1. `tunnelhub login-check`
2. `tunnelhub list-environments`
3. confirmar o valor de `--env`
4. confirmar se o projeto certo contém `tunnelhub.yml`

Consulte também [Comandos e referência](https://docs.tunnelhub.io/cli/commands).