---
title: microvm ls
description: List what this CLI created and could not confirm it deleted; --remote asks the account too
---

## 1. Synopsis

List what this CLI created and could not confirm it deleted; `--remote` asks the account too

```sh
microvm ls [options]
```

## 2. Parameters

| Parameter | Kind | Type | Required | Default | Choices | Help |
| --- | --- | --- | --- | --- | --- | --- |
| `--state-dir` | flag | `path` | no | none | any | Where the ledgers live. Defaults to $MICROVM\_STATE\_DIR or ~/.microvm/runs |
| `--watch` | flag | `boolean` | no | none | any | Re-read the ledger on an interval until Ctrl-C, port-forward style (#78) |
| `--interval-sec` | flag | `string` | no | `2` | any | Seconds between ledger re-reads under `--watch`; default 2 |
| `--max-refreshes` | flag | `string` | no | none | any | Stop after this many snapshots instead of on Ctrl-C |
| `--remote` | flag | `boolean` | no | none | any | Ask the account too: list live MicroVMs and images and mark each ledger entry live, gone, or unjudged |
| `--prune` | flag | `boolean` | no | none | any | Remove the ledger files of `gone` entries. Requires `--remote` |
| `--region` | flag | `enum` | no | none | `us-east-1`, `us-east-2`, `us-west-2`, `eu-west-1`, `ap-northeast-1` | AWS region. Defaults to $AWS\_REGION, then $AWS\_DEFAULT\_REGION, then us-east-1 |
| `--unlisted-region` | flag | `string` | no | none | any | Use a region this client has not seen carry MicroVMs. Costs you the diagnostic |

The 3 global flags (`--json`, `--dense`, `--quiet`) are accepted here as on every command, and are left out of the table above for that reason; see [Global flags](/microvms-agentd/reference/#3-global-flags).

## 3. Response

On success stdout carries one envelope whose `type` is `microvm.runs`. Its `data` object carries these keys: `runs`, `watch`, `source`, `remote`, `pruned`.

[The envelope](/microvms-agentd/reference/envelope/) describes the fields around `data`. [Response types](/microvms-agentd/reference/response-types/) lists every `type` the CLI emits and which commands share each one.

## 4. Failures

A failure exits with one of the statuses on [Exit codes](/microvms-agentd/reference/exit-codes/) and writes the error shape on [The envelope](/microvms-agentd/reference/envelope/): a stable `code` to branch on, an `exitCode` that matches the process status, a human-readable `error`, and `suggestions`.

Where a failure is one this project has measured on the platform, the envelope's `finding` names the section of the platform notes that documents it. The exit-code table links each one.

## 5. Provenance

This page is generated from `docs/manifest.json`, the output of `microvm manifest`, which the CLI derives from its own argument tree. This page reads the `ls` entry of `data.commands`. `site/scripts/gen-reference.mjs` writes it into the site's content directory on every `pnpm run sync`, so an edit made here is overwritten by the next run.

To change the page, change the source. Regenerate the source with `mise run manifest` from the repository root; `mise run manifest:check` fails when the committed file no longer matches what the binary emits.