Federico Del Gaudio
hum docs Service lifecycle and commands Contents
Back to project
•
2 min read

Service lifecycle and commands

Table of Contents

Commands follow the shape hum <project> <template> <command>.

hum storefront all-services start
hum storefront all-services status
hum storefront all-services plan --json
hum storefront all-services secrets sync
hum storefront all-services restart
hum storefront all-services stop
hum storefront all-services reset --yes

Pass service names after start, stop, restart, plan, or secrets sync to operate on a subset. Use --timeout 20s with stop, restart, or reset to change the grace period before a forced termination.

Graph planning and exclusions

plan resolves the dependency graph and execution order without side effects:

hum storefront all-services plan --exclude legacy-api --exclude-service mailer
  • --exclude TEMPLATE: removes services owned by that template from the root selection. If a remaining service still depends on one, it is reintroduced with a warning.
  • --exclude-service SERVICE: strictly excludes a service; if it remains required, execution fails before contacting providers or Docker.

Secrets sync and reset

  • secrets sync: fetches provider-backed environment sources and updates private cache files without starting services.
  • reset: stops all services and permanently deletes Compose-owned volumes (requires interactive confirmation or --yes).

Detached runtime

Each service receives an independent session and process group. hum redirects its output to persistent files, writes a registry entry atomically, and exits. The registry includes PID and process-group identity, process start time, command, working directory, port, and log paths.

PID identity is verified before signals are sent. Project operations are serialized, and repeated or concurrent starts are idempotent. If a multi-service start partially fails, hum rolls back only the processes created by that invocation.

Dependencies start before their consumers. Shutdown occurs in reverse dependency order. --detach is retained as a deprecated no-op because start is always detached.

Runtime state lives under $XDG_STATE_HOME/hum/<project> or ~/.local/state/hum/<project>.