# 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](/cli/commands.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tunnelhub.io/cli/authentication-and-environments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.