---
title: microvm cost
description: What a run cost, or what a plan will cost. Every figure labelled
---

## 1. Synopsis

What a run cost, or what a plan will cost. Every figure labelled

```sh
microvm cost [options]
```

## 2. Parameters

| Parameter | Kind | Type | Required | Default | Choices | Help |
| --- | --- | --- | --- | --- | --- | --- |
| `--estimate` | flag | `boolean` | no | none | any | Treat the durations as a plan rather than as timings |
| `--compare` | flag | `boolean` | no | none | any | Also print running versus suspended for the same hold, with the break-even |
| `--memory` | flag | `enum` | no | `2048` | `512`, `1024`, `2048`, `4096`, `8192` | Baseline MiB, selecting a documented size class |
| `--running-sec` | flag | `string` | no | `0` | any | Seconds the VM spent, or will spend, RUNNING |
| `--suspended-sec` | flag | `string` | no | `0` | any | Seconds spent suspended. Storage only — no compute line at all |
| `--build-sec` | flag | `string` | no | `0` | any | Seconds the image build took |
| `--image-gb` | flag | `string` | no | none | any | Image size in GB. Adds storage with its one-week minimum retention |
| `--cycles` | flag | `string` | no | `1` | any | Suspend/resume cycles, each paying a snapshot write plus a read |
| `--hold-sec` | flag | `string` | no | `3600` | any | The hold to compare running against suspended over, in seconds |
| `--max-cost` | flag | `string` | no | none | any | A budget in USD the report's total is checked against (#77) |
| `--on-breach` | flag | `enum` | no | none | `warn`, `abort` | What a `--max-cost` breach does: warn and exit 0, or abort with ERR\_PRECONDITION (exit 12) |

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.cost`. Its `data` object carries these keys: `report`, `comparison`, `budget`.

[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 `cost` 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.