> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# celesto prune

> Reclaim disk space by deleting cached Celesto images from older releases. Preview targets with --dry-run or get machine-readable output with --json.

When you upgrade Celesto, the new release pulls a fresh set of pre-built sandbox images. The images from older releases stay on disk under `~/.smolvm/images/` and slowly add up. The `celesto prune` command finds those leftover image folders and deletes them so you get the space back.

Run it any time after an upgrade. It only touches caches that belong to versions you're no longer using, so your current sandboxes keep working.

<Note>
  `celesto prune` is an alias of [`celesto image prune`](/smolvm/cli/image#prune) — same implementation, same flags. Either name works. The `image` group is the canonical home; the top-level `celesto prune` is kept for backward compatibility.
</Note>

## Synopsis

```bash theme={null} theme={null}
celesto prune [OPTIONS]
celesto image prune [OPTIONS]   # canonical spelling
```

## Options

<ParamField path="--dry-run" type="flag" default="false">
  Show what would be deleted without removing anything. Useful for previewing the targets before you commit.
</ParamField>

<ParamField path="--image-dir" type="path">
  Cache location to prune. Overrides `SMOLVM_IMAGE_DIR` and the default `~/.smolvm/images/`.
</ParamField>

<ParamField path="--json" type="flag" default="false">
  Print results as JSON instead of a formatted table. Useful for scripts and automation.
</ParamField>

## Examples

### Preview before deleting

Always safe to run first — it never deletes:

```bash theme={null} theme={null}
celesto prune --dry-run
```

**Example output:**

```
Stale image caches (2):
  - ~/.smolvm/images/0.0.12/   (412 MB)
  - ~/.smolvm/images/0.0.13/   (487 MB)

Total reclaimable: 899 MB
Dry run complete. No changes made.
```

### Reclaim disk space

Delete the stale caches:

```bash theme={null} theme={null}
celesto prune
```

**Example output:**

```
Removed: ~/.smolvm/images/0.0.12/
Removed: ~/.smolvm/images/0.0.13/
Reclaimed 899 MB.
```

### JSON output for automation

Get a machine-readable report:

```bash theme={null} theme={null}
celesto prune --json
```

The `--json` flag emits a structured object listing the cache directories that were considered, which were removed, and the total bytes reclaimed. Pipe into `jq` to extract specific fields, or combine with `--dry-run` to inspect targets without deleting:

```bash theme={null} theme={null}
celesto prune --dry-run --json | jq .
```

## What gets deleted

`celesto prune` only removes cached image folders for Celesto versions other than the one currently installed. The current version's cache is preserved.

It does not touch:

* Running sandboxes or their state
* Custom images you built with [`ImageBuilder`](/smolvm/api/imagebuilder)
* Snapshots stored under `~/.smolvm/snapshots/`
* SSH keys under `~/.smolvm/keys/`

<Note>
  If you upgrade Celesto frequently, run `celesto prune` periodically to keep your cache footprint small. Each release ships a fresh set of pre-built rootfs and kernel artifacts.
</Note>

## Exit codes

| Code | Description                              |
| ---- | ---------------------------------------- |
| `0`  | Success — caches removed (or none found) |
| `1`  | Error reading or deleting cache files    |

## Related commands

* [`celesto image`](/smolvm/cli/image) — pull, list, inspect, build, save, and remove cached images
* [`celesto sandbox delete`](/smolvm/cli/cleanup) — remove stale sandboxes and free runtime resources
* [`celesto sandbox prune`](/smolvm/cli/sandbox-prune) — sweep disks and logs left behind by deleted sandboxes
* [`celesto doctor`](/smolvm/cli/doctor) — diagnose your install before pruning


## Related topics

- [celesto sandbox prune](/smolvm/cli/sandbox-prune.md)
- [celesto image](/smolvm/cli/image.md)
- [celesto sandbox delete](/smolvm/cli/cleanup.md)
- [celesto update](/smolvm/cli/update.md)
- [CLI overview](/smolvm/cli/overview.md)