Referência completa do CLI

Todos os comandos heroctl com sinopse, flags e exemplo. Use como cola de mesa.

Operações·20 min·Atualizado em 26 de abril de 2026

Esta página lista todos os comandos do binário heroctl. Use como referência de mesa, não como tutorial. Para introdução, comece em Instalação.

Modos do binário

O mesmo executável muda de papel pela flag inicial.

`heroctl server`

Inicia o plano de controle. Roda como serviço systemd em produção.

sudo heroctl server --bootstrap --advertise 10.0.0.1

Flags principais: --bootstrap, --advertise, --config, --data-dir.

`heroctl agent`

Inicia um worker. Executa contêineres e reporta saúde.

sudo heroctl agent --token <T> --advertise 10.0.0.10 --servers 10.0.0.1:8080,10.0.0.2:8080,10.0.0.3:8080

Flags: --token, --advertise, --servers, --node-class.

`heroctl <cmd>` (modo CLI)

Sem flag de modo, o binário vira cliente. Lê endereço do servidor da variável HEROCTL_ADDR ou da flag --addr.

Cluster

Comandos que mudam a topologia do plano de controle.

`heroctl cluster init`

Cria o primeiro nó. Roda uma vez por instalação.

sudo heroctl cluster init --advertise 10.0.0.1

Saída: cluster initialized, node-id: node-1.

`heroctl cluster join`

Adiciona um servidor ao cluster existente.

sudo heroctl cluster join --token <T> --advertise 10.0.0.2 --servers 10.0.0.1:8080

Flags: --token, --advertise, --servers, --role (server|agent).

`heroctl cluster join-token`

Gera token assinado com TTL.

heroctl cluster join-token --ttl 1h --role server
# eyJhbGciOi...8X7Z

`heroctl cluster status`

Visão geral do plano de controle.

heroctl cluster status
# cluster: 3 nodes, quorum: ok, leader: node-1

`heroctl cluster leave`

Remove o nó atual do cluster com saída ordenada.

sudo heroctl cluster leave

Atenção: sair sem drain antes interrompe os contêineres rodando. Sempre drene primeiro.

Nós

Comandos que afetam um nó individual.

`heroctl node list`

Lista todos os nós com status.

heroctl node list
# node-1  server  ready   3.2 GB free   2 jobs

Flags: --filter status=ready, --json.

`heroctl node info`

Detalhes de um nó: recursos, allocs, eventos.

heroctl node info node-2

`heroctl node drain`

Move workloads para outros nós e impede novos jobs. Use antes de manutenção.

heroctl node drain node-2 --deadline 5m

Flags: --deadline, --force (não espera).

`heroctl node eligibility`

Marca um nó como elegível ou não para receber workloads.

heroctl node eligibility node-2 --ineligible
heroctl node eligibility node-2 --eligible

Jobs

Definição de aplicação. Coração do sistema.

`heroctl job submit`

Envia um spec YAML ao cluster.

heroctl job submit app.yaml

Flags: --detach (não acompanha), --no-rolling (deploy imediato).

`heroctl job list`

Todos os jobs do cluster.

heroctl job list
# api-vendas    running   2/2   v3   2h
# worker-email  running   1/1   v1   5d

`heroctl job status`

Estado detalhado de um job: tasks, allocs, eventos.

heroctl job status api-vendas

`heroctl job restart`

Reinicia todas as réplicas com a mesma versão. Útil após mudar segredos.

heroctl job restart api-vendas

`heroctl job stop`

Para o job e remove os contêineres.

heroctl job stop api-vendas --purge

Flag --purge apaga histórico. Sem ela, o job fica em stopped e pode voltar com submit.

`heroctl job scale`

Altera contagem de réplicas sem novo deploy.

heroctl job scale api-vendas web=4

`heroctl job revert`

Volta para uma versão anterior.

heroctl job revert api-vendas --version 2

Allocations

Uma alloc é uma réplica rodando em um nó.

`heroctl alloc list`

Lista réplicas de um job.

heroctl alloc list --job api-vendas
# web-c3d4   node-1   running   healthy   2h

`heroctl alloc info`

Detalhes: imagem, recursos, eventos, restarts.

heroctl alloc info web-c3d4

`heroctl alloc stop`

Mata uma réplica. O cluster recria em outro nó.

heroctl alloc stop web-c3d4

`heroctl alloc restart`

Reinicia o contêiner mantendo a alloc.

heroctl alloc restart web-c3d4

`heroctl alloc logs`

Atalho para heroctl logs --alloc.

heroctl alloc logs web-c3d4 --since 10m

Segredos

Valores sensíveis injetados em runtime.

`heroctl secret create`

Cria um segredo.

heroctl secret create db-password --value 'sN9kL...'
heroctl secret create tls-cert --file ./cert.pem

`heroctl secret list`

Lista nomes (valores nunca aparecem).

heroctl secret list
# NAME            VERSION  CREATED
# db-password     3        2d ago
# jwt-secret      1        5d ago

`heroctl secret get`

Mostra metadata. O valor só sai com --reveal e auditoria.

heroctl secret get db-password
heroctl secret get db-password --reveal

`heroctl secret update`

Cria nova versão. Jobs que referenciam pegam na próxima reinicialização.

heroctl secret update db-password --value 'nNnK7...'

`heroctl secret delete`

Remove. Falha se algum job ativo referencia.

heroctl secret delete db-password

Deploys

Cada job submit cria um deploy. Comandos abaixo controlam esse processo.

`heroctl deploy list`

Histórico de deploys.

heroctl deploy list --job api-vendas

`heroctl deploy status`

Progresso atual.

heroctl deploy status dep-2026-04-26-001
# strategy: rolling, progress: 2/2, state: complete

`heroctl deploy pause`

Congela um rolling em andamento. Allocs já trocadas ficam novas, restantes esperam.

heroctl deploy pause dep-2026-04-26-001

`heroctl deploy resume`

Continua um deploy pausado.

heroctl deploy resume dep-2026-04-26-001

`heroctl deploy abort`

Cancela e reverte para versão anterior.

heroctl deploy abort dep-2026-04-26-001

Ingresso

Domínios públicos roteados para jobs.

`heroctl ingress list`

Todos os domínios ativos.

heroctl ingress list
# api.minhaempresa.com   api-vendas/web   tls   2 backends

`heroctl ingress info`

Detalhes de um domínio: backends, certificado, métricas.

heroctl ingress info api.minhaempresa.com

Métricas

`heroctl metrics status`

Estado do coletor interno.

heroctl metrics status
# scraping: 14 targets, last_run: 12s ago

`heroctl metrics query`

Consulta ad-hoc por nome de métrica.

heroctl metrics query 'cpu_usage{job="api-vendas"}' --range 1h

Logs

`heroctl logs`

Uma interface, três alvos.

heroctl logs --job api-vendas
heroctl logs --alloc web-c3d4
heroctl logs --job api-vendas --task web -f

Flags importantes: -f (follow), --since 10m, --until '2026-04-26T18:00', --grep ERROR.

Snapshot

Backup do estado completo do cluster.

`heroctl snapshot save`

Salva snapshot em arquivo.

heroctl snapshot save backup-2026-04-26.snap

Saída inclui tamanho e hash. Guarde em local seguro fora do cluster.

`heroctl snapshot restore`

Restaura cluster a partir de arquivo.

sudo heroctl snapshot restore backup-2026-04-26.snap

Atenção: restore reescreve o estado atual. Use apenas em recuperação de desastre, com cluster fora do ar.

`heroctl snapshot inspect`

Mostra metadata sem aplicar.

heroctl snapshot inspect backup-2026-04-26.snap
# created: 2026-04-26 14:00 UTC
# jobs: 12, secrets: 8, nodes: 4
# size: 2.4 MB

Outros

`heroctl status`

Resumo geral. Combina cluster + jobs + nós + ingresso em uma tela.

heroctl status
# cluster:  3 nodes (ok)
# jobs:     5 running, 0 failed
# allocs:   12/12 healthy
# ingress:  3 domains, all certs valid

`heroctl version`

Versão do binário e build.

heroctl version
# heroctl 1.0.0 (commit abc123, build 2026-04-20)

Variáveis de ambiente úteis

Variável	Função	Exemplo
`HEROCTL_ADDR`	endereço do servidor	`https://manage.exemplo.com`
`HEROCTL_TOKEN`	token de auth	`eyJh...`
`HEROCTL_NAMESPACE`	namespace ativo	`production`
`HEROCTL_FORMAT`	formato de saída padrão	`json`, `yaml`, `table`

Configure no shell para evitar repetir flags em cada comando.

#cli#referencia#comandos

Voltar para o índice