# 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).


---

# 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/commands.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.