> For the complete documentation index, see [llms.txt](https://docs.tunnelhub.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tunnelhub.io/cli/commands.md).

# 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` | depende do fluxo | depende do fluxo | não             |

Para `deploy-automation`:

* no fluxo interativo, exige login e `--env`;
* no fluxo CI/CD M2M, não exige login no navegador e aceita `--environment-id` ou `--env` com UUID.

## 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`;
* `--environment-id <uuid>` para informar explicitamente o UUID do ambiente;
* `--publish` para solicitar criação de versão publicada.

Requisitos do deploy:

Fluxo com login:

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

Fluxo CI/CD M2M:

* configurar `TH_API_HOST`, `TH_CLIENT_ID` e `TH_CLIENT_SECRET`;
* executar o comando na pasta que contém `tunnelhub.yml`;
* ter `package.artifact` configurado;
* fornecer `--environment-id` ou `--env` com UUID;
* fornecer `--message`.

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

No fluxo CI/CD com credenciais M2M:

* configure `TH_API_HOST`, `TH_CLIENT_ID` e `TH_CLIENT_SECRET`;
* use uma credencial autorizada para o ambiente alvo;
* use `--environment-id` ou `--env` com UUID do ambiente;
* use `--message` para registrar o contexto humano do deploy;
* `createdBy` da revisão ficará como `api-client:<clientId>`.

Exemplo:

```bash
COMMIT_EMAIL="$(git log -1 --pretty=format:'%ae')"
COMMIT_SHA="$(git rev-parse --short HEAD)"

th deploy-automation \
  --environment-id "$TH_ENVIRONMENT_ID" \
  --automation "$TH_AUTOMATION_ID" \
  --message "GitHub Actions deploy ${COMMIT_SHA} by ${COMMIT_EMAIL}"
```

## 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 [Deploy via CI/CD](/cli/ci-cd-deployments.md), [Autenticação e ambientes](/cli/authentication-and-environments.md) e [`tunnelhub.yml`](/cli/tunnelhub-yml.md).