> 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/cli.md).

# Visão geral

O `@tunnelhub/cli` é a ferramenta de linha de comando para fluxos de desenvolvimento e publicação de automações.

## Quando usar

Use a CLI para:

* autenticar na plataforma;
* listar ambientes, pacotes e automações;
* criar pacotes;
* criar automações com bootstrap de template;
* publicar deploys.

## Escopo atual da CLI

Os comandos públicos instalados hoje são:

* `login`
* `logout`
* `login-check`
* `list-environments`
* `list-packages`
* `create-package`
* `list-automations`
* `create-automation`
* `deploy-automation`

## Instalação

```bash
npm install -g @tunnelhub/cli
```

Pacote no npm: `https://www.npmjs.com/package/@tunnelhub/cli`

Depois da instalação, os dois comandos abaixo funcionam:

```bash
tunnelhub --help
th --help
```

## Fluxo de autenticação

O fluxo principal usa navegador e salva as credenciais localmente para reutilização e refresh automático.

```bash
tunnelhub login
```

Também existe fallback por usuário e senha:

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

## Como a CLI trabalha com ambientes

Comandos como `list-packages`, `create-package`, `list-automations` e `create-automation` dependem de `--env`. Você pode informar nome ou UUID do ambiente.

No fluxo interativo com login, `deploy-automation` também usa `--env`.

No fluxo CI/CD com credenciais M2M, use `--environment-id` ou `--env` com o UUID do ambiente.

Os comandos de listagem também aceitam `--json` quando você precisa integrar a saída em script.

## O que acontece ao criar uma automação

Ao executar `create-automation`, a CLI:

* consulta seus pacotes no ambiente escolhido;
* pede os dados da automação;
* cria a automação na plataforma;
* baixa um template oficial do GitHub;
* extrai esse template em uma nova pasta local;
* preenche o `service.uuid` no `tunnelhub.yml`.

## O que acontece no deploy

Ao executar `deploy-automation`, a CLI valida o `tunnelhub.yml`, verifica `package.artifact`, faz upload do artefato para S3 e solicita a criação do deploy.

O parâmetro `--message` é obrigatório. Ele deve carregar o contexto humano do deploy, especialmente em pipelines.

No fluxo CI/CD:

* a credencial é da account e pode ser autorizada para um ou mais ambientes;
* `createdBy` da revisão fica como `api-client:<clientId>`;
* a mensagem do deploy deve trazer o contexto do commit, autor e execução quando isso for relevante.

Exemplo de variáveis de ambiente para CI/CD:

* `TH_API_HOST`
* `TH_CLIENT_ID`
* `TH_CLIENT_SECRET`
* `TH_ENVIRONMENT_ID`
* `TH_AUTOMATION_ID`

Exemplo com GitHub Actions:

```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}"
```

Consulte [Deploy via CI/CD](/cli/ci-cd-deployments.md), [Autenticação e ambientes](/cli/authentication-and-environments.md), [Comandos e referência](/cli/commands.md) e [`tunnelhub.yml`](/cli/tunnelhub-yml.md) para o contrato completo.