# Comandos e referência

Esta página resume o comportamento atual dos comandos públicos da CLI e destaca os pré-requisitos mais importantes de cada fluxo.

## Matriz rápida

| Comando             | Exige login | Exige `--env` | Aceita `--json` |
| ------------------- | ----------- | ------------- | --------------- |
| `login`             | não         | não           | não             |
| `logout`            | não         | não           | não             |
| `login-check`       | sim         | não           | não             |
| `list-environments` | sim         | não           | sim             |
| `list-packages`     | sim         | sim           | sim             |
| `create-package`    | sim         | sim           | não             |
| `list-automations`  | sim         | sim           | sim             |
| `create-automation` | sim         | sim           | não             |
| `deploy-automation` | sim         | sim           | não             |

## Login

```bash
tunnelhub login
```

* abre autenticação via navegador;
* solicita `Tenant ID`;
* salva tokens localmente;
* usa refresh automático quando necessário.

Fallback:

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

## Verificação de sessão

```bash
tunnelhub login-check
```

Use para confirmar se as credenciais atuais ainda são válidas.

## Logout

```bash
tunnelhub logout
```

Remove credenciais locais salvas pela CLI.

## Listagem de ambientes

```bash
tunnelhub list-environments
```

Saída de máquina:

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

## Listagem de pacotes

```bash
tunnelhub list-packages --env DEV
```

Também é possível usar `--json`.

Importante: `--env` é obrigatório. Você pode informar nome ou UUID do ambiente.

## Criação de pacote

```bash
tunnelhub create-package --env DEV
```

O comando é interativo e hoje exige `--env` no fluxo público atual.

## Listagem de automações

```bash
tunnelhub list-automations --env DEV
```

Também é possível usar `--json`.

Importante: `--env` é obrigatório. Você pode informar nome ou UUID do ambiente.

## Criação de automação

```bash
tunnelhub create-automation --env DEV
```

O comando permite escolher entre quatro templates:

* `NO_DELTA`
* `NO_DELTA_BATCH`
* `DELTA`
* `DELTA_BATCH`

Durante o fluxo, a CLI:

* consulta os pacotes do ambiente escolhido;
* coleta nome, descrição, pacote, retention period e URL de repositório;
* cria a automação na plataforma;
* baixa o template oficial correspondente do GitHub;
* extrai o projeto para uma nova pasta local;
* preenche `service.uuid` no `tunnelhub.yml` gerado.

## Deploy de automação

```bash
tunnelhub deploy-automation --env DEV --message "meu deploy"
```

Opções relevantes:

* `--automation <uuid>` para sobrescrever o `service.uuid` do `tunnelhub.yml`;
* `--publish` para solicitar criação de versão publicada.

Requisitos do deploy:

* estar autenticado;
* executar o comando na pasta que contém `tunnelhub.yml`;
* ter `package.artifact` configurado;
* fornecer `--env`;
* fornecer `--message`.

O fluxo de deploy faz upload do artefato por URL assinada e depois solicita a criação do deploy na plataforma.

## Troubleshooting rápido

* **Não autenticado**: rode `tunnelhub login`.
* **Ambiente inválido**: valide com `tunnelhub list-environments`.
* **`tunnelhub.yml` não encontrado**: execute o comando na raiz correta do projeto.
* **`package.artifact` ausente**: configure o caminho do ZIP antes do deploy.
* **UUID da automação ausente**: preencha `service.uuid` ou use `--automation`.

## Fluxo recomendado

```bash
tunnelhub login
tunnelhub list-environments
tunnelhub create-package --env DEV
tunnelhub create-automation --env DEV
# implementar e gerar artefato
tunnelhub deploy-automation --env DEV --message "primeira versão"
```

Consulte também [Autenticação e ambientes](https://docs.tunnelhub.io/cli/authentication-and-environments) e [`tunnelhub.yml`](https://docs.tunnelhub.io/cli/tunnelhub-yml).