> Documentation index: https://docs.kiste.run/llms.txt, a list of every page in this documentation.

# Manage

> List and inspect Kisten, watch live usage, rename, extend, update to the newest image, read logs and delete.

## List

```bash
kiste list
kiste list --status running
kiste list --status running --status stopped
kiste ls --json
```

Every Kiste with its state, size and age, and a mark when a newer image is
available. `--status` filters by exact states and can be repeated.

## Inspect

```bash
kiste status review-42
kiste status review-42 --usage
```

`status` (also `info` and `inspect`) shows one Kiste: state, size, image
version, lifetime, whether a session is saved, and its
[checkpoints](https://docs.kiste.run/kisten/snapshots.md). `--usage` adds a live sample from inside a
running Kiste: CPU, memory, disk, load and uptime. The console shows the same
when you open an entry under **Machines**.

## Rename

```bash
kiste rename review-42 review-43
```

The new name follows the [naming rules](https://docs.kiste.run/kisten/create.md#names). Its snapshots and
published ports keep working. The host name inside the Kiste changes at its
next update or cold boot. The `instance.renamed` event carries the old name.

Plain `ssh` reaches it under the new name right away: the [SSH
configuration](https://docs.kiste.run/ssh/ssh-config.md) covers every `NAME.kiste`.

## Extend

```bash
kiste extend review-42 --hours 12
kiste extend review-42 --ttl 90m
```

Adds time to the Kiste's [automatic stop](https://docs.kiste.run/kisten/lifecycle.md#automatic-stop-lifetime).
A Kiste without one gets a stop that far from now. `--hours` takes 1 to 720,
`--ttl` seconds or a duration with a unit.

## Update

The platform ships new versions of the Kiste image with fixes and new tools. A
running Kiste is never changed under you; you choose when it moves.

```bash
kiste update                 # which Kisten have an update, and what it brings
kiste update review-42       # update one
kiste update --all --yes     # update every Kiste that has one
```

`kiste upgrade` is the same command. What an update does depends on the
Kiste's state:

| State | `kiste update NAME` |
| --- | --- |
| Running | Reboots the Kiste onto the newest image. The session ends; files and installed packages stay. |
| Stopped with a saved session | Discards the saved session; the Kiste stays stopped and its next start is the update. Resuming instead continues the session on the old image. |
| Stopped without a session | Nothing to do: its next start boots the newest image. |

`kiste restart` applies a pending update as well. The release notes of the
current image are available from the API at
[`GET /v1/runtime/image`](https://docs.kiste.run/api/images.md#get-the-current-image-version).

## Logs

```bash
kiste logs review-42
kiste logs review-42 --tail 500
```

The Kiste's boot and console log, by default the last 100 lines, at most 2000.
Useful when a Kiste is in state `error` or doesn't come up.

## Delete

```bash
kiste delete review-42
kiste delete old-1 old-2 old-3 --yes
kiste rm review-42
```

Permanently deletes the Kiste and its disk. In a terminal the CLI asks for
confirmation; `--yes` skips it, and in `--json` mode or with `--no-input` it is
required. A last checkpoint is taken before the disk goes, and the Kiste's
automatic checkpoints are kept for 14 days so it can still be
[restored](https://docs.kiste.run/kisten/snapshots.md#restore). Named snapshots stay until you delete
them. Its desktop links and published ports end.

> **Warning:** There is no undo
>
> After 14 days, nothing of a deleted Kiste is left except its named snapshots.

## Related topics

- [Overview](https://docs.kiste.run/kisten.md)
- [Create a Kiste](https://docs.kiste.run/kisten/create.md)
- [Lifecycle](https://docs.kiste.run/kisten/lifecycle.md)
- [Checkpoints and snapshots](https://docs.kiste.run/kisten/snapshots.md)
- [Fork](https://docs.kiste.run/kisten/fork.md)
- [Images and environments](https://docs.kiste.run/kisten/images.md)
- [Automation](https://docs.kiste.run/kisten/automation.md)
- Previous: [Fork](https://docs.kiste.run/kisten/fork.md)
- Next: [Images and environments](https://docs.kiste.run/kisten/images.md)