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

tunnelhub login

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

Fallback:

tunnelhub login --password

Verificação de sessão

tunnelhub login-check

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

Logout

tunnelhub logout

Remove credenciais locais salvas pela CLI.

Listagem de ambientes

tunnelhub list-environments

Saída de máquina:

tunnelhub list-environments --json

Listagem de pacotes

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

tunnelhub create-package --env DEV

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

Listagem de automações

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

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

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:

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

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, Autenticação e ambientes e tunnelhub.yml.