Referencia completa del CLI

Todos los comandos heroctl con sinopsis, flags y ejemplo. Úsalo como chuleta de mesa.

Operaciones·20 min·última revisión 2026-04-26

Esta página lista todos los comandos del binario heroctl. Úsala como referencia de mesa, no como tutorial. Para introducción, empieza en Instalación.

Modos del binario

El mismo ejecutable cambia de rol por la flag inicial.

`heroctl server`

Inicia el plano de control. Corre como servicio systemd en producción.

sudo heroctl server --bootstrap --advertise 10.0.0.1

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

`heroctl agent`

Inicia un worker. Ejecuta contenedores y reporta salud.

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)

Sin flag de modo, el binario se vuelve cliente. Lee la dirección del servidor de la variable HEROCTL_ADDR o de la flag --addr.

Cluster

Comandos que cambian la topología del plano de control.

`heroctl cluster init`

Crea el primer nodo. Corre una vez por instalación.

sudo heroctl cluster init --advertise 10.0.0.1

Salida: cluster initialized, node-id: node-1.

`heroctl cluster join`

Agrega un servidor al 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`

Genera token firmado con TTL.

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

`heroctl cluster status`

Visión general del plano de control.

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

`heroctl cluster leave`

Remueve el nodo actual del cluster con salida ordenada.

sudo heroctl cluster leave

Atención: salir sin drain antes interrumpe los contenedores corriendo. Drena siempre primero.

Nodos

Comandos que afectan a un nodo individual.

`heroctl node list`

Lista todos los nodos con status.

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

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

`heroctl node info`

Detalles de un nodo: recursos, allocs, eventos.

heroctl node info node-2

`heroctl node drain`

Mueve workloads a otros nodos e impide nuevos jobs. Úsalo antes de mantenimiento.

heroctl node drain node-2 --deadline 5m

Flags: --deadline, --force (no espera).

`heroctl node eligibility`

Marca un nodo como elegible o no para recibir workloads.

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

Jobs

Definición de aplicación. Corazón del sistema.

`heroctl job submit`

Envía un spec YAML al cluster.

heroctl job submit app.yaml

Flags: --detach (no acompaña), --no-rolling (deploy inmediato).

`heroctl job list`

Todos los jobs del cluster.

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

`heroctl job status`

Estado detallado de un job: tasks, allocs, eventos.

heroctl job status api-vendas

`heroctl job restart`

Reinicia todas las réplicas con la misma versión. Útil tras cambiar secretos.

heroctl job restart api-vendas

`heroctl job stop`

Detiene el job y remueve los contenedores.

heroctl job stop api-vendas --purge

La flag --purge borra historial. Sin ella, el job queda en stopped y puede volver con submit.

`heroctl job scale`

Altera la cantidad de réplicas sin nuevo deploy.

heroctl job scale api-vendas web=4

`heroctl job revert`

Vuelve a una versión anterior.

heroctl job revert api-vendas --version 2

Allocations

Una alloc es una réplica corriendo en un nodo.

`heroctl alloc list`

Lista réplicas de un job.

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

`heroctl alloc info`

Detalles: imagen, recursos, eventos, restarts.

heroctl alloc info web-c3d4

`heroctl alloc stop`

Mata una réplica. El cluster la recrea en otro nodo.

heroctl alloc stop web-c3d4

`heroctl alloc restart`

Reinicia el contenedor manteniendo la alloc.

heroctl alloc restart web-c3d4

`heroctl alloc logs`

Atajo para heroctl logs --alloc.

heroctl alloc logs web-c3d4 --since 10m

Secretos

Valores sensibles inyectados en runtime.

`heroctl secret create`

Crea un secreto.

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

`heroctl secret list`

Lista nombres (los valores nunca aparecen).

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

`heroctl secret get`

Muestra metadata. El valor solo sale con --reveal y auditoría.

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

`heroctl secret update`

Crea nueva versión. Los jobs que la referencian la toman en el próximo reinicio.

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

`heroctl secret delete`

Remueve. Falla si algún job activo la referencia.

heroctl secret delete db-password

Deploys

Cada job submit crea un deploy. Los comandos abajo controlan ese proceso.

`heroctl deploy list`

Historial de deploys.

heroctl deploy list --job api-vendas

`heroctl deploy status`

Progreso actual.

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

`heroctl deploy pause`

Congela un rolling update en curso. Las allocs ya cambiadas quedan nuevas, las restantes esperan.

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

`heroctl deploy resume`

Continúa un deploy pausado.

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

`heroctl deploy abort`

Cancela y revierte a la versión anterior.

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

Ingress

Dominios públicos ruteados a jobs.

`heroctl ingress list`

Todos los dominios activos.

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

`heroctl ingress info`

Detalles de un dominio: backends, certificado, métricas.

heroctl ingress info api.minhaempresa.com

Métricas

`heroctl metrics status`

Estado del colector interno.

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

`heroctl metrics query`

Consulta ad-hoc por nombre de métrica.

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

Logs

`heroctl logs`

Una interfaz, tres objetivos.

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 del estado completo del cluster.

`heroctl snapshot save`

Guarda snapshot en archivo.

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

La salida incluye tamaño y hash. Guárdalo en lugar seguro fuera del cluster.

`heroctl snapshot restore`

Restaura el cluster a partir de archivo.

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

Atención: restore reescribe el estado actual. Úsalo solo en recuperación de desastre, con el cluster fuera del aire.

`heroctl snapshot inspect`

Muestra metadata sin 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

Otros

`heroctl status`

Resumen general. Combina cluster + jobs + nodos + ingress en una pantalla.

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

`heroctl version`

Versión del binario y build.

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

Variables de entorno útiles

Variable	Función	Ejemplo
`HEROCTL_ADDR`	dirección del servidor	`https://manage.exemplo.com`
`HEROCTL_TOKEN`	token de auth	`eyJh...`
`HEROCTL_NAMESPACE`	namespace activo	`production`
`HEROCTL_FORMAT`	formato de salida por defecto	`json`, `yaml`, `table`

Configúralas en el shell para evitar repetir flags en cada comando.

#cli#referencia#comandos

Volver al índice