nkapp volumes prune

Remove orphaned Nanokit-managed volumes. It reuses the same authoritative selection helper the Hub's prune action runs, so the CLI and the dashboard always agree on what is prunable.

nkapp volumes prune [options]

A side-effect-free preview is always rendered first — a table of the volumes that would be pruned plus a skipped count. --dry-run stops there.

---

What gets pruned

A volume is removed only when all of these hold:

Guard	Rule
Orphan	It is not referenced by nanokit.yml
Non-system	It is not one of Nanokit's own system volumes
Destroyable	It is marked as safe to destroy
Not in use	No container currently mounts it

The set is re-derived from a fresh inventory at the moment of the request, not from a cached state file.

Volumes hold your data

Orphan status is computed from the current nanokit.yml. A database volume for a service you temporarily commented out of the config counts as an orphan. Always read the --dry-run table before confirming.

---

Options

Flag	Type	Default	Description
-e, --env <env>	string	local	Environment to use
--ssh <host>	string	—	Target an explicit host (e.g. root@1.2.3.4), overriding the environment's configured deploy target — prunes stranded / cross-host orphan volumes
-p, --port <port>	number	22	SSH port (used with --ssh)
-i, --ssh-key <path>	string	—	SSH private key override (used with --ssh)
--provider <name>	string	all	Only prune volumes from this provider
--name <volume>	string[]	—	Only consider these volumes. Repeatable (--name a --name b) or comma-separated (--name a,b)
--dry-run	boolean	false	List the orphaned volumes that would be pruned, change nothing
-y, --yes	boolean	false	Skip the confirmation prompt

---

Pruning specific volumes (--name)

--name narrows the prune to the volumes you name. It never widens it: every guard above still applies. The preview adds a Requested Volumes table with one row per name:

Outcome	Meaning	Exit
Prune	An eligible orphan — pruned after the usual confirmation	0
Skipped	It fails a guard. The reason is shown: declared in nanokit.yml, a system volume, not destroyable, in use by a container, or excluded by --provider. It is never removed, and there is no way to force it	0
Unknown	No volume with that name in the environment. Nothing is pruned, not even the other names	1

An unknown name is an error so that a typo can never look like a run that succeeded and pruned nothing. This applies under --dry-run too.

---

Examples

# Always start here
nkapp volumes prune --dry-run

# Prune local orphans
nkapp volumes prune -y

# Prune orphan volumes on the staging host
nkapp volumes prune -e stage --dry-run

# Prune only two named orphans
nkapp volumes prune --name nk-acme-local-old-cache,nk-acme-local-tmp --dry-run

# Target a stranded host directly
nkapp volumes prune --ssh root@1.2.3.4 -i ~/.ssh/id_rsa --dry-run

Execution is best-effort: per-volume failures are aggregated and reported, and any failure exits non-zero.

See also

• nkapp containers prune — stale containers
• nkapp images prune — unused images
• nkapp destroy -v — remove a project's volumes along with its containers