# jackin prune (https://jackin.tailrocks.com/commands/prune/)



## Synopsis [#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.

Each prune command prints the phase it is running, then one aligned status row per deletion. Rows start before the deletion runs and finish with a colored `OK`, `SKIP`, or `FAILED` status; skip and failure details appear on the following line.

## Subcommands [#subcommands]

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

## `jackin prune roles` [#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` [#jackin-prune-cache]

```bash
jackin prune cache
```

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

## `jackin prune images` [#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` [#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 [#options]

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

## `jackin prune system` [#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 [#options-1]

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

## Examples [#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 [#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` [#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.