Skip to content
SHC Docs

shc inspect

Dump a stack’s files + runtime snapshot in one call.

shc inspect <stack> calls GET /api/method/shc.stack.inspect and prints the file bundle (rendered compose, vars, plugs/sockets, jobs, the persisted state JSON, the backup manifest), then a containers table: one row per container with its node, name, state, image and, where the runtime gives one, its health. An image the answer does not name is an empty cell, and a column no container fills is left out. The answer also carries a runtime snapshot, which the HUD and the console read:

  • composed_config: parsed docker compose config --format json output (best-effort, omitted if compose can’t resolve).
  • containers: every container that carries the deployment’s three shc.* labels, on each node a replica is bound to, whatever compose project made it (replica projects included). A docker or podman node answers from its docker API: state, status, image, and a Health field enriched from the metrics stats cache. An incus or apple node answers through its own runtime: name, state, health and, on incus, the image. Status is docker’s own sentence and is empty there.
  • health_rollup: healthy / starting / unhealthy / unknown summary of the container set, same precedence as the HUD Stack panel.
  • placement: where the install put the deployment and why: the node, the rule that chose it (operator, engine, existing-stack, local), the reason, and the scorer’s factors when the scorer ranked the nodes. A factor the node could not answer has no value and reads unmeasured. shc inspect prints it first; an install prints none of it.
  • created_at / updated_at / status_changed_at: timestamps from the deployment row. status_changed_at bumps only on a real status flip via Service.UpdateStatus.
  • warnings: what the daemon could not read, each with its reason: a bound node that did not answer, or one whose runtime could not be listed. The containers of the nodes it did read stay in containers. shc inspect prints the files and the containers it has, then exits non-zero naming each warning.

shc inspect <stack> -o json (or -o yaml) prints the whole answer instead, placement included, and exits non-zero on its warnings the same way.