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

npm install -g @tunnelhub/cli

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

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

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.

tunnelhub login

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

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:

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, Autenticação e ambientes, Comandos e referência e tunnelhub.yml para o contrato completo.