Complete CLI reference

All heroctl commands with synopsis, flags, and example. Use as a desk reference.

Operations·20 min read·last reviewed 2026-04-26

This page lists every command of the heroctl binary. Use as a desk reference, not as a tutorial. For an introduction, start at Installation.

Binary modes

The same executable changes role via the initial flag.

`heroctl server`

Starts the control plane. Runs as a systemd service in production.

sudo heroctl server --bootstrap --advertise 10.0.0.1

Main flags: --bootstrap, --advertise, --config, --data-dir.

`heroctl agent`

Starts a worker. Runs containers and reports health.

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>` (CLI mode)

Without a mode flag, the binary becomes a client. It reads the server address from the HEROCTL_ADDR variable or the --addr flag.

Cluster

Commands that change the control plane topology.

`heroctl cluster init`

Creates the first node. Runs once per install.

sudo heroctl cluster init --advertise 10.0.0.1

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

`heroctl cluster join`

Adds a server to an existing cluster.

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`

Generates a signed token with TTL.

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

`heroctl cluster status`

Overview of the control plane.

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

`heroctl cluster leave`

Removes the current node from the cluster with an orderly exit.

sudo heroctl cluster leave

Warning: leaving without drain first interrupts running containers. Always drain first.

Nodes

Commands that affect an individual node.

`heroctl node list`

Lists all nodes with status.

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

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

`heroctl node info`

Details of a node: resources, allocs, events.

heroctl node info node-2

`heroctl node drain`

Moves workloads to other nodes and prevents new jobs. Use before maintenance.

heroctl node drain node-2 --deadline 5m

Flags: --deadline, --force (does not wait).

`heroctl node eligibility`

Marks a node as eligible or not to receive workloads.

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

Jobs

Application definition. Heart of the system.

`heroctl job submit`

Sends a YAML spec to the cluster.

heroctl job submit app.yaml

Flags: --detach (does not follow), --no-rolling (immediate deploy).

`heroctl job list`

All cluster jobs.

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

`heroctl job status`

Detailed state of a job: tasks, allocs, events.

heroctl job status api-vendas

`heroctl job restart`

Restarts all replicas with the same version. Useful after changing secrets.

heroctl job restart api-vendas

`heroctl job stop`

Stops the job and removes containers.

heroctl job stop api-vendas --purge

The --purge flag erases history. Without it, the job stays in stopped and can come back with submit.

`heroctl job scale`

Changes replica count without a new deploy.

heroctl job scale api-vendas web=4

`heroctl job revert`

Goes back to a previous version.

heroctl job revert api-vendas --version 2

Allocations

An alloc is a replica running on a node.

`heroctl alloc list`

Lists replicas of a job.

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

`heroctl alloc info`

Details: image, resources, events, restarts.

heroctl alloc info web-c3d4

`heroctl alloc stop`

Kills a replica. The cluster recreates it on another node.

heroctl alloc stop web-c3d4

`heroctl alloc restart`

Restarts the container while keeping the alloc.

heroctl alloc restart web-c3d4

`heroctl alloc logs`

Shortcut for heroctl logs --alloc.

heroctl alloc logs web-c3d4 --since 10m

Secrets

Sensitive values injected at runtime.

`heroctl secret create`

Creates a secret.

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

`heroctl secret list`

Lists names (values never appear).

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

`heroctl secret get`

Shows metadata. The value only comes out with --reveal and audit.

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

`heroctl secret update`

Creates a new version. Jobs that reference it pick up at the next restart.

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

`heroctl secret delete`

Removes. Fails if any active job references it.

heroctl secret delete db-password

Deploys

Each job submit creates a deploy. The commands below control that process.

`heroctl deploy list`

Deploy history.

heroctl deploy list --job api-vendas

`heroctl deploy status`

Current progress.

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

`heroctl deploy pause`

Freezes a rolling update in progress. Already-swapped allocs stay new, the rest wait.

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

`heroctl deploy resume`

Continues a paused deploy.

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

`heroctl deploy abort`

Cancels and reverts to the previous version.

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

Ingress

Public domains routed to jobs.

`heroctl ingress list`

All active domains.

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

`heroctl ingress info`

Details of a domain: backends, certificate, metrics.

heroctl ingress info api.minhaempresa.com

Metrics

`heroctl metrics status`

State of the internal collector.

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

`heroctl metrics query`

Ad-hoc query by metric name.

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

Logs

`heroctl logs`

One interface, three targets.

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

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

Snapshot

Backup of the complete cluster state.

`heroctl snapshot save`

Saves a snapshot to a file.

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

Output includes size and hash. Keep in a safe place outside the cluster.

`heroctl snapshot restore`

Restores the cluster from a file.

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

Warning: restore overwrites the current state. Use only in disaster recovery, with the cluster offline.

`heroctl snapshot inspect`

Shows metadata without applying.

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

Others

`heroctl status`

General summary. Combines cluster + jobs + nodes + ingress in a single screen.

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

`heroctl version`

Binary version and build.

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

Useful environment variables

Variable	Function	Example
`HEROCTL_ADDR`	server address	`https://manage.exemplo.com`
`HEROCTL_TOKEN`	auth token	`eyJh...`
`HEROCTL_NAMESPACE`	active namespace	`production`
`HEROCTL_FORMAT`	default output format	`json`, `yaml`, `table`

Configure in your shell to avoid repeating flags on every command.

#cli#reference#commands

Back to index