---
title: jackin prune
description: "Delete cached or stale jackin data in bulk"
---

## Synopsis

```bash
jackin prune <SUBCOMMAND>
```

`jackin prune` removes cached or stale data that jackin manages on your host machine. Unlike `jackin purge`, which targets a specific instance by selector, `prune` operates in bulk across a category of data.

## Subcommands

| Subcommand | What it removes |
|---|---|
| `roles` | Cached role repositories |
| `cache` | Shared caches (terminfo, version-check results) |
| `images` | Unused jackin-managed Docker images |
| `instances` | On-disk state for terminated instances |
| `system` | All of the above, in order |

## `jackin prune roles`

```bash
jackin prune roles
```

Removes the local role-repo cache. Role repos are re-cloned automatically the next time a role that uses them is launched.

## `jackin prune cache`

```bash
jackin prune cache
```

Removes the shared cache directory, including compiled terminfo entries and version-check results. All caches regenerate automatically on the next jackin invocation that needs them.

## `jackin prune images`

```bash
jackin prune images
```

Removes `jk_*` Docker images that have no role containers — running or stopped — that depend on them. Images still in use by a role container are skipped; the final summary reports the count of images removed and skipped. Because Docker images are rebuilt from the role Dockerfile on the next `jackin load`, removing an unused image does not lose any data.

## `jackin prune instances`

```bash
jackin prune instances [--all]
```

Removes on-disk state and index entries for instances in terminal statuses. Pass `--all` to also stop and remove running or recoverable instances.

| Status | Pruned by default | Pruned with `--all` |
|---|---|---|
| `clean_exited` | Yes | Yes |
| `superseded` | Yes | Yes |
| `failed_setup` | Yes | Yes |
| `purged` (tombstones) | Yes — cleared from the index | Yes |
| `crashed` | No | Yes — container is force-removed |
| `preserved_dirty` | No | Yes — container is force-removed |
| `preserved_unpushed` | No | Yes — container is force-removed |
| `restore_available` | No | Yes — container is force-removed |
| `active` / `running` | No | Yes — container is force-removed |

Instances that cannot be pruned because Docker resources are still present (and `--all` was not passed) are listed with a suggestion to use `jackin eject <selector> --purge` instead.

### Options

| Option | Description |
|---|---|
| `--all`, `-a` | Also stop and remove running or recoverable instances |

## `jackin prune system`

```bash
jackin prune system [--yes] [--all]
```

Runs all four subcommands in order: `instances` → `images` → `roles` → `cache`. Prompts for confirmation before proceeding unless `--yes` is passed. By default skips running instances; pass `--all` to stop and remove them too.

When `--all` is passed and all steps succeed, jackin removes its runtime home directory entirely, leaving no managed state on disk.

### Options

| Option | Description |
|---|---|
| `--yes`, `-y` | Skip the confirmation prompt |
| `--all`, `-a` | Also stop and remove running or recoverable instances |

## Examples

```bash
# Free up disk space from terminated instances
jackin prune instances

# Remove all instances including running ones
jackin prune instances --all

# Remove Docker images that are no longer used by any container
jackin prune images

# Remove cloned role repos (will be re-cloned on next launch)
jackin prune roles

# Full cleanup in one command
jackin prune system

# Non-interactive full cleanup (for scripts)
jackin prune system --yes

# Full cleanup including stopping all running containers
jackin prune system --all
```

## What `prune` does not touch

- **Running instances (without `--all`)** — without the `--all` flag, containers that are currently attached or running are never stopped or purged by `prune`. Pass `--all` to include them.
- **Stopped instances with recovery state (without `--all`)** — instances with status `restore_available`, `crashed`, `preserved_dirty`, or `preserved_unpushed` are skipped unless `--all` is passed. Use `jackin hardline` to reconnect or `jackin eject <selector> --purge` to explicitly remove them.
- **Operator config** — `~/.config/jackin/config.toml` and saved workspaces are never modified by `prune`.

## Relationship to `jackin purge`

`jackin purge` targets a single instance by selector and requires an explicit role, instance ID, or container name. `jackin prune instances` does the same job in bulk for every instance already in a terminal state, without requiring the operator to name each one.
