> Documentation index: fetch https://dvmkit.com/llms.txt to find every page before exploring further.

# dvmctl CLI reference (/docs/cli-dvmctl)

Complete reference for the dvmctl builder CLI — every command, flag, JSON output shape, and error anchor.



`dvmctl` is the builder CLI for creating, deploying, and managing DVMs on the dvmkit platform.

Every command that targets a DVM by `<slug>` resolves it only within the active `dvmctl switch` context. Pass `--org <handle>` for a one-shot override; after resolution, the operation is bound to the immutable `dvmId`, never to a global slug fallback.

All commands write JSON to stdout by default. Pass `--human` for prose output. Commands that start servers (`dev`, `serve`, `logs`) stream to stdout until interrupted.

Every JSON payload below is also prefixed with a `trace_id` string. `dvmctl` generates one locally at startup, and the platform's own trace\_id replaces it whenever the command makes a platform call — so a local-only command like `validate` still prints one. Quote it when reporting a problem, and pass it to [`dvmctl trace get`](#trace-get) to see the spans behind a platform call. The samples in this reference omit it, except where a command returns a trace\_id of its own ([`trace get`](#trace-get)). Two outputs carry no `trace_id` at all: [`auth`](#auth) and [`deploy --target self-host`](#deploy), which print their JSON without the wrapper.

Two URLs recur across the DVM payloads and they are not interchangeable. `dvmkitUrl` — `https://<handle>--<slug>.dvmkit.ai` — is the public address you give callers; it is `null` until the owning account claims a handle with [`dvmctl handle set`](#handle-set). `url` is where the DVM answers from outside dvmkit: the same router address for a cloud deploy, whose Fly app has no public address of its own, and your own upstream on the connect tier. There is no `<slug>.dvmkit.ai` — a slug names a DVM only inside its owning org, so it cannot claim a hostname.

Authentication [#authentication]

`dvmctl` authenticates via a long-lived API key. Two ways to supply it:

| Method                   | How                                                                        |
| ------------------------ | -------------------------------------------------------------------------- |
| Interactive browser flow | `dvmctl auth` — opens browser, stores key in `~/.dvmctl/config.json`       |
| Environment variable     | `DVMKIT_API_KEY=dvmk_...` — takes precedence over stored key, useful in CI |

Environment variables [#environment-variables]

| Variable              | Default                  | Description                                                                                           |
| --------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------- |
| `DVMKIT_API_KEY`      | —                        | API key; overrides stored credentials                                                                 |
| `DVMKIT_PLATFORM_URL` | `https://api.dvmkit.dev` | Platform API base URL                                                                                 |
| `DVMKIT_WEB_URL`      | `https://dvmkit.com`     | Web app base URL (used by `dvmctl auth`)                                                              |
| `DVMKIT_CONFIG_DIR`   | `~/.dvmkit`              | Builder state directory: secrets and per-DVM records. See [State directories](#state-directories)     |
| `DVMCTL_CONFIG_DIR`   | `~/.dvmctl`              | Login directory: the stored API key and `switch` context. See [State directories](#state-directories) |

State directories [#state-directories]

`dvmctl` reads and writes three directories on the machine it runs on. Each has a variable that moves it. Set the variable in every environment that runs `dvmctl` against the same state, including a cron or launchd job, which may not see your shell's `HOME`.

| Variable            | Default     | Holds                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DVMKIT_CONFIG_DIR` | `~/.dvmkit` | Builder secrets: `builder.mnemonic` (Cashu lock keys, from [`lock create`](#lock-create)) and `builder.key` (signing identity, from [`identity create`](#identity-create)). `builder.json`: the identity pubkey and one record per DVM (its id, key rotation, and payout default). The payout worker's local files: `melt-pending.log`, `drain-park.log`, `drain-hold.json`, and `melt-success.json` |
| `DVMCTL_CONFIG_DIR` | `~/.dvmctl` | `config.json`: the API key from [`auth`](#auth) and the active [`switch`](#switch) context                                                                                                                                                                                                                                                                                                           |
| `DVM_CONFIG_DIR`    | `~/.dvm`    | The caller CLI's state. `dvmctl` reads it in two places. It moves a builder mnemonic left at the old `recovery.mnemonic` path into `DVMKIT_CONFIG_DIR`. [`doctor`](#doctor) warns when the variable is unset or not a temporary directory, since a local paid test could otherwise spend from the caller's normal wallet, and it lists mnemonic backups left beside the old path                     |

Back up both `builder.mnemonic` and `builder.key`. Neither one restores the other. A [payout worker](/docs/builder-payments#running-the-payout-worker) on another machine needs `builder.mnemonic` and `builder.json` from this directory.

Admin endpoints [#admin-endpoints]

`credit`, `refund`, `content-holds`, `melt-pending`, and `rotate` accept `--mount-prefix <path>` for a DVM mounted under a path. `destroy` accepts it for the admin liability lookup. For example, `--endpoint https://example.com --mount-prefix /feed` targets the DVM at `https://example.com/feed`. The prefix is appended to the explicit or platform-resolved endpoint; omit it if that URL already includes the full mount path. Identity and refund-capability probes use the same mount, and admin signatures bind the full prefixed path.

A prefix starts with `/`, has no trailing slash, and contains no empty or dot segments, query string, or fragment. Omit the option for a root mount; `/` is not a valid prefix. Malformed prefixes return `invalid_mount_prefix`. An endpoint must be an absolute HTTP or HTTPS URL without credentials, a query string, or a fragment; malformed endpoints return `invalid_admin_endpoint`.

Error envelope [#error-envelope]

Same shape as the `dvm` CLI — every failure exits with code `1` and prints:

```json
{
  "error": {
    "code": "auth_required",
    "message": "Not authenticated.",
    "hint": "A human must sign in once. Run `dvmctl auth` and give the printed link and session code to the human; they can open it on any device within 5 minutes, and signing in also creates the account if they have none. If you cannot wait for them or run unattended, ask the human to create an API key in the dashboard and set DVMKIT_API_KEY (https://dvmkit.com/docs/cli-auth.md)."
  },
  "help": "https://discord.gg/aJ8BwVj5G2"
}
```

For platform errors, authentication failures, and deploy failures without a local cause, the top-level `help` field points to the builder Discord. Relay it to the human when they need help. In `--human` mode, the link prints as one line.

Exit codes [#exit-codes]

| Code | Meaning   |
| ---- | --------- |
| `0`  | Success   |
| `1`  | Any error |

***

auth [#auth]

Authenticate with the dvmkit platform. Opens a browser for the interactive consent flow and stores the returned API key at `~/.dvmctl/config.json` (mode `0600`).

```sh
dvmctl auth
dvmctl auth --status
dvmctl auth --logout
```

See [Logging in to dvmkit](/docs/cli-auth) for the full flow, security details, and headless CI usage.

The browser sign-in hint is "Complete sign-in in your browser, then return here." In JSON mode, the `awaiting_human` progress event includes `url`, `fingerprint`, `expires_at`, `browser_opened`, and `instruction`.

Relay the URL and session code to the human; they can open it on any device within five minutes. Keep the command running until it reports `authenticated`. If no browser can open, the event reports `browser_opened: false` and tells the agent to relay the link. If the agent cannot wait or runs unattended, the instruction points to the dashboard API-key route and `DVMKIT_API_KEY`.

Cancellation returns `authenticated: false` and `cancelled: true`, with a hint to run `dvmctl auth` again. Timeout returns `authenticated: false` and `timed_out: true`, with guidance to retry or use `DVMKIT_API_KEY` to skip the browser.

| Flag       | Description                       |
| ---------- | --------------------------------- |
| `--status` | Show current authentication state |
| `--logout` | Remove stored credentials         |
| `--human`  | Prose output                      |

**JSON output — `--status` (authenticated):**

```json
{ "authenticated": true, "account": "you@example.com" }
```

**JSON output — `--logout`:**

```json
{ "status": "logged_out" }
```

***

create [#create]

Scaffold a new DVM project in the current directory.

```sh
dvmctl create my-dvm
dvmctl create my-dvm --price '$0.05' --name "My DVM" --description "Does something useful"
```

Creates a `package.json` with `dvmkit` config, a starter `handler.ts`, and a `Dockerfile` for container deployment. Version `0.20.0` pins new projects to `@dvmkit/sdk@0.28.0`; upgrading dvmctl leaves existing projects' SDK dependencies unchanged.

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--price <price>`      | Static price per request (default: `$0.01`)        |
| `--name <name>`        | DVM display name (default: derived from directory) |
| `--description <text>` | DVM description                                    |

No JSON output — writes files and prints progress to stderr.

***

dev [#dev]

Start a local development server for a DVM handler with hot reload.

```sh
dvmctl dev handler.ts
dvmctl dev handler.ts --port 4000
dvmctl dev handler.ts --no-reload
```

Serves the DVM protocol on the specified port. Runs until interrupted.

Saving the handler or any local file it imports reloads it; packages under `node_modules` are not watched. Each reload loads the handler in a fresh process. If the new code fails to load, the error is printed and the previous version keeps serving until the next save.

| Flag            | Description                                   |
| --------------- | --------------------------------------------- |
| `--port <port>` | HTTP port (default: `PORT` env var or `3000`) |
| `--no-reload`   | Disable hot reload                            |
| `--human`       | Human-readable errors instead of JSON         |

While it runs, all output is informational. If the handler fails to load at startup, the command prints the [error envelope](#error-envelope) with the handler's own message and the file and line it names, then exits with code `1`. If the port can't be opened at startup, the envelope names the port and carries it as `port`, then the command exits with code `1`.

**Error anchors:**

| Code                  | Trigger                                                                                                   |
| --------------------- | --------------------------------------------------------------------------------------------------------- |
| `handler_load_failed` | The handler threw while loading, has a syntax error, or exports no `configureDVM()` result                |
| `dev_port_in_use`     | Another process is already listening on the port, often an earlier `dvmctl dev`. Stop it or pass `--port` |
| `dev_listen_failed`   | The port can't be opened for any other reason, such as a number above `65535`                             |

***

deploy [#deploy]

Deploy a DVM project to the dvmkit cloud or generate a self-host Dockerfile.

```sh
dvmctl deploy
dvmctl deploy --name my-dvm
dvmctl deploy --dry-run
dvmctl deploy --create-identity
dvmctl deploy --target self-host
dvmctl deploy --allow-dirty
```

With no `--target`, deploys to dvmkit cloud. Reads `dvmkit` config from `package.json` in the current directory. Requires authentication. Cloud deploys refuse when packaged files differ from `HEAD`; commit or discard them first, or pass `--allow-dirty` when shipping the uncommitted state is deliberate. `--yes` does not bypass this guard. Local and self-host targets are unaffected.

| Flag                   | Description                                                                                                                                                                                                 |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--target <target>`    | `cloud` (default), `self-host`, or `local`                                                                                                                                                                  |
| `--name <slug>`        | DVM slug for cloud deploy (default: from `package.json`)                                                                                                                                                    |
| `--runtime <runtime>`  | `container` (default) or `isolate`. The hosted builder platform supports containers only, so the platform refuses `isolate` except from operator accounts                                                   |
| `--endpoint-url <url>` | Connect-tier upstream URL (required on plans where the platform doesn't host compute)                                                                                                                       |
| `--local`              | Register a locally-running DVM into the local platform (no Fly), pointing at its localhost URL                                                                                                              |
| `--url <url>`          | Localhost URL the DVM is running at, for `--local` (default `http://localhost:<PORT or 3000>`)                                                                                                              |
| `--dry-run`            | Validate and build locally without contacting platform                                                                                                                                                      |
| `--create-identity`    | Create the builder signing identity when it is absent; intended for noninteractive first deploys                                                                                                            |
| `--yes`                | Skip the SDK-staleness confirmation prompt and proceed automatically                                                                                                                                        |
| `--env-stdin`          | Read a JSON string map from standard input for a cloud deploy; overrides matching `.env` keys without placing secrets in arguments. Invalid or oversized input fails before network access.                 |
| `--allow-dirty`        | Allow a cloud image to include uncommitted packaged files; the image SHA retains its `-dirty` suffix                                                                                                        |
| `--context <dir>`      | Override `package.json#dvmkit.buildContext` for this deploy. Path is relative to the DVM folder, must contain it, and must stay inside the Git repository. With neither setting, defaults to the DVM folder |
| `--org <handle>`       | Deploy under this org, overriding the `dvmctl switch` context                                                                                                                                               |
| `--human`              | Prose output                                                                                                                                                                                                |

Build context [#build-context]

The build context is the folder uploaded for a hosted build or used by Docker during a dry run. By default, it is the DVM folder. To include a containing workspace folder, set `dvmkit.buildContext` in the DVM's `package.json`:

```json
{
  "dvmkit": {
    "buildContext": "../.."
  }
}
```

This example selects the folder two levels above the DVM. The value must be a nonempty relative path to an existing folder that contains the DVM folder and stays inside the Git repository. `--context <dir>` uses the same rules and takes precedence over the package setting. If only the DVM folder should be used, select `"."`.

When neither setting is present, a DVM without its own lockfile is refused if a parent folder inside the repository has one. Set the context explicitly to include that parent, or add a lockfile to the DVM folder to build it alone. The CLI does not choose the parent for you.

JSON output [#json-output]

**Cloud deploy (success):**

```json
{
  "status": "deployed",
  "slug": "my-dvm",
  "url": "https://alice--my-dvm.dvmkit.ai",
  "dvmkitUrl": "https://alice--my-dvm.dvmkit.ai",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "context_root": "/workspace/my-dvm",
  "dockerfile": "Dockerfile"
}
```

`dvmkitUrl` is the address you give callers — `https://<handle>--<slug>.dvmkit.ai`, built from the handle of the org that owns the DVM. A cloud deploy needs that handle: its Fly app is reachable only through the router, so a deploy from an owner without one fails with `handle_required` until the handle is claimed with [`dvmctl handle set`](#handle-set). `url` is the same router address for a cloud deploy, or your own upstream on the connect tier. A DVM is **not** reachable at `<slug>.dvmkit.ai`: slugs repeat across orgs, so a bare name addresses nobody.

For hosted container deploys and their dry runs, `context_root` is the absolute path to the selected build context. `dockerfile` is the Dockerfile path relative to that context. For example, a DVM at `services/my-dvm` with the repository root as its context reports `services/my-dvm/Dockerfile`.

The connect-tier path omits the build-context fields; the `--local` path adds an optional `warning` string when registration succeeded with caveats.

A cloud deploy reports `status` `deployed_unverified` when Fly accepted the release but the deploy could not confirm the new version is serving, for example because the log stream dropped. The result then carries `display`, a `hint` naming the command that checks the served `gitSha`, and `verification_url`, the DVM's `/healthz`. The exit code is the same as for `deployed`.

A cloud deploy adds `x402_listing` when the DVM serves x402 routes, or when the deploy could not confirm the DVM is serving. With routes, it holds Coinbase's validator verdict on each one, in the shape [`x402 listing-check`](#x402-listing-check) returns. Once the routes are known, and before the validator is called, a `{"event":"x402_listing_check","routes":<count>}` progress event is printed to stderr. The check is advisory: it never changes the deploy's `status` or exit code, and a deploy whose `/v1/info` could not be read omits the key. A deploy that could not confirm the DVM is serving reports `x402_listing` as `{"status":"not_checked","routes":[],"hint":"..."}`, and the hint names the command to run once it is. Local, self-host, connect-tier, and dry-run deploys never call the validator.

**Dry run:**

```json
{
  "status": "dry-run-ok",
  "slug": "my-dvm",
  "name": "My DVM",
  "runtime": "container",
  "docker_built": true,
  "dockerfile": "Dockerfile",
  "context_root": "/workspace/my-dvm",
  "vm_config": null,
  "inherit_secrets": ["GROQ_*"]
}
```

`inherit_secrets` is omitted entirely when the project inherits none; `vm_config` is `null` when `package.json` carries no `dvmkit.vm` block.

**Self-host:**

```json
{
  "status": "ready",
  "file": "Dockerfile",
  "target": "self-host",
  "attestation_env": {
    "DVMKIT_BUILDER_PUBKEY": "f2f1d2c3b3382d924d13f55d0a70d0d555239c39a36464980c0b37804ddd1846",
    "DVMKIT_BUILDER_ATTESTATION": "{\"slug\":\"my-dvm\",\"capabilities_hash\":\"709523528f4df152c0cfbb352eda593872fd6bd72543de62ca8d1f0b4c19cdb6\",\"builder_pubkey\":\"f2f1d2c3b3382d924d13f55d0a70d0d555239c39a36464980c0b37804ddd1846\",\"deployed_at\":1747900800}",
    "DVMKIT_BUILDER_SIGNATURE": "ab85e4d1560ac15b5b16f95e3b4f55c5eaa6da6ed903ac6a42c728460d25231616295b13c1d45c4c9e4db94d5ec6e2e92b1416cd5574cc7d4e2d909ac34b1c18"
  }
}
```

`attestation_env` is the set of environment variables you must inject into your self-hosted container so its `/v1/info` advertises a verifiable `builder.pubkey`. `DVMKIT_BUILDER_PUBKEY` is the x-only BIP-340 identity key (64 hex chars — no `02`/`03` prefix), `DVMKIT_BUILDER_ATTESTATION` is the JSON payload as a string, and `DVMKIT_BUILDER_SIGNATURE` is the 64-byte Schnorr signature over it. This is the one `dvmctl` JSON output with no `trace_id` prefix besides [`auth`](#auth).

**Error anchors:**

| Code                          | Trigger                                                                                                                                                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `auth_required`               | Not authenticated                                                                                                                                                                                                  |
| `dirty_worktree`              | Packaged files differ from `HEAD` on a cloud deploy without `--allow-dirty`                                                                                                                                        |
| `build_context_required`      | Neither context setting is present, the DVM folder has no lockfile, and a parent inside the repository has one. Set `dvmkit.buildContext` or pass `--context` to select that parent, or add the DVM's own lockfile |
| `invalid_build_context`       | The selected context is not a nonempty relative path to an existing folder containing the DVM, or it leaves the repository. Correct `dvmkit.buildContext` or `--context`; use `"."` to select the DVM folder alone |
| `handler_not_found`           | Neither `handler.ts` nor `handler.js` exists in the project directory, unless `--endpoint-url` is set. Add a handler or run deploy from your DVM project directory                                                 |
| `missing_dockerfile`          | No `Dockerfile` at the project root. Cloud deploys run as containers, so `dvmctl create` scaffolds one                                                                                                             |
| `isolate_runtime_unavailable` | The platform refused `--runtime isolate`, or a redeploy of a DVM that was on the isolate runtime: that runtime is limited to operator accounts                                                                     |
| `invalid_slug`                | Slug is too short (min 3 chars)                                                                                                                                                                                    |
| `docker_build_failed`         | Local Docker build failed                                                                                                                                                                                          |
| `invalid_dvmkit_config`       | Malformed `dvmkit` field in `package.json`                                                                                                                                                                         |
| `terms_not_accepted`          | The account has not accepted the current Builder Terms; the message names the page to accept them on                                                                                                               |
| `handle_required`             | A cloud deploy from an owner with no handle. The DVM would have no address, so claim one with [`dvmctl handle set`](#handle-set) and deploy again                                                                  |

***

deploy-status [#deploy-status]

Show the current status of a deploy by ID — the recovery handle for a `dvmctl deploy` whose stream was interrupted. The deploy ID is printed in the `deploy` progress events.

```sh
dvmctl deploy-status 3dcc9623-8db4-4c03-9929-a0cd5841c1d2
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

**JSON output:**

```json
{
  "status": "building",
  "url": "https://alice--my-dvm.dvmkit.ai",
  "dvmkitUrl": "https://alice--my-dvm.dvmkit.ai",
  "slug": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "deployId": "3dcc9623-8db4-4c03-9929-a0cd5841c1d2",
  "startedAt": 1747785600000,
  "endedAt": null,
  "error": null
}
```

`status` mirrors the platform deploy state (`pending`, `building`, `deployed`, `failed`). `startedAt`/`endedAt` are epoch-millisecond numbers (`--human` renders them as dates). `url`/`dvmkitUrl` may be `null` until the deploy lands; `endedAt`/`error` are populated once the deploy reaches a terminal state.

***

x402 listing-check [#x402-listing-check]

Ask Coinbase's public x402 validator about each x402 route a deployed DVM serves. It runs the same check a cloud [`deploy`](#deploy) runs, on demand: after a deploy that could not confirm the DVM was serving, after changing a listing, or after the first paid call. The route list comes from the DVM's `/v1/info`. The bare slug resolves in your current org context; `--org` overrides that context once.

```sh
dvmctl x402 listing-check my-dvm
dvmctl x402 listing-check my-dvm --human
```

| Flag             | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `--org <handle>` | Read as this org, overriding the `dvmctl switch` context |
| `--human`        | Prose output                                             |

The check only reports what Coinbase's validator says. It does not list a capability, and a `listed` verdict is not a place in Coinbase's catalog: Coinbase decides what the catalog shows. [Staying in Coinbase's catalog](/docs/builder-x402#staying-in-coinbases-catalog) covers what keeps a listing there.

**JSON output:**

```json
{
  "slug": "my-dvm",
  "dvmkitUrl": "https://alice--my-dvm.dvmkit.ai",
  "x402_listing": {
    "status": "checked",
    "routes": [
      {
        "capability": "uppercase",
        "url": "https://alice--my-dvm.dvmkit.ai/v1/x402/uppercase",
        "status": "listed",
        "index": { "active": false },
        "hint": "Valid, but not in Coinbase's active index yet. Coinbase indexes a route after its first paid call through its facilitator."
      }
    ],
    "note": "Coinbase removes a catalog listing after 30 days without a settlement, so keeping it active is up to you. Curation in the catalog is Coinbase's editorial choice; a valid listing is not a curated one."
  }
}
```

`routes` is empty when the DVM serves no x402 routes. `note` appears when at least one route is `listed` or `listed_with_problems`. Each route's `status` is one of:

| Status                 | Meaning                                                                                                                                                                                                                                                                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `listed`               | The route answers with a valid x402 challenge carrying a catalog listing. `index` appears once Coinbase has indexed the route: `active` says whether the route is served in Coinbase's discovery results, and `last_crawled_at` when Coinbase last crawled it. Until the route is indexed and active, `hint` says so. A failed advisory check still appears in `problems` |
| `listed_with_problems` | The route carries a listing, but some of Coinbase's checks failed. Each one is in `problems`                                                                                                                                                                                                                                                                              |
| `not_listed`           | The route answers with an x402 challenge but carries no listing. Listing is optional; `hint` says how to add one. Problems with the route itself still appear in `problems`                                                                                                                                                                                               |
| `challenge_invalid`    | The route answers 402, but its payment challenge fails Coinbase's checks                                                                                                                                                                                                                                                                                                  |
| `not_x402`             | The route did not answer an unpaid `POST` with HTTP 402                                                                                                                                                                                                                                                                                                                   |
| `unreachable`          | Coinbase could not reach the route, or its address is not public HTTPS. A non-HTTPS route is not sent to the validator                                                                                                                                                                                                                                                    |
| `check_unavailable`    | The validator timed out, failed, or rejected the request. `detail` says which, and suggests a retry when one could help                                                                                                                                                                                                                                                   |

`problems` holds each failed check as `check`, `severity` (`required` or `advisory`), Coinbase's `detail`, and a `fix` where a known one exists. A listed route whose listing icon cannot be fetched, or is not a JPEG, PNG, WebP, or GIF image, also gets an `icon_warning` with a `code` (`icon_unreachable`, `icon_http_error`, or `icon_unsupported_type`) and a `fix`. In JSON mode, when the DVM serves x402 routes, a `{"event":"x402_listing_check","routes":<count>}` progress event on stderr precedes the result.

**Error anchors:**

| Code                    | Trigger                                                                           |
| ----------------------- | --------------------------------------------------------------------------------- |
| `dvm_url_unset`         | The DVM has no public URL yet: it is still deploying, or its owner has no handle  |
| `x402_info_unavailable` | The DVM's `/v1/info` could not be read. Check that it is serving, then retry      |
| `not_found`             | No DVM with this slug exists in the selected org. Check the slug, or pass `--org` |

***

validate [#validate]

Load the DVM handler and lint its capabilities, schemas, examples, prices, and tags alongside `package.json#dvmkit` (vmConfig + inheritSecrets), without contacting the platform. Runs offline — no auth, no network — and exits non-zero with a specific handler or package error. Package validation remains the pre-flight gate inside `dvmctl deploy` and the CI check for first-party DVM manifests.

```sh
dvmctl validate
dvmctl validate --handler src/handler.ts
dvmctl validate --human
```

| Flag               | Description                                                       |
| ------------------ | ----------------------------------------------------------------- |
| `--handler <path>` | Handler module to load (default: `handler.ts`, then `handler.js`) |
| `--human`          | Prose output                                                      |

**JSON output — success:**

```json
{
  "status": "ok",
  "slug": "scribe",
  "name": "Scribe",
  "vm_config": { "memoryMb": 1024, "cpuKind": "shared", "minMachinesRunning": 0, "maxMachines": 3 },
  "inherit_secrets": ["GROQ_*", "REPLICATE_*"]
}
```

**Error anchors:**

| Code                    | Trigger                                                           |
| ----------------------- | ----------------------------------------------------------------- |
| `missing_package_json`  | No `package.json` in the current directory                        |
| `invalid_dvmkit_config` | Malformed `dvmkit` field (bad vmConfig or inheritSecrets pattern) |

***

doctor [#doctor]

Check builder-side state stored under `~/.dvmkit`. The command is local and read-only. It emits a warning when timestamped plaintext copies of an older builder mnemonic remain beside `~/.dvmkit/builder.mnemonic`, including copies beside the legacy `~/.dvmkit/recovery.mnemonic` and `~/.dvm/recovery.mnemonic` paths that builder mnemonic migration replaced; warnings do not change the successful exit code.

```sh
dvmctl doctor
dvmctl doctor --human
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

No check row is emitted when no mnemonic backups exist. With backups present, JSON includes every path and its age so an agent can relay the exact files to review:

```json
{
  "checks": [
    {
      "name": "mnemonic_backups",
      "group": "files",
      "status": "warn",
      "display": "1 plaintext builder-mnemonic backup remains on disk: ~/.dvmkit/builder.mnemonic.2026-08-13T12-00-00-000Z.bak (10 days old).",
      "hint": "Each file contains older recovery words. Deleting it is safe once your password-manager and offline backups are refreshed; until then it is a rescue copy of an earlier derivation root.",
      "details": {
        "count": 1,
        "paths": ["~/.dvmkit/builder.mnemonic.2026-08-13T12-00-00-000Z.bak"],
        "backups": [
          {
            "path": "~/.dvmkit/builder.mnemonic.2026-08-13T12-00-00-000Z.bak",
            "modifiedAt": "2026-08-13T12:00:00.000Z",
            "ageMs": 864000000,
            "ageDays": 10,
            "age": "10 days old"
          }
        ]
      }
    }
  ],
  "summary": { "ok": 0, "warn": 1, "fail": 0 },
  "configDir": "~/.dvmkit",
  "cliVersion": "0.1.0",
  "nodeVersion": "v22.0.0"
}
```

Delete a `.bak` only after refreshing the password-manager and offline copies of the mnemonic. `doctor` never deletes or expires one itself.

***

serve [#serve]

Start a production DVM server for a handler file.

```sh
dvmctl serve handler.ts
dvmctl serve handler.ts --port 8080
dvmctl serve handler.ts --dvm my-dvm
```

Like `dev` but without hot reload. Used inside Dockerfiles for container-runtime DVMs.

| Flag             | Description                                                                                                                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--port <port>`  | HTTP port (default: `PORT` env var or `8080`)                                                                                                                                                                |
| `--dvm <handle>` | Serve under the lock identity `builder.json` holds for `<handle>` — advertises the Cashu lock pubkey derived from your recovery mnemonic instead of whatever `DVMKIT_CASHU_LOCK_PUBKEY` happens to be set to |

Reach for `--dvm` when you self-host. `dvmctl deploy` publishes a lock pubkey derived from your recovery mnemonic, which is what lets `dvmctl melt-pending` and `dvmctl rotate` sign for that DVM later; a hand-rolled `serve` has no such link, so a DVM booted with an unrelated lock key can take Cashu payments it can never melt — and can never park a credit-drain refund, because the admin routes only accept a signature from the key the DVM advertises. The flag derives the pubkey and the DVM id together and prints both at boot. If `DVMKIT_CASHU_LOCK_PUBKEY`, `DVMKIT_DVM_ID`, or `DVMKIT_CANONICAL_DVM_ID` is already set to a conflicting value, the boot refuses with `lock_identity_conflict` rather than silently overriding it.

No JSON output — all output is informational (stderr).

**Error anchors:**

| Code                     | Trigger                                                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `no_builder_mnemonic`    | `--dvm` passed but no mnemonic found — run `dvmctl lock create` first                                                     |
| `dvm_not_initialized`    | `--dvm` passed but no `builder.json` entry for this handle — run `dvmctl deploy`, or `dvmctl init <handle> --self-hosted` |
| `lock_identity_conflict` | `--dvm` derives an identity that contradicts one already set in the environment                                           |

***

list [#list]

List the DVMs in your current org context — the org set by [`switch`](#switch), or your personal account when none is set.

```sh
dvmctl list

# One-off: read a shared org without changing your context
dvmctl list --org my-org
```

| Flag             | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `--org <handle>` | Read as this org, overriding the `dvmctl switch` context |
| `--human`        | Prose output (columnar table)                            |

**JSON output:**

```json
{
  "dvms": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "orgId": "acffd753-105a-4958-9f37-243ac032f332",
      "slug": "my-dvm",
      "name": "My DVM",
      "url": "https://alice--my-dvm.dvmkit.ai",
      "dvmkitUrl": "https://alice--my-dvm.dvmkit.ai",
      "status": "deployed",
      "runtime": "container",
      "dvmMeta": {
        "name": "My DVM",
        "description": "Does something useful",
        "tags": ["text"],
        "price": "$0.01"
      },
      "hidden": false,
      "region": "iad",
      "suspensionReason": null,
      "pausedAt": null,
      "githubRepoFullName": null,
      "gitBranch": null,
      "rootDir": null,
      "entrypoint": null,
      "endpointUrl": null,
      "lastJobAt": 1745000000000,
      "feedbackEnabled": true,
      "createdAt": 1744000000000,
      "updatedAt": 1745000000000,
      "lifetimeRevenueFiatMinor": 14237
    }
  ],
  "org": {
    "id": "acffd753-105a-4958-9f37-243ac032f332",
    "handle": "my-org",
    "role": "admin",
    "personal": false
  }
}
```

Every row is the full builder projection — same field set `info` returns for a single DVM, minus `orgHandle`. `dvmMeta` is the DVM's advertised metadata (`null` until the first successful deploy captures it); the git fields are set only for DVMs wired to git-push deploys; `endpointUrl` only on the connect tier; `lifetimeRevenueFiatMinor` is gross revenue in minor units of your reporting currency (cents for USD).

`org` is the context the list was answered from, so an empty `dvms` array is never ambiguous about *which* org it was empty for. `handle` is `null` and `personal` is `true` when you have no org context set — personal accounts have no public org handle.

`hidden` records discovery visibility: `true` means hidden and `false` means listed. Change it with [`dvmctl visibility`](#visibility). The `--human` table shows a `VISIBILITY` column with `hidden` or `listed`.

The `--human` table's `URL` column shows `dvmkitUrl` — the public address callers use. It falls back to `url` only while you have no handle; see [`info`](#info) below.

***

info [#info]

Show detailed information about a single DVM: metadata, discovery visibility, recent deploys, and custom domains. The bare slug is resolved within your current org context; pass `--org` for a one-off shared-org read without changing `dvmctl switch`.

```sh
dvmctl info my-dvm
```

| Flag             | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `--org <handle>` | Read as this org, overriding the `dvmctl switch` context |
| `--human`        | Prose output                                             |

**JSON output:**

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "dvm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "acffd753-105a-4958-9f37-243ac032f332",
    "slug": "my-dvm",
    "name": "My DVM",
    "url": "https://alice--my-dvm.dvmkit.ai",
    "dvmkitUrl": "https://alice--my-dvm.dvmkit.ai",
    "status": "deployed",
    "runtime": "container",
    "dvmMeta": {
      "name": "My DVM",
      "description": "Does something useful",
      "tags": ["text"],
      "price": "$0.01"
    },
    "hidden": false,
    "region": "iad",
    "suspensionReason": null,
    "pausedAt": null,
    "githubRepoFullName": null,
    "gitBranch": null,
    "rootDir": null,
    "entrypoint": null,
    "endpointUrl": null,
    "lastJobAt": 1745000000000,
    "feedbackEnabled": true,
    "createdAt": 1744000000000,
    "updatedAt": 1745000000000,
    "lifetimeRevenueFiatMinor": 14237,
    "orgHandle": null
  },
  "deploys": [
    {
      "id": "3dcc9623-8db4-4c03-9929-a0cd5841c1d2",
      "dvmId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "deployed",
      "error": null,
      "logs": null,
      "startedAt": 1744999000000,
      "endedAt": 1745000000000,
      "trigger": "cli",
      "commitSha": null,
      "commitRef": null,
      "commitMessage": null,
      "commitAuthorName": null
    }
  ],
  "domains": [
    {
      "id": "7c2ab918-3ef4-4a21-8d6c-0b5e1f9a2d84",
      "orgId": "acffd753-105a-4958-9f37-243ac032f332",
      "dvmId": "550e8400-e29b-41d4-a716-446655440000",
      "domain": "my-dvm.example.com",
      "status": "verified",
      "verificationAttemptedAt": 1745000000000,
      "createdAt": 1744900000000,
      "updatedAt": 1745000000000
    }
  ]
}
```

`dvmkitUrl` is the public address callers use — `https://<handle>--<slug>.dvmkit.ai`, resolved from the owning handle (your builder handle, or the org's for an org-owned DVM). It is `null` until you claim a handle with [`dvmctl handle set`](#handle-set). `url` is the same router address for a cloud DVM, or your own upstream on the connect tier. `orgHandle` is set only when a *shared* org owns the DVM; a personal org reports `null`.

`deploys[].status` is the deploy-lifecycle enum (`pending`, `building`, `deployed`, `failed`) and `trigger` is how it was started (`cli`, `push`, `redeploy`, `rollback`); the `commit*` fields are populated for git-push deploys only. `dvm.status` is the DVM-lifecycle enum (`created`, `deploying`, `deployed`, `deploy_failed`, `destroyed`, `suspended`), and when it reads `suspended`, `suspensionReason` says who put it down — `builder_pause` is your own [`dvmctl pause`](#pause) and yours to lift, anything else came from the platform. All timestamps (`createdAt`, `updatedAt`, `pausedAt`, `lastJobAt`, deploy `startedAt`/`endedAt`) are epoch-millisecond numbers.

***

payout-routing [#payout-routing]

Read or update stored payout rail preferences for one DVM. Requires an admin or owner in the DVM's account. With no rail flags, the command reads the preferences. With rail flags, it changes only those supplied.

```sh
dvmctl payout-routing my-dvm
dvmctl payout-routing my-dvm --base false --tempo false
dvmctl payout-routing my-dvm --base null --org my-team
```

| Flag                          | Description                                                                 |
| ----------------------------- | --------------------------------------------------------------------------- |
| `--cashu <true\|false\|null>` | `false` declines Cashu; `true` and `null` inherit the account setting       |
| `--tempo <true\|false\|null>` | `false` declines Tempo; `true` and `null` inherit the account setting       |
| `--base <true\|false\|null>`  | `false` declines Base (x402); `true` and `null` inherit the account setting |
| `--org <handle>`              | Target this org, overriding the `dvmctl switch` context                     |
| `--human`                     | Print stored preferences and next-deploy guidance instead of JSON           |

A DVM cannot enable a rail disabled by its account. Omitted flags leave stored preferences unchanged. Saving preferences does not change the running service: redeploy to apply them. Card and Lightning settings are separate.

**JSON output: read or update**

```json
{
  "accept_cashu": null,
  "accept_tempo": false,
  "accept_base": false,
  "applies_on": "next_deploy"
}
```

These are stored DVM preferences, not the account's effective rail availability. An inherited rail still needs the account's payout configuration. See [builder payments](/docs/builder-payments#per-dvm-rail-preferences) before declining a rail, including the effect on open Base channels.

| Error code             | Meaning                                                                                   |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| `bad_request`          | A rail flag is not exactly `true`, `false`, or `null`, or the platform refused the update |
| `forbidden`            | The signed-in account member lacks the required admin or owner role                       |
| `not_found`            | The DVM or org was not found in the selected context                                      |
| `platform_unreachable` | The platform could not be reached; follow the error hint before retrying                  |

***

visibility [#visibility]

Hide a DVM from discovery or list it again. Hidden DVMs remain callable by URL. Changing visibility requires an admin role in the DVM's org. The bare slug resolves within your current org context; `--org` overrides that context for this command.

```sh
dvmctl visibility my-dvm --hidden
dvmctl visibility my-dvm --listed
```

| Flag             | Description                                             |
| ---------------- | ------------------------------------------------------- |
| `--hidden`       | Hide from discovery                                     |
| `--listed`       | List in discovery                                       |
| `--org <handle>` | Target this org, overriding the `dvmctl switch` context |
| `--human`        | Prose output                                            |

Choose exactly one of `--hidden` or `--listed`. Passing neither or both returns `bad_request`.

**JSON output:**

```json
{ "slug": "my-dvm", "hidden": true }
```

`hidden` is `false` after `--listed`. Read the current value in [`info`](#info) or [`list`](#list). In `--human` output, `info` shows `Visibility: hidden` or `Visibility: listed`.

***

status [#status]

Show a deployed DVM's **live Fly-side runtime state** — which machines are running, in what region, on what image, their health-check results, and the current scale. Where [`dvmctl info`](#info) reads DVM-level metadata from the platform DB, `status` reflects what Fly is running right now. The platform fetches it via the Fly Machines API using its own credentials; no flyctl builder-side. This is the `flyctl status` replacement for builders. Like `info`, it resolves the bare slug in your current org context; `--org` overrides that context once.

```sh
dvmctl status my-dvm

# Prose summary
dvmctl status my-dvm --human
```

| Flag             | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `--org <handle>` | Read as this org, overriding the `dvmctl switch` context |
| `--human`        | Print a per-machine summary instead of JSON              |

**JSON output:**

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "status": "deployed",
  "paused": false,
  "suspensionReason": null,
  "withdrawal": null,
  "reclaimsOpen": true,
  "machines": [
    {
      "id": "148e2deef03e89",
      "state": "started",
      "region": "iad",
      "instance_id": "01J9Z...",
      "created": "2026-05-19T10:00:00Z",
      "started": "2026-05-19T10:00:05Z",
      "image": { "version": "deployment-01J9Z...", "sha": "sha256:abc123..." },
      "checks": [
        { "name": "health", "status": "passing", "output": "200 OK", "endpoint": ":8080/health" }
      ]
    }
  ],
  "scale": { "count": 1, "vm_size": { "cpus": 1, "cpu_kind": "shared", "memory_mb": 256 } }
}
```

`started` is the timestamp of the machine's most recent start; it is `null` if the machine has no start event. A DVM with no running machines returns `machines: []` and `scale.count: 0`. `status` is the DVM-lifecycle enum from the platform DB and `paused` is true when your [`dvmctl pause`](#pause) is on record — without them, a paused DVM's stopped machines look the same as a crashed one's.

`suspensionReason` is what's actually holding a suspended DVM down: `builder_pause` is your own pause and `free_tier_idle` is the idle auto-suspend — [`dvmctl resume`](#resume) lifts either. Any other reason came from the platform and `resume` refuses it. A pause and a platform suspension can be set at once — the suspension takes precedence over your pause without discarding it, so `paused: true` with a `suspensionReason` other than `builder_pause` means the DVM returns to paused once the platform lifts its suspension.

`withdrawal` is set while a destroy is winding the DVM down because callers still hold prepaid balances at it (see [`destroy`](#destroy)): `delete_after` is when the platform deletes it, `started_at` when the wind-down began, both epoch milliseconds, and `keep_db` whether the deletion keeps the database. `suspensionReason` reads `withdrawn` meanwhile. `reclaimsOpen` says whether callers can reclaim their balances right now. A suspended DVM keeps answering reclaims, so it is `false` only when the platform has closed them for a legal or fraud reason.

`free_tier_idle` is the benign one: nothing is wrong, the platform just stopped the machines of a free-tier DVM that had gone quiet, and the next request through the router wakes it. It needs no action from you — but an idle DVM can't be acted on: [`scale`](#scale), [`restart`](#restart), [`ssh`](#ssh) and [`env`](#env) refuse with `idle`, and [`deploy`](#deploy) fails with `deploy_failed` carrying the same advice. Run [`dvmctl resume`](#resume) first when you want to act on it rather than wait for traffic.

**Error anchors:**

| Code        | Trigger                                                                                                                |
| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| `not_found` | The slug doesn't exist, or the caller doesn't own it (non-owners get 404, not 403, to avoid leaking which slugs exist) |
| `gone`      | The DVM has been destroyed                                                                                             |

***

content-holds list [#content-holds-list]

Read one job's content-retention metadata and hold history through a signed service-admin request. The service requires a supported store and verifies your local builder lock key. The response contains no raw job content.

```sh
dvmctl content-holds list my-dvm job_abc123 --org my-org
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--org <handle>`        | Owning organisation                                                                          |
| `--endpoint <url>`      | Self-hosted service recorded in local builder state                                          |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--human`               | Readable output                                                                              |

JSON includes effective and baseline expiry in epoch milliseconds or null, hold IDs, verified actors, review dates, overdue status, and immutable events. Multiple holds compose. An overdue review never clears a hold. An unsupported service gives an upgrade action; typed `job_not_found` remains a missing-job error. Isolate and arbitrary custom stores do not automatically support these controls.

content-holds place [#content-holds-place]

Retain one job's content for support or a dispute. A hold cannot recover content already redacted. While any hold is active, effective expiry is null and the original baseline deadline stays visible to admins.

```sh
dvmctl content-holds place my-dvm job_abc123 --org my-org --purpose support --reason 'Investigating result' --review-due-at 2030-01-01T00:00:00Z
```

| Flag                     | Description                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------- |
| `--purpose <purpose>`    | `support` or `dispute`                                                                       |
| `--reason <reason>`      | Reason for retaining the job                                                                 |
| `--review-due-at <date>` | Future ISO date or epoch milliseconds                                                        |
| `--org <handle>`         | Owning organisation                                                                          |
| `--endpoint <url>`       | Self-hosted service recorded in local builder state                                          |
| `--mount-prefix <path>`  | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--human`                | Readable output                                                                              |

The [list response](#content-holds-list) returns the new hold and its immutable placement event. The actor is the service-verified public key, not a body field supplied by the client.

content-holds renew [#content-holds-renew]

Record the continuing reason and a later review date for an active hold. Renewal appends an event and preserves earlier decisions. It does not clear the hold.

```sh
dvmctl content-holds renew my-dvm job_abc123 hold_abc123 --org my-org --reason 'Review continues' --review-due-at 2030-02-01T00:00:00Z
```

| Flag                     | Description                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------- |
| `--reason <reason>`      | Continuing reason                                                                            |
| `--review-due-at <date>` | Future ISO date or epoch milliseconds                                                        |
| `--org <handle>`         | Owning organisation                                                                          |
| `--endpoint <url>`       | Self-hosted service recorded in local builder state                                          |
| `--mount-prefix <path>`  | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--human`                | Readable output                                                                              |

content-holds clear [#content-holds-clear]

Explicitly end a hold when its purpose ends. Clearing the last active hold restores the baseline expiry, which may already have passed. Eligible content can then be removed on the next sweep; other active holds still protect it.

```sh
dvmctl content-holds clear my-dvm job_abc123 hold_abc123 --org my-org --reason 'Review complete'
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--reason <reason>`     | Reason for ending the hold                                                                   |
| `--org <handle>`        | Owning organisation                                                                          |
| `--endpoint <url>`      | Self-hosted service recorded in local builder state                                          |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--human`               | Readable output                                                                              |

The clear decision stays in the immutable history. A review date never performs this action automatically.

destroy [#destroy]

`--org <handle>` selects the owning org for this one command.

Permanently destroy a deployed DVM and its paired Postgres cluster. To take a DVM offline temporarily — no traffic, no compute cost, but slug, secrets and data all kept — use [`dvmctl pause`](#pause) instead.

```sh
dvmctl destroy my-dvm
dvmctl destroy my-dvm --confirm
dvmctl destroy my-dvm --confirm --keep-db
```

If you want financial evidence after destruction, save and verify the minimized SQL export before either variant. Both remove compute and its database tunnel, including `--keep-db`. Carry the same owning organisation through database and destruction commands. The recipe is shipped with the service's exact SDK at `recipes/postgres/financial-export-v1.sql`; it preserves signed receipts, amounts, currencies, financial links, and recovery outcomes while excluding raw job input/output, bearer proofs, and operational credentials. A full database backup is not this minimized export.

Run `dvmctl db connect my-dvm --org my-org` for an interactive PostgreSQL client, or keep `dvmctl db proxy my-dvm --org my-org` running for an automated client. From the service project, locate the installed SDK recipe:

```sh
sdk_entry="$(node --input-type=module -e 'console.log(import.meta.resolve("@dvmkit/sdk"))')"
recipe="$(node --input-type=module -e 'import { fileURLToPath } from "node:url"; console.log(fileURLToPath(new URL("../recipes/postgres/financial-export-v1.sql", process.argv[1])))' "$sdk_entry")"
umask 077
psql "$DATABASE_URL" -X -q -t -A -v ON_ERROR_STOP=1 -f "$recipe" > financial-evidence.json
```

Configure `DATABASE_URL` privately from the proxy's `database_url`; it is a credential. Check the exit status, parse the JSON, and verify retained receipts with the service's receipt public key. Keep the file and recipe securely under your own retention policy. A failed export may leave a partial file. Only after verification, run `dvmctl destroy my-dvm --org my-org --confirm`, adding `--keep-db` when storage must remain. Later tunnel access needs a redeployed service and reattached database. Platform financial history does not replace this optional builder-owned evidence.

Without `--confirm`, prompts interactively. In non-interactive contexts (CI, agents), `--confirm` is required.

A DVM whose callers still hold prepaid balances is not deleted at once. The builder terms give those callers at least 30 days to reclaim what they are owed, or at least 7 days if the DVM is on a free trial, so the platform stops the DVM taking new jobs and deposits, keeps it answering reclaims, lets its machines sleep when idle, and deletes it no sooner than that. The org's admins get an email with the date, and [`dvmctl status`](#status) shows it under `withdrawal`. A DVM that owes nobody is deleted straight away.

| Flag                    | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| `--confirm`             | Skip confirmation prompt                                          |
| `--keep-db`             | Preserve the Postgres cluster (allows re-attachment on redeploy)  |
| `--mount-prefix <path>` | DVM mount path for its admin liability lookup (no trailing slash) |
| `--human`               | Prose output                                                      |

**JSON output:**

```json
{
  "status": "destroyed",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "keptDb": false
}
```

***

metrics [#metrics]

Show request metrics for a deployed DVM over a trailing time window. The bare slug is resolved in your current org context; `--org` overrides that context once.

```sh
dvmctl metrics my-dvm
dvmctl metrics my-dvm --hours 48
```

| Flag              | Description                                              |
| ----------------- | -------------------------------------------------------- |
| `--hours <hours>` | Look-back window in hours (default: 24)                  |
| `--org <handle>`  | Read as this org, overriding the `dvmctl switch` context |
| `--human`         | Prose output (aggregated totals + error breakdown)       |

**JSON output:**

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "hours": 24,
  "metrics": [
    {
      "dvmId": "550e8400-e29b-41d4-a716-446655440000",
      "hour": 1746489600000,
      "status2xx": 40,
      "status4xx": 1,
      "status5xx": 1,
      "totalRequests": 42,
      "totalLatencyMs": 84000,
      "egressBytes": 1048576
    }
  ]
}
```

One bucket per hour in the window; `hour` is the epoch-millisecond bucket start.

***

events [#events]

Show a chronological "what happened to my DVM recently" feed — deploys, restarts, pauses and resumes, scale changes, env-var changes, and Fly machine state transitions (start/stop/exit/OOM kills) — over a trailing window (default 7 days). Platform-mediated; you do not need `flyctl` or Fly access. The bare slug is resolved in your current org context; `--org` overrides that context once.

```sh
dvmctl events my-dvm
dvmctl events my-dvm --since 24h
dvmctl events my-dvm --since 1h --human
```

| Flag                 | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `--since <duration>` | Look-back window — `30s`, `5m`, `2h`, `7d` (default: `7d`) |
| `--org <handle>`     | Read as this org, overriding the `dvmctl switch` context   |
| `--human`            | Prose output (chronological list)                          |

Events are merged from the deploy history, the config-change audit log, and the Fly Machines API, then sorted newest-first. Each entry carries a `type`, a `timestamp` (epoch ms), an `actor` (builder handle/email, commit author for deploys, or `"fly"` for machine events), a `source` (`deploy` | `audit` | `machine`), and source-specific `details`.

Machine events are best-effort: if the Fly Machines API is unavailable (or the DVM was never deployed / has been torn down), the feed still returns deploy and audit events, with a note in `warnings`.

**JSON output:**

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "since": "7d",
  "events": [
    {
      "type": "deploy",
      "timestamp": 1715000000000,
      "actor": "alice",
      "source": "deploy",
      "details": {
        "id": "3dcc9623-8db4-4c03-9929-a0cd5841c1d2",
        "status": "deployed",
        "trigger": "cli",
        "durationMs": 64000,
        "commitSha": "a1b2c3d",
        "commitRef": "main",
        "commitMessage": "Tighten retry backoff",
        "error": null
      }
    },
    {
      "type": "scale",
      "timestamp": 1714990000000,
      "actor": "alice",
      "source": "audit",
      "details": { "before": { "maxMachines": 1 }, "after": { "maxMachines": 2 } }
    },
    {
      "type": "machine.start",
      "timestamp": 1714980000000,
      "actor": "fly",
      "source": "machine",
      "details": { "machineId": "148e2deef03e89", "status": "started", "flySource": "flyd" }
    }
  ]
}
```

**Error anchors:**

| Code          | Trigger                                       |
| ------------- | --------------------------------------------- |
| `bad_request` | `--since` is not a valid duration (e.g. `5x`) |
| `not_found`   | Unknown or unowned slug                       |

***

env [#env]

`--org <handle>` selects the owning org for this one command.

View or update environment variables for a deployed DVM.

Each `--set` or `--unset` restarts the DVM's running machines. A `--set` value travels in the command's arguments, so it can land in shell history and the process list. [Change a secret after deploy](/docs/deploying#change-a-secret-after-deploy) covers when to redeploy with `--env-stdin` instead.

```sh
# List variable names (values are not shown)
dvmctl env my-dvm

# Set one or more variables
dvmctl env my-dvm --set API_KEY=abc123 --set MODEL=gpt-4o

# Unset variables
dvmctl env my-dvm --unset OLD_KEY
```

| Flag                | Description                                |
| ------------------- | ------------------------------------------ |
| `--set <KEY=value>` | Set an environment variable (repeatable)   |
| `--unset <KEY>`     | Unset an environment variable (repeatable) |
| `--human`           | Prose output                               |

**JSON output — list:**

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "env": ["API_KEY", "MODEL"]
}
```

**JSON output — after set/unset:**

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "updated": ["API_KEY", "MODEL"],
  "removed": ["OLD_KEY"]
}
```

**Error anchors:**

| Code          | Trigger                             |
| ------------- | ----------------------------------- |
| `bad_request` | `--set` value missing `=` separator |

***

logs [#logs]

`--org <handle>` selects the owning org for this one command.

View or stream logs for a deployed DVM. Default is a snapshot of recent lines; pass `--tail` to follow live.

```sh
# Snapshot mode (default): show recent lines and exit
dvmctl logs my-dvm
dvmctl logs my-dvm --lines 50

# Look-back window
dvmctl logs my-dvm --since 30m

# Stream live until interrupted (Ctrl-C)
dvmctl logs my-dvm --tail
```

| Flag                 | Description                                                   |
| -------------------- | ------------------------------------------------------------- |
| `--tail`             | Stream live logs until interrupted (Ctrl-C)                   |
| `--since <duration>` | Only show logs newer than this (e.g. `30s`, `5m`, `2h`, `1d`) |
| `--lines <count>`    | Max recent lines to show in non-tail mode (default: 100)      |

No JSON envelope — `logs` writes raw log lines to stdout (one per line) in both snapshot and `--tail` mode, so the output pipes cleanly into `grep`, `jq -R`, or a file. There is no `--human` flag.

***

ssh [#ssh]

`--org <handle>` selects the owning org for this one command.

SSH into a running Fly machine of a deployed DVM, for debugging without flyctl. The platform validates ownership and brokers the connection on your behalf.

With no `--command`, `dvmctl ssh <slug>` opens an **interactive shell** on a running machine, relayed over a websocket. Type `exit` or press Ctrl-D to disconnect; `dvmctl` exits with the remote shell's exit code. Requires an interactive terminal.

> **Note:** the remote PTY is currently fixed at 80×24 and does not track your terminal size or live resizes (`SIGWINCH`), so full-screen TUIs (`vim`, `less`, `htop`) may render to the wrong dimensions. For plain shell use this isn't noticeable.

With `--command`, it runs a **one-shot command** and returns the output plus the remote exit code as JSON (the `dvmctl` process exits with that code). The command runs through `/bin/sh -c`, so shell features (pipes, redirects, env-var expansion) work. Fly caps each one-shot command at 60 seconds.

For DVMs owned by an org, this requires the `admin` role — a shell (or arbitrary command) can read secret values (e.g. `env`), so ssh matches the admin gating on [`dvmctl env`](#env).

```sh
# Open an interactive shell on a running machine
dvmctl ssh my-dvm

# Open a shell on a specific machine of a multi-machine DVM
dvmctl ssh my-dvm --machine 148e2deef03e89

# Run a one-shot command instead
dvmctl ssh my-dvm --command "cat /tmp/state"
dvmctl ssh my-dvm --machine 148e2deef03e89 --command "top -bn1 | head"
```

| Flag              | Description                                                              |
| ----------------- | ------------------------------------------------------------------------ |
| `--command <cmd>` | Run a one-shot command instead of opening an interactive shell           |
| `--machine <id>`  | Target a specific machine (default: first running machine)               |
| `--human`         | Print stdout/stderr directly instead of JSON (one-shot `--command` only) |

**JSON output (one-shot `--command`):**

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "stdout": "running\n",
  "stderr": "",
  "exit_code": 0,
  "machine_id": "148e2deef03e89"
}
```

**Error anchors:**

| Code                  | Trigger                                                                    |
| --------------------- | -------------------------------------------------------------------------- |
| `not_a_tty`           | Interactive shell requested without an attached terminal (use `--command`) |
| `forbidden`           | Caller lacks the `admin` role on the owning org                            |
| `no_running_machine`  | The DVM has no machine in the `started` state                              |
| `machine_not_found`   | `--machine <id>` does not match any machine on this DVM                    |
| `machine_not_running` | `--machine <id>` exists but is not in the `started` state                  |

***

restart [#restart]

`--org <handle>` selects the owning org for this one command.

Restart a deployed DVM's Fly machines without a redeploy — handy after a [`dvmctl env`](#env) change or to clear bad state. The platform validates ownership and restarts each machine via Fly using its own credentials; no flyctl builder-side. Restarts all running machines by default, or a single machine with `--machine <id>`. Returns each restarted machine's post-restart state.

For DVMs owned by an org, this requires the `admin` role, matching the other mutating surfaces ([`dvmctl env`](#env), `deploy`, `destroy`).

```sh
# Restart all of the DVM's running machines
dvmctl restart my-dvm

# Restart a single machine on a multi-machine DVM
dvmctl restart my-dvm --machine 148e2deef03e89
```

| Flag             | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `--machine <id>` | Restart a single machine (default: all running machines) |
| `--human`        | Print a machine/state summary instead of JSON            |

**JSON output:**

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "machines": [{ "id": "148e2deef03e89", "state": "started" }],
  "restarted": 1
}
```

**Error anchors:**

| Code                  | Trigger                                                   |
| --------------------- | --------------------------------------------------------- |
| `forbidden`           | Caller lacks the `admin` role on the owning org           |
| `no_running_machine`  | The DVM has no machine in the `started` state             |
| `machine_not_found`   | `--machine <id>` does not match any machine on this DVM   |
| `machine_not_running` | `--machine <id>` exists but is not in the `started` state |

***

pause [#pause]

`--org <handle>` selects the owning org for this one command.

Take a DVM offline without destroying it. The router stops routing to it (callers get a `503` with code `paused`), it drops out of `/explore`, and its Fly machines are stopped so it stops accruing [compute](/docs/resources#what-always-on-costs). Its slug, secrets, volumes and paired Postgres are all left alone — this is the "I'm reworking this, park it for a few weeks" move, and the one thing [`dvmctl scale`](#scale) can't do (it floors at one machine) and [`dvmctl destroy`](#destroy) does far too much of.

[`dvmctl resume`](#resume) brings it back on the same image, with no redeploy.

For DVMs owned by an org, this requires the `admin` role.

```sh
dvmctl pause my-dvm

# Prose summary
dvmctl pause my-dvm --human
```

| Flag      | Description                                   |
| --------- | --------------------------------------------- |
| `--human` | Print a machine/state summary instead of JSON |

**JSON output:**

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "status": "suspended",
  "paused": true,
  "machines": [{ "id": "148e2deef03e89", "state": "stopping" }],
  "stopped": 1
}
```

A paused DVM *is* a suspended one — the difference is who suspended it, which is what `paused` tells you. `status` and `paused` mean the same thing here as in [`dvmctl status`](#status).

Fly acknowledges a stop and transitions the machine asynchronously, so `machines[].state` is usually `stopping` rather than `stopped` at the moment the call returns. Pausing is idempotent: re-running it on an already-paused DVM re-issues the stop, which is what makes a pause whose Fly call failed safe to retry.

The router is the only way into a cloud DVM, since its Fly app has no public address, so a paused DVM stays dark to callers until you resume it.

You can't deploy to a paused DVM — resume it first.

**Error anchors:**

| Code                    | Trigger                                                                                                                                 |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `forbidden`             | Caller lacks the `admin` role on the owning org                                                                                         |
| `invalid_state`         | The DVM isn't deployed (e.g. still deploying, or a failed first deploy)                                                                 |
| `suspended_by_platform` | The DVM is already suspended by the platform (operator, enforcement, or reputation) — it's offline already, so there's nothing to pause |
| `machine_stop_failed`   | Fly refused to stop a machine. The DVM is already refusing traffic; re-run `pause` to retry                                             |

***

resume [#resume]

`--org <handle>` selects the owning org for this one command.

Bring an offline DVM back: its Fly machines start again on the same image, with the same volumes and the same database. No redeploy, no new image build.

`resume` lifts the two suspensions that are yours to lift — a pause **you** made (`builder_pause`), and the idle auto-suspend the platform applies to a quiet free-tier DVM (`free_tier_idle`). The idle one also clears on the next request through the router, but resuming is how you get an idle DVM back without sending it traffic: `deploy`, `scale`, `restart`, `exec` and `ssh` all refuse while it's idle.

A successful `resume`, deployment or `restart` resets the plan's full idle period. Requests through the router also reset it. The platform can idle-suspend the DVM again once that period passes without either kind of activity. “Last job” still reports request history; builder actions do not change it.

A DVM the platform suspended for any other reason — operator action, plan enforcement, or a reputation sweep — stays suspended and returns `suspended_by_platform`; lifting it is the platform's call, not yours.

The platform can also suspend a DVM you'd already paused, and its suspension takes precedence — but it doesn't discard your pause. When the platform lifts the suspension, the DVM goes back to *paused*, not back online: it stays offline (and off the compute meter) until you resume it yourself. `dvmctl status` reports `paused: true` throughout.

For DVMs owned by an org, this requires the `admin` role.

```sh
dvmctl resume my-dvm
```

| Flag      | Description                                   |
| --------- | --------------------------------------------- |
| `--human` | Print a machine/state summary instead of JSON |

**JSON output:**

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "status": "deployed",
  "paused": false,
  "machines": [{ "id": "148e2deef03e89", "state": "started" }],
  "started": 1
}
```

The machines are started before the DVM is un-suspended, so traffic only returns once there's something to serve it. If a machine fails to start, the DVM stays offline and the call is a clean re-run.

**Error anchors:**

| Code                    | Trigger                                                                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `forbidden`             | Caller lacks the `admin` role on the owning org                                                                                            |
| `not_paused`            | The DVM isn't suspended (nothing to resume)                                                                                                |
| `suspended_by_platform` | The DVM was suspended by the platform, not paused by you and not idle — only the platform can lift it                                      |
| `withdrawn`             | A [`destroy`](#destroy) is winding the DVM down while callers reclaim their balances; it is deleted on the date shown and can't be resumed |
| `machine_start_failed`  | Fly refused to start a machine. The DVM stays offline; re-run `resume` to retry                                                            |

***

rollback [#rollback]

`--org <handle>` selects the owning org for this one command.

Revert a deployed DVM to a previous successful deploy's image. Defaults to the prior deploy; target a specific one with `--to <deploy-id>` (find IDs via [`dvmctl events`](#events) or [`dvmctl deploy-status`](#deploy-status)).

```sh
# Roll back to the previous successful deploy
dvmctl rollback my-dvm

# Roll back to a specific deploy
dvmctl rollback my-dvm --to 3dcc9623-8db4-4c03-9929-a0cd5841c1d2
```

| Flag               | Description                                                    |
| ------------------ | -------------------------------------------------------------- |
| `--to <deploy-id>` | Roll back to a specific `deploy_id` (default: previous deploy) |
| `--human`          | Prose output                                                   |

Progress events (`queued`, `log`, `phase`) stream to stderr; the final result object goes to stdout.

**JSON output:**

```json
{
  "status": "deployed",
  "url": "https://alice--my-dvm.dvmkit.ai",
  "dvmkitUrl": "https://alice--my-dvm.dvmkit.ai",
  "slug": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "deployId": "9f1c4e07-2b55-4a3e-9f0d-71a2c8b4d611",
  "rolledBackTo": "3dcc9623-8db4-4c03-9929-a0cd5841c1d2"
}
```

***

scale [#scale]

`--org <handle>` selects the owning org for this one command.

Change a deployed DVM's machine count and/or VM size without redeploying. The platform validates ownership and the requested config against your plan caps, then resizes the live machines in place (`fly scale count` / `fly scale vm`). At least one of `--count` or `--size` is required.

For DVMs owned by an org, this requires the `admin` role — scaling changes spend, matching the gating on [`dvmctl env`](#env) and [`dvmctl ssh`](#ssh).

```sh
# Run two machines
dvmctl scale my-dvm --count 2

# Resize the VM
dvmctl scale my-dvm --size shared-cpu-2x

# Both at once, human-readable
dvmctl scale my-dvm --count 2 --size performance-1x --human
```

| Flag               | Description                                                   |
| ------------------ | ------------------------------------------------------------- |
| `--count <n>`      | Number of machines to run (1–100, subject to your plan's cap) |
| `--size <vm-size>` | Fly VM size (see below)                                       |
| `--human`          | Print a before → after summary instead of JSON                |

**Valid sizes:** `shared-cpu-1x`, `shared-cpu-2x`, `shared-cpu-4x`, `shared-cpu-8x`, `performance-1x`, `performance-2x`, `performance-4x`, `performance-8x`. Each maps to a fixed CPU count, CPU kind, and memory.

**JSON output** — the resolved machine config before and after the change:

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "before": { "memoryMb": 256, "cpuCount": 1, "cpuKind": "shared", "minMachinesRunning": 0, "maxMachines": 1 },
  "after":  { "memoryMb": 512, "cpuCount": 2, "cpuKind": "shared", "minMachinesRunning": 0, "maxMachines": 2 }
}
```

**Error anchors:**

| Code                  | Trigger                                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `bad_request`         | Neither `--count` nor `--size` given, count out of range, unknown size, or count below the DVM's `min_machines_running`                    |
| `forbidden`           | Caller lacks the `admin` role on the owning org                                                                                            |
| `idle`                | The DVM is idle-suspended (`free_tier_idle`) — the platform stopped its machines after a quiet spell. Run [`dvmctl resume`](#resume) first |
| `paused`              | The DVM is [paused](#pause) — scaling it would start machines it can't serve traffic from. Resume it first                                 |
| `plan_limit_exceeded` | Requested count/size exceeds your plan's caps. The error `data` carries `upgradeUrl`, `cap`, and `planName`                                |

A `plan_limit_exceeded` error returns HTTP `402` and includes an upgrade link:

```json
{
  "error": {
    "code": "plan_limit_exceeded",
    "message": "Your Free plan allows up to 1 machine per DVM. You requested 2. Upgrade at https://dvmkit.com/dashboard/billing to run more machines.",
    "data": { "limit": "max_machines", "requested": 2, "cap": 1, "planName": "Free", "upgradeUrl": "https://dvmkit.com/dashboard/billing" }
  }
}
```

***

switch [#switch]

Set or inspect the active org context. When an org is active, every `dvmctl` command runs against it: reads ([`list`](#list), [`feedback list`](#feedback-list), [`revenue summary`](#revenue-summary), [`trace get`](#trace-get)) answer for that org, and [`deploy`](#deploy) creates new DVMs under its account. Pass `--org <handle>` to any of those — reads and `deploy` alike — to override the context for one invocation.

```sh
# Show current context
dvmctl switch

# Switch to an org
dvmctl switch my-org

# Return to personal context
dvmctl switch --personal
```

Verifies org membership before saving. The active handle is stored in `~/.dvmctl/config.json`.

| Flag         | Description                                 |
| ------------ | ------------------------------------------- |
| `--personal` | Clear org context (run as personal builder) |
| `--human`    | Prose output                                |

**JSON output — show current:**

```json
{ "activeOrg": "my-org" }
```

**JSON output — after switch:**

```json
{ "activeOrg": "my-org", "role": "owner" }
```

`role` is your actual membership role in the target org — one of `owner`, `admin`, or `member`.

**JSON output — after `--personal`:**

```json
{ "activeOrg": null }
```

**Error anchors:**

| Code            | Trigger                                 |
| --------------- | --------------------------------------- |
| `auth_required` | Not authenticated                       |
| `bad_arguments` | Both `<handle>` and `--personal` passed |

***

orgs [#orgs]

List every org membership. Use a shared-org `handle` with [`switch`](#switch) or a one-shot `--org` override. Your personal context is listed without a handle because it is already the default and cannot be selected with `switch`.

```sh
dvmctl orgs
dvmctl orgs --human
```

| Flag      | Description              |
| --------- | ------------------------ |
| `--human` | Print a membership table |

**JSON output:**

```json
{
  "activeOrg": "my-org",
  "memberships": [
    {
      "handle": "my-org",
      "displayName": "My Org",
      "role": "owner",
      "personal": false,
      "active": true
    },
    {
      "displayName": "Alice",
      "role": "owner",
      "personal": true,
      "active": false
    }
  ],
  "display": "1 shared org membership. Active context: my-org.",
  "hint": "Run `dvmctl switch <handle>` to choose a shared org, or `dvmctl switch --personal` for your personal context."
}
```

When you have no shared-org memberships, `memberships` still includes your personal context. `display` says that you have no shared memberships, and `hint` tells you to create or join one in the dashboard.

***

whoami [#whoami]

Show the local builder identity, authenticated builder profile, every org membership, and the active context. Every listed membership can deploy a new DVM. A personal context has no switchable handle.

```sh
dvmctl whoami
dvmctl whoami --human
```

| Flag      | Description                                       |
| --------- | ------------------------------------------------- |
| `--human` | Print the identity, profile, and membership table |

**JSON output:**

```json
{
  "identity_pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "identity_status": "available",
  "builder": {
    "id": "bld_123",
    "email": "builder@example.com",
    "handle": "builder",
    "authId": "auth_123",
    "displayName": "Builder",
    "bio": null,
    "avatarUrl": null,
    "website": null,
    "links": {},
    "isOperator": false,
    "createdAt": 1744000000000,
    "updatedAt": 1745000000000
  },
  "activeOrg": "my-org",
  "memberships": [
    {
      "handle": "my-org",
      "displayName": "My Org",
      "role": "owner",
      "personal": false,
      "deployable": true,
      "active": true
    },
    {
      "displayName": "Builder",
      "role": "owner",
      "personal": true,
      "deployable": true,
      "active": false
    }
  ],
  "display": "Builder builder@example.com. Active context: my-org.",
  "hint": "Every listed membership can deploy a new DVM. The role shows its existing access level."
}
```

`identity_status` is `missing` when no local identity has been created, or `unreadable` when the local builder config cannot be read. In both cases, the platform profile and memberships remain available.

***

handle set [#handle-set]

Claim a builder handle (2–20 characters, lowercase alphanumeric with hyphens, no leading/trailing `--`).

**Your handle is what gives your DVMs a public URL.** The router resolves callers at `https://<handle>--<slug>.dvmkit.ai`, so until you claim one, a cloud deploy fails with `handle_required`, and a connect-tier DVM you own reports `dvmkitUrl: null` from [`deploy`](#deploy), [`list`](#list) and [`info`](#info). Claim the handle once and every DVM the owning account holds, present and future, gets its public URL. DVMs owned by a shared org take the *org's* handle, not yours.

```sh
dvmctl handle set alice
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

**JSON output:**

```json
{ "status": "ok", "handle": "alice" }
```

***

handle check [#handle-check]

Check whether a handle is available without claiming it. Unauthenticated — no API key needed.

```sh
dvmctl handle check alice
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

**JSON output:**

```json
{ "handle": "alice", "available": true }
```

***

domains add [#domains-add]

`--org <handle>` selects the owning org for this one command.

Add a custom domain to a deployed DVM. After adding, point your DNS to the dvmkit router and verify with `domains verify`.

```sh
dvmctl domains add my-dvm api.example.com
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

**JSON output:**

```json
{ "status": "added", "dvmId": "550e8400-e29b-41d4-a716-446655440000", "slug": "my-dvm", "domain": "api.example.com" }
```

***

domains remove [#domains-remove]

`--org <handle>` selects the owning org for this one command.

Remove a custom domain from a deployed DVM.

```sh
dvmctl domains remove my-dvm api.example.com
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

**JSON output:**

```json
{ "status": "removed", "dvmId": "550e8400-e29b-41d4-a716-446655440000", "slug": "my-dvm", "domain": "api.example.com" }
```

***

domains verify [#domains-verify]

`--org <handle>` selects the owning org for this one command.

Verify that DNS is correctly configured for a custom domain.

```sh
dvmctl domains verify my-dvm api.example.com
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

**JSON output:**

```json
{ "status": "verified", "dvmId": "550e8400-e29b-41d4-a716-446655440000", "slug": "my-dvm", "domain": "api.example.com" }
```

***

domains list [#domains-list]

`--org <handle>` selects the owning org for this one command.

List all custom domains configured for a DVM.

```sh
dvmctl domains list my-dvm
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

**JSON output:**

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "domains": [
    {
      "id": "7c2ab918-3ef4-4a21-8d6c-0b5e1f9a2d84",
      "orgId": "acffd753-105a-4958-9f37-243ac032f332",
      "dvmId": "550e8400-e29b-41d4-a716-446655440000",
      "domain": "api.example.com",
      "status": "verified",
      "verificationAttemptedAt": 1746489600000,
      "createdAt": 1746489600000,
      "updatedAt": 1746489600000
    }
  ]
}
```

`status` is `pending`, `verified`, `failed` or `revoked` — a domain is only served once it reads `verified`. `dvmId` is the DVM currently serving the domain (`null` once it's been de-routed; the domain itself survives, owned by `orgId`).

***

identity create [#identity-create]

Generate a secp256k1 builder identity keypair for your account. Persists the pubkey to `~/.dvmkit/builder.json` and the secret to `~/.dvmkit/builder.key` (mode `0600`). This key signs deploy attestations and populates `builder.pubkey` on each DVM's `/v1/info` — distinct from the Cashu lock keypair managed by [`dvmctl lock create`](#lock-create).

These paths sit under `DVMKIT_CONFIG_DIR` when it is set; `~/.dvmkit` is the default. See [State directories](#state-directories).

```sh
dvmctl identity create
dvmctl identity create --force
```

| Flag      | Description                                                                                                                                          |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--force` | Overwrite the local identity. This does not change the account’s bound pubkey; deploys with a replacement key are rejected once the account is bound |
| `--human` | Prose output                                                                                                                                         |

**JSON output:**

```json
{
  "status": "created",
  "identity_pubkey": "f2f1d2c3b3382d924d13f55d0a70d0d555239c39a36464980c0b37804ddd1846",
  "secret_path": "~/.dvmkit/builder.key",
  "pubkey_path": "~/.dvmkit/builder.json",
  "mode": "0600"
}
```

`identity_pubkey` is the x-only BIP-340 pubkey — 64 hex chars, no `02`/`03` prefix (unlike the compressed Cashu lock pubkeys that [`rotate`](#rotate) prints).

On Windows, `mode` is replaced by a `windows_note` string (POSIX file modes don't apply).

Deploying from a second machine [#deploying-from-a-second-machine]

The platform binds one signing identity per account when you first deploy. Every machine deploying for that account needs the same key. Authenticated `GET /api/v1/builder/me` returns `builder.identity_pubkey`: the bound 64-character x-only hex pubkey, or `null` before binding.

Transfer `builder.key` from a machine that already deploys for the account through a secure channel, then restore it with [`dvmctl identity import`](#identity-import). Run `dvmctl identity show` on the destination and compare the pubkey with the account's binding before deploying.

A `403 builder_identity_mismatch` includes the full bound pubkey in `error.bound_identity_pubkey` and its prefix in the message. Restore the original key if they differ. Generating another key with `identity create --force` does not change the platform binding. There is no identity re-bind or rotation route.

***

identity import [#identity-import]

Install your account's existing signing identity on this machine. Read the 32-byte secret key as 64 hex characters from stdin or `--from-file`. The command derives the pubkey and writes `builder.key` and `builder.json` under `DVMKIT_CONFIG_DIR` (default: `~/.dvmkit`). Keep the secret out of command arguments.

```sh
dvmctl identity import < builder.key
dvmctl identity import --from-file ./builder.key
dvmctl identity import --from-file ./builder.key --force
```

| Flag                 | Description                                                                                              |
| -------------------- | -------------------------------------------------------------------------------------------------------- |
| `--from-file <path>` | Read the secret from a file instead of stdin                                                             |
| `--force`            | Replace a different existing identity, backing up the old key first. Redeploy DVMs that used the old key |
| `--human`            | Prose output                                                                                             |

**JSON output:**

```json
{
  "status": "imported",
  "configDir": "~/.dvmkit",
  "configDirEnv": "DVMKIT_CONFIG_DIR",
  "identity_pubkey": "f2f1d2c3b3382d924d13f55d0a70d0d555239c39a36464980c0b37804ddd1846",
  "secret_path": "~/.dvmkit/builder.key",
  "pubkey_path": "~/.dvmkit/builder.json",
  "mode": "0600"
}
```

Paths in the output are absolute; `~` is shorthand in this example. `status` is `unchanged` when the same key and pubkey are already installed. A replaced secret's backup path appears as `backup_file`. Importing a different identity requires `--force`; otherwise the command returns `identity_exists`.

On Windows, `mode` is replaced by a `windows_note` string.

***

identity show [#identity-show]

Print the builder identity pubkey from `~/.dvmkit/builder.json`.

```sh
dvmctl identity show
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

**JSON output:**

```json
{
  "identity_pubkey": "f2f1d2c3b3382d924d13f55d0a70d0d555239c39a36464980c0b37804ddd1846",
  "pubkey_path": "~/.dvmkit/builder.json"
}
```

Errors with `identity_missing` when no identity has been created yet.

***

lock create [#lock-create]

Generate a BIP-39 mnemonic for builder Cashu P2PK lock keypairs, saved to `~/.dvmkit/builder.mnemonic`. The mnemonic is the derivation root for per-DVM lock keypairs — `dvmctl deploy` derives and registers the per-DVM lock pubkey automatically, and `dvmctl rotate` / `dvmctl melt-pending` derive against it.

Every `~/.dvmkit` path in this section sits under `DVMKIT_CONFIG_DIR` when it is set. See [State directories](#state-directories).

A bare `dvmctl lock create` reports `already_exists` and leaves an existing mnemonic alone. Replacing one takes `--import` (restore known words) or `--force` (generate fresh ones), and either way the replaced mnemonic is copied to a timestamped `.bak` sibling at mode 0600 before the write. That backup is the only local trace of the old words: proofs locked to lock pubkeys derived from them are not spendable with the new mnemonic, so every DVM needs a `dvmctl deploy` afterwards to advertise a pubkey you can still derive.

```sh
dvmctl lock create
dvmctl lock create --import "word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12"
dvmctl lock create --force
```

| Flag                  | Description                                                                                                                          |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `--import <mnemonic>` | Import an existing 12-word BIP-39 mnemonic instead of generating a new one. Replaces an existing mnemonic — this is the restore path |
| `--force`             | Replace an existing mnemonic with a freshly generated one                                                                            |
| `--human`             | Prose output                                                                                                                         |

**JSON output — generated or imported:**

```json
{
  "status": "generated",
  "mnemonicFile": "~/.dvmkit/builder.mnemonic"
}
```

`status` is `"generated"` for new mnemonics, `"imported"` when `--import` is used.

**JSON output — an existing mnemonic was replaced:**

```json
{
  "status": "imported",
  "mnemonicFile": "~/.dvmkit/builder.mnemonic",
  "backupFile": "~/.dvmkit/builder.mnemonic.2026-08-01T09-14-22-113Z.bak",
  "hint": "The mnemonic this replaced was copied to ~/.dvmkit/builder.mnemonic.2026-08-01T09-14-22-113Z.bak (mode 0600). ..."
}
```

`backupFile` is present only when words were actually replaced — absent on a first write, and absent when `--import` re-imports the mnemonic already on disk.

**JSON output — mnemonic already exists:**

```json
{
  "status": "already_exists",
  "mnemonicFile": "~/.dvmkit/builder.mnemonic",
  "hint": "A builder mnemonic already exists, so nothing was written. Re-run with --force to generate fresh words, or --import <words> to restore a known mnemonic; either way the current mnemonic is copied to a timestamped .bak sibling (mode 0600) first. …"
}
```

The `hint` is the agent's only signal that a next step exists, so it names both flags and the consequence of taking either.

**Error anchors:**

| Code               | Trigger                                                                                                                                                                                                                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_mnemonic` | Provided `--import` value is not a valid 12-word BIP-39 phrase                                                                                                                                                                                                                                                                  |
| `mnemonic_exists`  | A mnemonic exists — at `~/.dvmkit/builder.mnemonic`, the former `~/.dvmkit/recovery.mnemonic`, or the pre-state-split `~/.dvm/recovery.mnemonic` — and the write did not opt in to replacing it. `lock create` never surfaces this — it reports `already_exists` first — but any other caller of the underlying library hits it |

***

init [#init]

Bootstrap a self-hosted DVM: generate a `canonical_dvm_id` (UUIDv4) and persist it to `~/.dvmkit/builder.json`. Platform-hosted DVMs get their `canonical_dvm_id` at deploy time and don't need this command.

```sh
dvmctl init my-dvm --self-hosted
```

| Flag            | Description                            |
| --------------- | -------------------------------------- |
| `--self-hosted` | Mark the DVM as self-hosted (required) |
| `--human`       | Prose output                           |

**JSON output:**

```json
{
  "status": "initialized",
  "handle": "my-dvm",
  "canonical_dvm_id": "550e8400-e29b-41d4-a716-446655440000",
  "current_rotation_index": 0,
  "self_hosted": true
}
```

**Error anchors:**

| Code                        | Trigger                                                                    |
| --------------------------- | -------------------------------------------------------------------------- |
| `init_requires_self_hosted` | `--self-hosted` flag not passed                                            |
| `invalid_handle`            | Handle doesn't match slug pattern (3-40 lowercase alphanumeric or hyphens) |
| `already_initialized`       | Handle already has a `canonical_dvm_id` in `builder.json`                  |

***

rotate [#rotate]

Rotate the per-DVM Cashu lock pubkey. Derives the next BIP-32 child from the builder mnemonic, publishes it to the DVM's admin endpoint (signed with the current privkey), and demotes the prior pubkey to retired. For cloud-hosted DVMs, it then updates the platform's lock pubkey. Starting with 0.3.5-rc.1, a failed platform update leaves a local pending marker and exits with an error. Finish that update before deploying or rotating again.

```sh
dvmctl rotate my-dvm
dvmctl rotate my-dvm --endpoint https://my-dvm.example.com
dvmctl rotate my-dvm --sync-platform
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--endpoint <url>`      | DVM admin endpoint URL (skips platform lookup; required for self-hosted DVMs)                |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--sync-platform`       | Finish a recorded pending platform update without another rotation (0.3.5-rc.1 or later)     |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Prose output                                                                                 |

**JSON output — rotated:**

```json
{
  "status": "rotated",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "canonical_dvm_id": "550e8400-e29b-41d4-a716-446655440000",
  "previous_rotation_index": 0,
  "current_rotation_index": 1,
  "current_pubkey": "021104d14e5c045c0e9d25e50e2efa1acd7978284e2b2d559ba0eb476050ec91f3",
  "retired": [
    {
      "pubkey": "036d85c25e8a23f918712b2ecced8d3ed2d9e0d937283f66c45ddc4b6dc4352054",
      "retired_at_ms": 1700000000000
    }
  ]
}
```

Lock pubkeys are compressed secp256k1 — 66 hex chars starting `02` or `03` — not the x-only form [`identity show`](#identity-show) prints.

`status` is `"resynced"` when the server reports that the DVM is already at the next rotation index. This depends on the server accepting the request: a stale signing key can instead receive `admin_bad_signature`. Do not assume repeating a rotation will recover every lost response.

`--sync-platform` returns `status: "platform_resynced"`, the handle, `dvmId`, `canonical_dvm_id`, `current_rotation_index`, and `current_pubkey`. It does not advance the rotation index. A pending update blocks ordinary rotation with `platform_lock_sync_pending`; restore platform authentication and follow the sync-only hint. Version 0.3.4-rc.1 lacks this flag and can return `platform_sync_warning` in its rotation output.

**Error anchors:**

| Code                            | Trigger                                                           |
| ------------------------------- | ----------------------------------------------------------------- |
| `no_builder_mnemonic`           | No mnemonic found — run `dvmctl lock create` first                |
| `dvm_not_initialized`           | No `builder.json` entry for this handle                           |
| `platform_lock_sync_failed`     | Rotation is saved locally, but the platform update is unconfirmed |
| `platform_lock_sync_pending`    | A prior platform update must finish before another rotation       |
| `no_pending_platform_lock_sync` | `--sync-platform` has no recorded cloud update to finish          |
| `endpoint_required`             | Self-hosted DVM without `--endpoint`                              |
| `auth_required`                 | Not authenticated (needed to resolve endpoint via platform)       |
| `admin_bad_signature`           | DVM's lock pubkey doesn't match the derived privkey               |
| `dvm_url_unset`                 | DVM has no platform URL yet (still deploying)                     |

***

melt-pending [#melt-pending]

Drain a DVM's pending Cashu accumulator batches. Derives the per-DVM lock privkey locally, signs NUT-11 witnesses, melts proofs at the mint via LNURL-pay to the payout Lightning address, and posts `mark-melted` back to the DVM admin endpoint. With `--watch`, runs as a long-lived daemon suitable for systemd.

Run it on a machine that holds `builder.mnemonic` and this DVM's `builder.json` entry, both under `DVMKIT_CONFIG_DIR` ([State directories](#state-directories)). dvmkit Cloud does not run it for you. [Running the payout worker](/docs/builder-payments#running-the-payout-worker) compares the places to run it.

Each tick services outstanding **credit drains** before it melts anything: a caller reclaiming an expired prepaid balance gets accumulator proofs swapped into notes P2PK-locked to their refund key and parked on the DVM for pickup, and your payout melt is held back while any cashu drain liability is still outstanding — refunds never get swept to your Lightning address first. Ecash is the only refund this job settles: a Lightning-funded credit reclaims as ecash too, since direct Lightning payout is not a reclaim method.

Sometimes no accumulator batch covers a refund at all. A Lightning-funded credit has no proofs behind it, and a Cashu-funded one loses its proofs the moment you legitimately melt them. `--refund-nwc` lets the tick **buy** the refund instead: it asks one of your accepted mints for a quote, pays that quote's invoice from the wallet you named, mints the notes locked to the caller, and parks them the same way. The wallet only ever pays invoices this command obtained from your own mints in the same run or from its own on-disk record; nothing a caller signs is a destination. Without the flag such a refund stays queued and visible, rather than being minted from a wallet you did not authorise.

```sh
dvmctl melt-pending my-dvm --payout builder@example.com
dvmctl melt-pending my-dvm --watch --interval 120
dvmctl melt-pending my-dvm --endpoint http://localhost:3000
dvmctl melt-pending my-dvm --drains-only
dvmctl melt-pending my-dvm --refund-nwc 'nostr+walletconnect://…'
dvmctl melt-pending my-dvm --acknowledge-stuck <quote-id> --reason "mint support ticket open"
```

| Flag                             | Description                                                                                                                                                                                                                                                    |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--payout <ln-address>`          | Lightning address to melt to (overrides default set via `dvmctl set-payout`)                                                                                                                                                                                   |
| `--endpoint <url>`               | DVM admin endpoint URL (skips platform lookup; use for self-hosted DVMs or local dev)                                                                                                                                                                          |
| `--mount-prefix <path>`          | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints)                                                                                                                                                                   |
| `--org <handle>`                 | Target this org, overriding the `dvmctl switch` context                                                                                                                                                                                                        |
| `--watch`                        | Run as a long-lived daemon polling on an interval                                                                                                                                                                                                              |
| `--interval <seconds>`           | Poll cadence under `--watch` (default: 60, range: 10–3600)                                                                                                                                                                                                     |
| `--drains-only`                  | Settle the credit drains you owe and stop — no batch sweep to your payout address. `--payout` is not required, because nothing melts                                                                                                                           |
| `--hold-alarm-after <duration>`  | How long this DVM's drain surface may stay unreadable before a one-shot sweep exits non-zero instead of holding the melt again (default: `24h`; e.g. `6h`, `2d`). Nothing melts and no refund parks while it is held, so this is the ceiling on a silent stall |
| `--refund-nwc <uri>`             | Send-capable NWC connection used to buy a caller's refund when no accumulator batch covers it (env: `DVMKIT_REFUND_NWC_URL`). Keep it separate from the receive-only connection your DVM funds credit over, and hold it here rather than on the DVM            |
| `--payout-nwc <uri>`             | Mint the payout invoice from this NWC wallet instead of resolving `--payout` over LNURL (env: `DVMKIT_MELT_PAYOUT_NWC_URL`). Use when the melt destination is a node with no Lightning address of its own                                                      |
| `--acknowledge-stuck <quote-id>` | Record that this in-flight melt quote is stuck at the mint, then exit without melting. Only a quote past the 24h in-flight alarm qualifies. Requires `--reason`; cannot be combined with `--watch` or `--drains-only`                                          |
| `--reason <text>`                | Why the acknowledged quote is stuck (for example, a mint support ticket). Kept in the melt journal and logged on every later sweep                                                                                                                             |
| `--human`                        | Prose output                                                                                                                                                                                                                                                   |

**JSON output — one-shot (and each tick in `--watch` mode):**

```json
{
  "tick": "2026-05-14T00:00:00.000Z",
  "dvm_id": "550e8400-e29b-41d4-a716-446655440000",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "endpoint": "https://alice--my-dvm.dvmkit.ai",
  "batches_seen": 5,
  "batches_melted": 4,
  "batches_skipped": 1,
  "batches_failed": 0,
  "sats_melted": 50000,
  "recovered": 0,
  "drains_seen": 2,
  "drains_parked": 1,
  "drains_jit_minted": 0,
  "drains_failed": 0,
  "drains_queued": 0,
  "drains_manual": 0,
  "drains_channel": 0,
  "drains_recovered": 0,
  "drain_state_known": true,
  "drain_state_unknown_since": null,
  "melt_held": false,
  "melt_skipped": null,
  "acknowledged_melts": 0,
  "acknowledged_sats": 0
}
```

In `--watch` mode, one JSON object is emitted per tick. `endpoint` is the DVM's admin endpoint — its `url`, resolved from the platform, or whatever `--endpoint` overrode it with. For a cloud DVM that is its router address, and the router passes these admin calls through even while the DVM is paused or suspended.

The `drains_*` counters cover this tick's credit-drain pass: `parked` are cashu refunds now waiting for caller pickup, `jit_minted` is the subset of those whose notes were bought from a mint rather than swapped out of the accumulator, `manual` are one-payment (`exact`) x402 drains and any other rail without an automated sender that you must settle from your own keys and record with `POST /admin/credit/mark-drain-sent`, `queued` are refunds nothing was attempted for this tick, and `recovered` are in-flight drains reconciled from the local park log before fresh work started. `melt_held` is true when the payout melt was skipped because cashu drain liability was still outstanding.

`queued` is not `failed`, and the difference is what you do about it. Nothing was tried: no send wallet was wired, no accepted mint would quote, or an earlier purchase for that refund is still in flight and the tick is holding it deliberately so it cannot be paid for twice. The `drain_jit_*` line above each one names which of those it was.

Read `drain_state_known` before any of them. It is false when the tick could not reach the DVM's drain admin surface at all — every drain counter except `drains_recovered` then reads zero for want of an answer, not for want of work, and the melt is held back rather than run blind to what you owe. Recovery replays the local park log before that fetch, so `drains_recovered` can be non-zero even on a tick that learned nothing about what is still owed.

`drain_state_unknown_since` then says how long that has been true, carried across runs. A hold is meant to be a pause: one silent tick is a DVM still booting, a week of them is a DVM that stopped melting revenue and stopped parking refunds without ever saying so. Past `--hold-alarm-after` a one-shot sweep stops holding quietly and exits `drain_state_unknown_sustained`; a `--watch` daemon logs `melt_pending_drain_hold_sustained` on every tick instead, since exiting would only end the retries that might still fix it.

`melt_skipped` says the batch sweep never ran because you told it not to — `"drains_only"` under `--drains-only`, `null` otherwise. Read it before you read the batch counters: zero `batches_melted` alongside `"drains_only"` is the flag doing its job, not a stuck payout, and `batches_seen` is zero because nothing was even fetched.

A one-shot `--drains-only` run exits non-zero unless it settled everything it owes, since settling is the whole point of the mode: `drain_state_unknown` when it never got to read the drain list, and `drains_unsettled` when `drains_failed`, `drains_manual` or `drains_queued` is non-zero — each has its own way out, and the hint names the one you hit. `drains_channel` is counted but never alarms: a channel-backed reclaim is settled by its own close on the caller's next poll, so there is nothing for you to do about one. Cron it and let the exit code speak. A plain sweep is deliberately not symmetric: there, an unsettled refund holds the melt back and retries on the next tick, and failing the daily melter over it would page you about a healthy DVM.

**Acknowledging a stuck melt:**

Every melt is journalled in `~/.dvmkit/melt-pending.log` before it is submitted. While the mint reports a submitted quote as `PENDING`, its rows are held out of new melts so the same ecash is never offered for a second payment, and each sweep asks the mint about the quote again. Once that melt has been in flight for 24 hours, the sweep logs `melt_pending_batch_in_flight` with a `hint` and exits `batches_failed`.

When the mint will not resolve the quote, and you have already taken it up with the mint, acknowledge it so the daily run stops failing on it and can report new failures again:

```sh
dvmctl melt-pending my-dvm --acknowledge-stuck <quote-id> --reason "mint support ticket open"
```

This appends one entry to the journal and exits. Nothing melts, and no mint or DVM admin call is made. It does not write anything off. The rows stay held, and every later sweep still checks the quote: `PAID` with a preimage marks the rows melted, and `UNPAID` releases them to a fresh melt. Until then the sweep logs `melt_pending_batch_acknowledged` (with `quote_id`, `age_ms` and your `reason`) in place of the alarm, and counts the melt in `acknowledged_melts` and `acknowledged_sats`, so held money stays visible in the summary. The acknowledgement only covers the mint answering `PENDING`: if a sweep cannot reach the mint, gets `PAID` without a preimage, or cannot hand the preimage to the DVM, the alarm returns and the run fails, because sats may have left without the rows being marked melted. Acknowledging again replaces the logged reason. Run it on the host that runs the sweep, because the journal is local.

Releases from before this flag ignore the acknowledgement and keep alarming on that quote. They never release its rows.

**JSON output — `--acknowledge-stuck`:**

```json
{
  "acknowledged": true,
  "dvm_id": "550e8400-e29b-41d4-a716-446655440000",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "quote_id": "q-7f3a",
  "mint_url": "https://mint.example",
  "row_ids": ["row-1", "row-2"],
  "total_sats": 1200,
  "age_ms": 190800000,
  "reason": "mint support ticket open",
  "acknowledged_at": "2026-05-16T05:00:00.000Z"
}
```

A plain sweep does exit non-zero on the two things that will not fix themselves. `admin_bad_signature` — the DVM advertises a lock pubkey your mnemonic cannot derive, so every admin call it makes is rejected; retrying that forever is what a hold would otherwise do. And `drain_state_unknown_sustained` — the drain surface has been unreadable for longer than `--hold-alarm-after`, so the hold has stopped being a pause. A refund merely waiting on accumulation still exits 0 for as long as it takes: that DVM is working as designed.

**Error anchors:**

| Code                            | Trigger                                                                                                                                                      |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `no_builder_mnemonic`           | No mnemonic found — run `dvmctl lock create` first                                                                                                           |
| `dvm_not_initialized`           | No `builder.json` entry for this handle                                                                                                                      |
| `no_payout_destination`         | No `--payout` flag and no default set via `dvmctl set-payout` (not required under `--drains-only`)                                                           |
| `auth_required`                 | Not authenticated (needed to resolve endpoint via platform)                                                                                                  |
| `admin_bad_signature`           | DVM's lock pubkey doesn't match the derived privkey — raised by whichever admin call hits it first, including the drain fetch                                |
| `pending_batches_fetch_failed`  | Failed to fetch pending batches from DVM admin endpoint                                                                                                      |
| `batches_failed`                | One or more batches failed during the sweep (one-shot only)                                                                                                  |
| `drains_unsettled`              | One or more credit drains went unsettled — failed, or awaiting manual settlement (one-shot `--drains-only` only)                                             |
| `drain_state_unknown`           | The DVM's pending drains could not be read, so nothing beyond a recovered park was settled (one-shot `--drains-only` only)                                   |
| `drain_state_unknown_sustained` | The drain surface has been unreadable for longer than `--hold-alarm-after`, so the melt hold is a standstill rather than a pause (one-shot plain sweep only) |
| `invalid_duration`              | `--hold-alarm-after` is not one count and one unit (e.g. `6h`, `2d`)                                                                                         |
| `dvm_url_unset`                 | DVM has no platform URL yet                                                                                                                                  |
| `acknowledge_reason_required`   | `--acknowledge-stuck` or `--reason` was passed without the other, or with an empty value                                                                     |
| `acknowledge_conflicting_flags` | `--acknowledge-stuck` was combined with `--watch` or `--drains-only`                                                                                         |
| `melt_quote_not_found`          | No melt for that quote is journalled for this DVM on this machine                                                                                            |
| `melt_quote_resolved`           | The melt for that quote is already resolved, so there is nothing to acknowledge                                                                              |
| `melt_quote_too_young`          | The melt has been in flight for less than 24 hours                                                                                                           |

***

melt-status [#melt-status]

Report when [`melt-pending`](#melt-pending) last completed cleanly for each DVM on this machine, and optionally exit non-zero when that was too long ago.

`melt-pending` is almost always run by something: a cron, a launchd job, or a `--watch` daemon. All three die the same silent way: the process stops, and there is no exit code anyone reads, no growing log, and no next run to notice. The only symptom is revenue that quietly stops arriving and caller refunds that quietly stop parking. So every run that completes cleanly stamps `~/.dvmkit/melt-success.json`, keyed by the DVM's immutable id, and this command reads it back. Nothing here talks to the dvmkit platform. The record is a local file, so a DVM you host anywhere can be alarmed on however you like.

A run that would have exited non-zero deliberately leaves the previous timestamp standing, in both one-shot and `--watch` mode. A daemon that is alive but failing every tick has not melted anything, and a liveness record saying otherwise is worse than none.

Each DVM keeps **one clock per mode**, and only the sweep's counts. A `--drains-only` run settles refunds and sweeps nothing, so it is reported separately and never satisfies `--max-age`. Both are recommended together, and folding them into one clock would let an hourly drains-only cron vouch for a `--watch` sweep daemon that died weeks ago.

`--max-age` watches **every** DVM on this machine, and one with no sweep on record is stale rather than exempt. That direction is deliberate: the record is best-effort in three independent ways, since an unwritable file is swallowed, a malformed entry is dropped on read, and the read-modify-write is not atomic against two `--watch` daemons. If a missing record meant "do not alarm", any partial loss of it would silently disarm the alarm for a DVM that is genuinely melting, which is the failure this whole command exists to prevent.

So exemption is something you say, never something this infers. `--except <handle>` (repeatable) drops a DVM from the alarm, which is what you want for one with no Cashu rail that is never going to melt. The question that actually matters is "does this DVM have a Cashu rail", `builder.json` cannot answer it, and inferring it from melt history is exactly what produced silence for DVMs that needed watching.

Install the melt job first and let it succeed once, **then** add the `--max-age` cron. Fail-closed means a fresh alarm is red until the first sweep lands. That is correct and clears itself, but a first-ever run that fires a false alarm is a good way to teach yourself to ignore the real one.

```sh
dvmctl melt-status                        # every DVM this machine knows about
dvmctl melt-status my-dvm                 # just one
dvmctl melt-status --max-age 30h          # exit non-zero on anything staler (this is the alarm)
dvmctl melt-status --max-age 30h --except my-free-dvm   # …but never alarm on that one
```

| Flag                   | Description                                                                                                                                                                                                                                                                                  |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--max-age <duration>` | Exit non-zero when a DVM has not **swept** successfully within this window (e.g. `30h`, `2d`). Set it a little longer than your melt cadence so one late run is not an alarm. Every DVM is watched, a DVM that has never swept counts as stale, and a `--drains-only` run never satisfies it |
| `--except <handle>`    | Do not alarm on this DVM under `--max-age`. Repeatable. For a DVM with no Cashu rail, which never melts and would otherwise hold the alarm red forever                                                                                                                                       |
| `--human`              | Prose output                                                                                                                                                                                                                                                                                 |

**JSON output:**

```json
{
  "dvms": [
    {
      "handle": "my-dvm",
      "dvm_id": "550e8400-e29b-41d4-a716-446655440000",
      "last_success_at": "2026-08-21T06:00:12.000Z",
      "age_seconds": 3612,
      "stale": false,
      "batches_melted": 3,
      "sats_melted": 42000,
      "drains_parked": 1,
      "last_drains_only_at": "2026-08-21T06:30:04.000Z",
      "drains_only_age_seconds": 1820
    }
  ],
  "max_age_seconds": 108000,
  "excepted": [],
  "state_file": "/home/you/.dvmkit/melt-success.json"
}
```

`last_success_at` and its counters describe the last clean **sweep**; `last_drains_only_at` is reported beside them and never counts toward `stale`. Both are `null`, and `stale` true under any `--max-age`, for a DVM that has never had a clean run **on this machine**, which is the right reading: a melt job that never once succeeded looks exactly like one with nothing to report, and treating that as healthy is the failure this command exists to prevent. `state_file` is the absolute path of the record itself, for alarming on the file directly rather than through the CLI.

`excepted` lists the handles `--except` actually matched, so a misspelled flag shows up as an absence rather than as a DVM that quietly stopped being watched. A typo fails safe either way: the DVM stays in the alarm, which is also why a `--except` matching nothing is not an error: a DVM you retire should not break a working cron. What *is* refused is an `--except` on a handle two `builder.json` entries claim: dropping both would silently unwatch a live DVM alongside a retired one, so it errors exactly as naming that handle positionally does.

A sweep stamped in the **future** counts as no sweep at all, so the DVM reads stale rather than fresh. A host that stamps before its clock syncs would otherwise be measured against a date years ahead and stay green until the clock caught up.

`--max-age` refuses outright when there is nothing left for it to watch, whether this machine records no DVMs at all or every one was excepted. Reporting a green list and exiting 0 would be an alarm that can never fire. For the first case the usual cause is not a machine without DVMs but a cron or launchd job running in a minimal environment against the wrong `HOME`. Set `DVMKIT_CONFIG_DIR` explicitly in the job if that is what happened.

**Error anchors:**

| Code                    | Trigger                                                                                                                          |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `melt_stale`            | One or more DVMs have not swept successfully within `--max-age`                                                                  |
| `no_dvms_recorded`      | `--max-age` was given but nothing is left to watch: this machine's `builder.json` records no DVMs, or every one was `--except`ed |
| `invalid_duration`      | `--max-age` is not one count and one unit (e.g. `30h`, `2d`)                                                                     |
| `invalid_except_handle` | An `--except` value is not a handle. Usually the next flag was swallowed as its value, e.g. `--except --max-age`                 |
| `dvm_not_initialized`   | A handle was named with no `builder.json` entry for it                                                                           |
| `ambiguous_dvm_handle`  | Two `builder.json` entries claim that handle, either named positionally or passed to `--except`                                  |

***

refund [#refund]

Return a completed job's charge to the caller's prepaid credit. The caller can use that balance on another job or reclaim it with `dvm credit drain`.

```sh
dvmctl refund job-123 --dvm my-dvm
dvmctl refund job-123 --dvm my-dvm --confirm
dvmctl refund job-456 --dvm my-dvm --amount 0.005 --confirm
```

| Flag                    | Description                                                                                                          |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `--dvm <handle>`        | DVM slug; defaults to the current project's name, as for `deploy`                                                    |
| `--amount <decimal>`    | Amount in the job's credit currency, with at most six decimal places; omit to refund the remaining unrefunded charge |
| `--reason <text>`       | Optional reason, at most 280 characters                                                                              |
| `--refund-id <id>`      | Override the deterministic ID for a deliberate additional partial refund                                             |
| `--confirm`             | Submit the refund; without it, exit with `confirmation_required` and send no HTTP request                            |
| `--endpoint <url>`      | DVM admin endpoint URL for self-hosted DVMs or local development                                                     |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints)                         |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                                              |
| `--human`               | Prose output                                                                                                         |

Without `--confirm`, the command describes a local intent. It does not read the original charge, determine eligibility, or quote a refundable amount. An explicit `--amount` uses the job's credit currency; omitting it means the remaining unrefunded charge.

A confirmed success has `status: "refunded"` and identifies the persisted refund with `refund_id`, `credit_id`, `draw_id`, and `job_id`. Its monetary fields are `amount_micro`, `currency`, `ledger_seq`, `refunded_at`, and `balance_after_micro`. Amounts in micro-units are millionths of `currency`.

Repeat the same command after an uncertain result. Its deterministic ID stays the same, including when `--amount` is omitted. A replay returns `replayed: true` and the original monetary fields. `balance_after_micro` describes that original refund, so it may differ from the caller's current balance after later activity. Use a new `--refund-id` only for a deliberate additional partial refund.

The DVM requires a persistent credit store and a configured platform refund reporter. It refuses per-job payments, closed credits, and credits backed by a Tempo or x402 payment channel. Older credits with an unproven open state or original Bitcoin value require independent payment evidence; retrying alone cannot repair that evidence. Each refusal includes a `hint` naming the next step.

credit blocked [#credit-blocked]

List the Lightning top-ups your DVM received but could never credit — the queue behind every `lightning_settlement_blocked` log line. A caller reused a `fund_id` on another rail after the invoice was minted, or named a `credit_id` someone else opened first, so their payment landed in your wallet with no balance able to take it.

Read-only: the money is still in your wallet and nothing here moves it. Signed with the same builder lock key `melt-pending` uses, derived locally from your mnemonic.

```sh
dvmctl credit blocked my-dvm
dvmctl credit blocked my-dvm --include-resolved
dvmctl credit blocked my-dvm --limit 10 --after eyJ...
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--endpoint <url>`      | DVM admin endpoint URL (skips the platform lookup; use for self-hosted DVMs or local dev)    |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--limit <n>`           | Page size (default: 50, max 200)                                                             |
| `--after <cursor>`      | Continue from a previous run's `next_after` value                                            |
| `--include-resolved`    | Also list rows you already reconciled or wrote off — the audit view                          |
| `--human`               | Prose output                                                                                 |

**JSON output:**

```json
{
  "op": "credit_blocked",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "invoices": [
    {
      "payment_hash": "9a3f...",
      "credit_id": "fnd:ab12...:topup-7",
      "fund_id": "topup-7",
      "caller_pubkey": "ab12...",
      "currency": "usd",
      "amount_micro": 500000,
      "amount_msats": 500000,
      "status": "blocked",
      "blocked_reason": "funding_replayed_on_cashu",
      "created_at": 1754000000000,
      "settled_at": null,
      "reconciled_credit_id": null,
      "resolved_at": null,
      "write_off_note": null
    }
  ],
  "blocked_count": 1,
  "display": "1 Lightning payment(s) landed in this DVM's wallet with no caller balance to put them on.",
  "hint": "Credit one onto a credit the caller holds with `dvmctl credit reconcile <handle> <payment-hash> --credit-id <id>`, or close it with `dvmctl credit write-off`."
}
```

`blocked_reason` names what the ledger refused on: `funding_replayed_on_<rail>` (the caller spent that `fund_id` elsewhere), `caller_mismatch` (someone else opened the credit first), `currency_mismatch`, `rail_mismatch`, or `invalid_basis`. `next_after` is present only when the page was full — pass it to `--after` to continue. Pagination is keyset-based rather than by page number, because a row you decline to act on stays at the head of the queue forever and would otherwise crowd out everything behind it.

**Error anchors:**

| Code                  | Trigger                                                                |
| --------------------- | ---------------------------------------------------------------------- |
| `invalid_limit`       | `--limit` outside 1..200                                               |
| `admin_bad_signature` | The DVM's lock pubkey doesn't match the key derived from this mnemonic |
| `admin_unreachable`   | The DVM's admin endpoint didn't answer                                 |
| `dvm_url_unset`       | No platform URL for this handle yet — pass `--endpoint`                |

***

credit reconcile [#credit-reconcile]

Credit a blocked Lightning payment onto a credit the caller holds. **Idempotent** — running it twice credits once.

You name only the target credit. The amount, currency, caller identity and rail basis all come off the invoice row your DVM recorded when it minted the bolt11, so this cannot credit more than arrived and cannot credit it to anyone but the caller who paid. Before moving anything the DVM re-confirms with its receive wallet that the invoice really settled, and the deposit is booked in the same transaction as the balance, so the platform's outstanding-liability view catches up on its own.

Which credit is the one thing that isn't derivable from the failed row — ask the caller, or use the `credit_id` from `dvmctl credit blocked`, which is the top-up the invoice was minted for.

```sh
dvmctl credit blocked my-dvm
dvmctl credit reconcile my-dvm 9a3f... --credit-id fnd:ab12...:topup-7
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--credit-id <id>`      | Credit the payment should land on (required)                                                 |
| `--endpoint <url>`      | DVM admin endpoint URL (skips the platform lookup; use for self-hosted DVMs or local dev)    |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Prose output                                                                                 |

**JSON output:**

```json
{
  "op": "credit_reconcile",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "payment_hash": "9a3f...",
  "credit_id": "fnd:ab12...:topup-7",
  "fund_id": "9a3f...",
  "amount_micro": 500000,
  "currency": "usd",
  "replayed": false,
  "credit": {
    "credit_id": "fnd:ab12...:topup-7",
    "currency": "usd",
    "balance_micro": 500000,
    "remaining_micro": 500000,
    "expiry_ms": 1756592000000
  },
  "display": "Credited 0.500000 USD to fnd:ab12...:topup-7. The caller can spend it now.",
  "hint": "The deposit is reported to the platform on the DVM's own retry loop, so its liability view catches up without another command."
}
```

`replayed: true` means this payment had already been credited to that credit and nothing moved. `fund_id` on the response is the payment hash, not the caller's original `fund_id` — that key is frequently the one that blocked the invoice in the first place, so the funding is recorded under the hash instead. The caller's next poll of their original `fund_id` returns a 200 naming the credit their balance actually landed on.

**Error anchors:**

| Code                               | Trigger                                                                                                              |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `missing_credit_id`                | No `--credit-id` given                                                                                               |
| `invoice_not_found`                | No invoice for that payment hash                                                                                     |
| `invoice_not_blocked`              | The invoice is pending, settled or expired — nothing to reconcile                                                    |
| `invoice_already_reconciled`       | Already credited, to a *different* credit than the one named                                                         |
| `funding_replayed`                 | Something else already holds `(named credit, payment hash)` — name a different credit                                |
| `invoice_not_settled`              | The receive wallet reports the invoice as unpaid                                                                     |
| `invoice_unknown_to_wallet`        | The wallet has no record of that payment — you're pointed at a different wallet than the one that minted the invoice |
| `wallet_unreachable`               | Couldn't reach the receive wallet to confirm the payment                                                             |
| `lightning_receive_not_configured` | The DVM has no `DVMKIT_NWC_RECEIVE_URI`, so it can't confirm anything                                                |
| `caller_mismatch`                  | That credit belongs to another caller                                                                                |
| `currency_mismatch`                | That credit is denominated in a different currency                                                                   |
| `rail_mismatch`                    | That credit was funded on another rail                                                                               |
| `currency_drift`                   | The DVM's declared currency changed since the invoice was minted                                                     |
| `credit_id_unavailable`            | The named credit is in a namespace the provider derives and doesn't exist yet                                        |

***

credit write-off [#credit-write-off]

Record that you reviewed a blocked Lightning payment and are not crediting it.

Moves no money: the sats stay in your wallet and no caller balance is created for them. dvmkit books nothing either way — there is no job to attribute the revenue to — so the note on the row and the `lightning_invoice_written_off` log are the only record of the amount. It exists so a row you've decided about leaves the queue without pretending it settled, and it is reversible: `dvmctl credit reconcile` still accepts a written-off invoice.

```sh
dvmctl credit write-off my-dvm 9a3f... --note "caller made whole on cashu"
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--note <text>`         | Why you are not crediting it. Recorded on the invoice row                                    |
| `--endpoint <url>`      | DVM admin endpoint URL (skips the platform lookup; use for self-hosted DVMs or local dev)    |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Prose output                                                                                 |

**JSON output:**

```json
{
  "op": "credit_write_off",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "payment_hash": "9a3f...",
  "amount_micro": 500000,
  "currency": "usd",
  "note": "caller made whole on cashu",
  "replayed": false,
  "display": "Closed this payment without crediting it. The 0.500000 USD stays in your wallet and no caller balance was created for it.",
  "hint": "Reversible: `dvmctl credit reconcile` still accepts a written-off invoice if you change your mind."
}
```

`replayed: true` means the invoice was already written off and this call changed nothing — including the note, which stays whatever the first write-off recorded. `note` on the response is always the note on the row, so a replay shows you the reason already on file rather than the one you just passed.

**Error anchors:**

| Code                  | Trigger                                                           |
| --------------------- | ----------------------------------------------------------------- |
| `invoice_not_found`   | No invoice for that payment hash                                  |
| `invoice_not_blocked` | The invoice isn't blocked — only a blocked one can be written off |

***

credit x402-wedged [#credit-x402-wedged]

List the x402 cooperative refunds that reached the chain but never cleared the caller's balance.

An x402 drain pays out on chain and extinguishes the ledger liability in two steps, and the on-chain half is deliberately recorded before the ledger half so a crash can be recovered. When the ledger half refuses — most often because what the facilitator reported it settled doesn't match what the ledger is extinguishing — the refund is gone and the caller's balance is still sitting there, and every retry hits the same refusal. These are those settlements.

Read-only. Each row carries what the chain itself says, which is what decides whether it can be finished or has to be closed. Those lookups are chunked log scans, so the page ceiling is low and `--no-evidence` skips them entirely.

```sh
dvmctl credit x402-wedged my-dvm
dvmctl credit x402-wedged my-dvm --include-resolved
dvmctl credit x402-wedged my-dvm --limit 10 --after eyJ... --no-evidence
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--endpoint <url>`      | DVM admin endpoint URL (skips the platform lookup; use for self-hosted DVMs or local dev)    |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--limit <n>`           | Page size (default: 20, max 50)                                                              |
| `--after <cursor>`      | Continue from a previous run's `next_after` value                                            |
| `--include-resolved`    | Also list settlements you already wrote off — the audit view                                 |
| `--min-age-ms <ms>`     | How long a settlement must have sat before it counts as stuck (default: 300000)              |
| `--no-evidence`         | Skip the per-row chain lookups — a fast read of the queue itself                             |
| `--human`               | Prose output                                                                                 |

**JSON output:**

```json
{
  "op": "credit_x402_wedged",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "settlements": [
    {
      "settlement_id": "5e2c...",
      "channel_id": "0x7c1a...",
      "operation": "refund",
      "effect_id": "imp:x402:0xabc...:drain-7",
      "credit_id": "imp:x402:0xabc...",
      "drain_id": "drain-7",
      "status": "settled",
      "submission_block": "18420031",
      "settled_amount": "999",
      "settled_transaction": "0x9ff1...",
      "created_at": 1754000000000,
      "updated_at": 1754000000000,
      "resolved_at": null,
      "write_off_note": null,
      "chain": { "chain": "found", "transaction": "0x9ff1...", "amount": "400000" }
    }
  ],
  "wedged_count": 1,
  "repairable_count": 1,
  "display": "1 x402 refund(s) settled on chain without the caller's credit balance being cleared. 1 of them have a matching refund the chain can confirm.",
  "hint": "Finish one with `dvmctl credit x402-reconcile <handle> <settlement-id>` — the amount comes off the chain, not from you. If the chain and the ledger disagree, close it with `dvmctl credit x402-write-off`."
}
```

`chain` is the answer to "did this actually happen", and its four values are deliberately distinct. `found` carries the chain's own transaction and amount and is the only one `x402-reconcile` will act on. `absent` means the chain was read from the submission block to the head of the chain and this refund is not on it. `unreachable` means the RPC endpoint didn't answer and says nothing either way — retry, or point the DVM at a different endpoint first. `unbookmarked` means the settlement recorded no submission block, so there is no range to scan.

`settled_amount` is what the facilitator claimed; the amount under `chain` is what the chain shows. A disagreement between those two is the usual reason a settlement is on this list at all. `next_after` is present only when the page was full.

**Error anchors:**

| Code                          | Trigger                                                                                   |
| ----------------------------- | ----------------------------------------------------------------------------------------- |
| `invalid_limit`               | `--limit` outside 1..50                                                                   |
| `x402_settlement_unavailable` | This DVM has no durable x402 batch-settlement store, so it holds no settlements to repair |
| `admin_bad_signature`         | The DVM's lock pubkey doesn't match the key derived from this mnemonic                    |
| `admin_unreachable`           | The DVM's admin endpoint didn't answer                                                    |
| `dvm_url_unset`               | No platform URL for this handle yet — pass `--endpoint`                                   |

***

credit x402-reconcile [#credit-x402-reconcile]

Finish the ledger leg of an x402 refund the chain already paid. **Idempotent** — running it twice books once.

You name only the settlement. The DVM re-derives the refund amount from the chain's own logs and completes the drain against that figure, so this cannot extinguish a different amount than the chain actually returned, and the amount can't be supplied from here at all. The reclaim is reported to the platform in the same transaction as the drain's transition, so its liability view catches up without another command.

If the chain's figure and the ledger's disagree, this refuses and names both. That refusal is the point: a real discrepancy still stops the drain, and `dvmctl credit x402-write-off` is how such a settlement gets closed with a reason on record.

```sh
dvmctl credit x402-wedged my-dvm
dvmctl credit x402-reconcile my-dvm 5e2c...
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--endpoint <url>`      | DVM admin endpoint URL (skips the platform lookup; use for self-hosted DVMs or local dev)    |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Prose output                                                                                 |

**JSON output:**

```json
{
  "op": "credit_x402_reconcile",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "settlement_id": "5e2c...",
  "channel_id": "0x7c1a...",
  "credit_id": "imp:x402:0xabc...",
  "drain_id": "drain-7",
  "transaction": "0x9ff1...",
  "settled_amount": "400000",
  "amount_micro": 400000,
  "currency": "usd",
  "replayed": false,
  "display": "Cleared the caller's balance on imp:x402:0xabc... against the refund the chain already paid (0x9ff1...).",
  "hint": "The reclaim is reported to the platform on the DVM's own retry loop, so its liability view catches up without another command."
}
```

`settled_amount` is in the channel token's own atomic units (USDC micro-units); `amount_micro` is the fiat liability the ledger extinguished. `replayed: true` means the settlement was already booked and nothing moved.

**Error anchors:**

| Code                        | Trigger                                                                                                                                              |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `settlement_not_found`      | No settlement with that id                                                                                                                           |
| `settlement_not_wedged`     | The settlement isn't stuck between chain and ledger — nothing to finish                                                                              |
| `settlement_not_repairable` | It's a deposit, not a cooperative refund. A wedged deposit recovers when the caller re-presents it                                                   |
| `credit_not_bound`          | No credit is bound to that channel any more, so there is no liability to extinguish                                                                  |
| `settlement_unbookmarked`   | The settlement recorded no submission block, so the chain can't be scanned for it                                                                    |
| `settlement_not_on_chain`   | The chain was read and carries no matching refund. Nothing was booked                                                                                |
| `chain_unreachable`         | The RPC endpoint didn't answer. This says nothing about whether the money moved                                                                      |
| `settlement_raced`          | Another repair, or a caller retry, moved this settlement mid-reconcile. Nothing was booked twice — re-read it with `x402-wedged` before acting again |
| `drain_conflict`            | The chain's figure and the ledger's don't match — the message names both                                                                             |

***

credit x402-write-off [#credit-x402-write-off]

Record that you reviewed a wedged x402 settlement and are not booking it.

Books nothing anywhere. If the refund did reach the chain, the caller already has it, and their matching credit balance stays on this ledger where they can reclaim it with a fresh drain — so the note on the row and the `x402_settlement_written_off` log are the only record. It exists so a settlement you've decided about leaves the queue without pretending it booked, and it is reversible: `dvmctl credit x402-reconcile` still accepts a written-off settlement.

A caller who re-presents the same refund voucher after a write-off gets a terminal refusal telling them to reclaim under a new drain id — not a payment challenge, which an agent would answer by re-signing the same voucher and landing straight back on the write-off. A new drain id opens a fresh settlement against whatever the channel really has left.

Reversing it is `x402-reconcile`, and a reconcile that then refuses leaves the write-off exactly as it found it — note, timestamp and all — so a settlement never sits in the queue advertising a decision that was undone.

```sh
dvmctl credit x402-write-off my-dvm 5e2c... --note "chain paid 250000, ledger owes 400000 — investigating"
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--note <text>`         | Why you are not booking it. Recorded on the settlement row                                   |
| `--endpoint <url>`      | DVM admin endpoint URL (skips the platform lookup; use for self-hosted DVMs or local dev)    |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Prose output                                                                                 |

**JSON output:**

```json
{
  "op": "credit_x402_write_off",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "settlement_id": "5e2c...",
  "channel_id": "0x7c1a...",
  "effect_id": "imp:x402:0xabc...:drain-7",
  "note": "chain paid 250000, ledger owes 400000 — investigating",
  "replayed": false,
  "display": "Closed this settlement without booking it. No ledger row moved: if the refund did reach the chain, the caller still holds the matching credit balance here and can reclaim it with a new drain.",
  "hint": "Reversible: `dvmctl credit x402-reconcile` still accepts a written-off settlement if you change your mind."
}
```

`replayed: true` means it was already written off and this call changed nothing — including the note, which stays whatever the first write-off recorded.

**Error anchors:**

| Code                        | Trigger                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| `settlement_not_found`      | No settlement with that id                                                                 |
| `settlement_not_wedged`     | The settlement isn't stuck between chain and ledger — only a wedged one can be written off |
| `settlement_not_repairable` | It's a deposit, not a cooperative refund                                                   |

***

credit x402-exact-wedged [#credit-x402-exact-wedged]

Lists exact x402 authorizations that may have settled on chain but have not finished the credit, draw, or job effect they were created for. The output never includes the signed payment header or facilitator credential.

```bash
dvmctl credit x402-exact-wedged my-dvm
dvmctl credit x402-exact-wedged my-dvm --include-resolved --limit 10
```

Options:

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--endpoint <url>`      | Call a self-hosted or local DVM directly                                                     |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org instead of the current switch context                                        |
| `--limit <n>`           | Rows to return (default 20, maximum 50)                                                      |
| `--include-resolved`    | Include completed and definitively rejected intents                                          |
| `--human`               | Human-readable output instead of JSON                                                        |

```json
{
  "op": "credit_x402_exact_wedged",
  "handle": "my-dvm",
  "settlements": [
    {
      "settlement_intent_id": "8f3d...",
      "status": "ambiguous",
      "transaction": null,
      "last_outcome": "missing_reference",
      "credit_id": "credit-1",
      "job_id": null
    }
  ],
  "wedged_count": 1,
  "display": "1 exact x402 payment(s) need an operator decision or local finalization.",
  "hint": "Run `dvmctl credit x402-exact-reconcile <handle> <settlement-intent-id>` only after this queue shows the authorization; the DVM derives the transaction and amount from its own evidence."
}
```

credit x402-exact-reconcile [#credit-x402-exact-reconcile]

Finishes the original local effect of an exact x402 authorization that the DVM can prove settled on chain. It accepts no transaction or amount flags: both come from the authorization's bookmarked chain evidence, and a replay books nothing again.

```bash
dvmctl credit x402-exact-reconcile my-dvm 8f3d...
```

Options:

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--endpoint <url>`      | Call a self-hosted or local DVM directly                                                     |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org instead of the current switch context                                        |
| `--human`               | Human-readable output instead of JSON                                                        |

```json
{
  "op": "credit_x402_exact_reconcile",
  "handle": "my-dvm",
  "status": "reconciled",
  "settlement_intent_id": "8f3d...",
  "transaction": "0xabc...",
  "amount": "100000",
  "credit_id": "credit-1",
  "draw_id": null,
  "job_id": null,
  "replayed": false,
  "display": "Finalized the original local effect for exact x402 transaction 0xabc....",
  "hint": "The original credit funding is now recorded; the caller can read that credit without paying again."
}
```

***

credit tempo-losses [#credit-tempo-losses]

List the immutable audit records created when a Tempo channel finalized before the DVM collected value under its highest accepted voucher. The former nominal credit balance remains visible for incident review, alongside the on-chain settlement, highest voucher, consumed service value, channel, and observation time, but the credit is terminal and has no drawable or reclaimable value.

This is deliberately read-only. There is no refund, mark-sent, retry, or repair action because the channel has already finalized and the missing backing cannot be collected.

```sh
dvmctl credit tempo-losses my-dvm
dvmctl credit tempo-losses my-dvm --limit 50
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--limit <n>`           | Rows to return (default: 20, max 50)                                                         |
| `--endpoint <url>`      | DVM admin endpoint URL (skips the platform lookup; use for self-hosted DVMs or local dev)    |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Prose output                                                                                 |

The JSON response uses `op: "credit_tempo_losses"`. Each `losses[]` row carries `credit_id`, `channel_id`, `former_balance_micro`, `settled_on_chain_native`, `highest_voucher_native`, `consumed_service_micro`, `consumed_native`, `observed_at`, and terminal `status: "unbacked"`; `hint` states that no money-moving action exists.

***

credit tempo-wedged [#credit-tempo-wedged]

List Tempo cooperative closes that landed on chain but never booked the caller's drain.

A Tempo channel close debits the caller's credit balance when the close intent is reserved, then broadcasts, then checks that what the chain refunded covers what the ledger extinguished. When that last step refuses, the channel is closed, the balance is gone, and every retry — the caller's own poll included — lands on the same refusal, because a closed channel cannot pay a second time. This is that queue.

Each row puts the two figures side by side: `amount_native` is the debit the refund has to cover, and `chain.refundedToPayer` is what the close receipt says it paid. Reading the chain costs an RPC round trip per row, so the page ceiling is 50 and `--no-evidence` skips the lookups entirely when you only want to see how many rows there are. A row whose RPC fails comes back `chain: "unreachable"` rather than failing the whole page — that says nothing about what the close paid, which is exactly why it is not the same answer as a close that names no receipt.

Drains you have already written off are hidden by default; `--include-resolved` is the audit view.

A drain with `status: "exit_required"` is classified using its chain evidence. If a close landed and its refund covers the debit, it counts in `wedged_count` and `repairable_count` and can be finished with `tempo-reconcile`. If a close landed with a short refund, no command can repair it yet: `tempo-write-off` refuses this status. These short terminal rows are counted separately in `exit_required_short_refund_count`, outside `short_refund_count` and `wedged_count`. A confirmed no-close result (`chain: "unconfirmed"`) means cooperative close is unavailable, and the caller must recover the funds with the timed exit; these rows appear in `timed_exit_count`. Unchecked, failed, or unknown chain reads, a missing close receipt, and a landed close with an unknown debit or unreadable refund instead get a "chain evidence unavailable" explanation. Re-run with chain lookups (omit `--no-evidence`), or check the channel before choosing an action. Those rows appear in `exit_required_evidence_unavailable_count`. `exit_required_count` counts unresolved rows with that status. All action counts exclude written-off drains, including under `--include-resolved`; the audit rows remain visible with their recorded notes and timestamps. Human output and JSON explanations distinguish all four cases. Builder payout reports are separate: inspect them with [`credit tempo-close-reports`](#credit-tempo-close-reports).

```sh
dvmctl credit tempo-wedged my-dvm
dvmctl credit tempo-wedged my-dvm --include-resolved --limit 50
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--limit <n>`           | Page size (default: 20, max 50)                                                              |
| `--after <cursor>`      | Continue from a previous run's `next_after` value                                            |
| `--include-resolved`    | Also list drains you already wrote off — the audit view                                      |
| `--min-age-ms <ms>`     | How long a drain must have sat before it counts as stuck (default: 300000)                   |
| `--no-evidence`         | Skip the per-row chain lookups — a fast read of the queue itself                             |
| `--endpoint <url>`      | DVM admin endpoint URL (skips the platform lookup; use for self-hosted DVMs or local dev)    |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Prose output                                                                                 |

**JSON output:**

```json
{
  "op": "credit_tempo_wedged",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "drains": [
    {
      "credit_id": "imp:tempo:challenge-9",
      "drain_id": "drain-7",
      "channel_id": "0x3a1b...",
      "amount_micro": 400000,
      "amount_native": 400000,
      "currency": "usd",
      "caller_pubkey": "ab12...",
      "status": "pending",
      "created_at": 1755200000000,
      "write_off_note": null,
      "written_off_at": null,
      "chain": {
        "chain": "found",
        "transaction": "0xb1c2...",
        "refundedToPayer": "390000",
        "settledToPayee": "110000"
      }
    }
  ],
  "wedged_count": 1,
  "repairable_count": 0,
  "short_refund_count": 1,
  "awaiting_close_count": 0,
  "exit_required_count": 0,
  "exit_required_short_refund_count": 0,
  "timed_exit_count": 0,
  "exit_required_evidence_unavailable_count": 0,
  "display": "1 Tempo close(s) landed on chain without the caller's credit balance being booked as paid. 0 paid enough to cover the debit and can be finished. 1 refunded the caller less than was extinguished — those cannot be reconciled and need a decision.",
  "hint": "Finish a repairable drain with `dvmctl credit tempo-reconcile <handle> <credit-id> <drain-id>` — the amount comes off the close receipt, not from you. If a pending drain's refund was genuinely short, close it with `dvmctl credit tempo-write-off`. Drains you have already written off are not counted here; re-run with `--include-resolved` to see those."
}
```

`repairable_count` is the rows whose on-chain refund covers the debit — those finish with `tempo-reconcile`. `short_refund_count` counts pending drains where the chain named a figure and it fell short; a reconcile refuses those, and `tempo-write-off` is how one gets closed. Landed short refunds on `exit_required` drains are separate and have no repair command yet. `awaiting_close_count` is counted separately and excluded from `wedged_count`: those are pending drains whose channel has no confirmed close at all, so nothing landed on chain and no repair applies — the caller's own poll is what finishes them. `next_after` appears when the page was full.

**Error anchors:**

| Code                       | Trigger                                                                     |
| -------------------------- | --------------------------------------------------------------------------- |
| `invalid_limit`            | `--limit` outside 1..50, refused before the DVM is called                   |
| `tempo_repair_unavailable` | The DVM has no durable Tempo session store, so it holds no closes to repair |
| `admin_bad_signature`      | The DVM advertises a lock pubkey your mnemonic cannot derive                |

***

credit tempo-book [#credit-tempo-book]

Record that the caller received the entire held Tempo refund, including any remainder returned outside the channel. This command records your decision; it sends no payment. Use `credit tempo-wedged` to identify the exact credit and drain first.

```sh
dvmctl credit tempo-book my-dvm credit-1 drain-1 --reason "Entire refund independently returned" --evidence "Refund audit reference" --confirm
```

| Flag                    | Description                                                                                                    |
| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `--reason <text>`       | Required reason, 1–2000 characters after trimming; retained in the immutable decision                          |
| `--evidence <text>`     | Optional audit note or reference, 1–4000 characters after trimming; not verified chain proof                   |
| `--confirm`             | Submit the decision; without this flag, the CLI returns `confirmation_required` before sending an HTTP request |
| `--endpoint <url>`      | DVM admin endpoint URL, skipping the platform lookup                                                           |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints)                   |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                                        |
| `--human`               | Human-readable output instead of JSON                                                                          |

The JSON response uses `op: "credit_tempo_book"`. It includes the credit and drain IDs, original amount, decision, current balance, and current spendable balance. Replaying requires the same action, trimmed reason, and evidence. A conflicting decision is refused. The evidence text is an audit reference, not proof that the refund was paid.

***

credit tempo-release [#credit-tempo-release]

Restore the original held debit only when no refund was paid. A proven partial refund blocks release; return the remaining amount independently, then use `credit tempo-book` for the entire refund. Missing refund evidence does not establish nonpayment.

```sh
dvmctl credit tempo-release my-dvm credit-1 drain-1 --reason "No refund was paid" --confirm
```

| Flag                    | Description                                                                                                    |
| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `--reason <text>`       | Required reason, 1–2000 characters after trimming; retained in the immutable decision                          |
| `--evidence <text>`     | Optional audit note or reference, 1–4000 characters after trimming; not verified chain proof                   |
| `--confirm`             | Submit the decision; without this flag, the CLI returns `confirmation_required` before sending an HTTP request |
| `--endpoint <url>`      | DVM admin endpoint URL, skipping the platform lookup                                                           |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints)                   |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                                        |
| `--human`               | Human-readable output instead of JSON                                                                          |

The JSON response uses `op: "credit_tempo_release"`. It includes the original decision and current balances. Restored credit can remain unspendable because expiry, backing, job holds, and channel restrictions still apply. Replay requires the same action, trimmed reason, and evidence. Channel close-report retry and write-off commands do not release a caller's held refund.

***

credit tempo-reconcile [#credit-tempo-reconcile]

Book a Tempo drain whose channel close already paid on chain.

You name one thing — which drain. The DVM re-reads the `ChannelClosed` receipt the confirmed close already points at and books the drain against *that* figure, never one you supply, so this door cannot extinguish more or less than the chain returned. Any excess over the debit is the payer's uncredited channel surplus and is recorded on the drain alongside the settled amount.

If the chain refunded less than the ledger is extinguishing it refuses and names both figures. That drain is not reconcilable: the channel is closed, so nothing can top the refund up. `tempo-write-off` can close out a pending drain; an `exit_required` drain with a short refund has no repair command yet.

Running it twice books once: the second call answers `replayed: true` off the drain's own recorded state, without paying for another chain read.

```sh
dvmctl credit tempo-reconcile my-dvm imp:tempo:challenge-9 drain-7
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--endpoint <url>`      | DVM admin endpoint URL (skips the platform lookup; use for self-hosted DVMs or local dev)    |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Prose output                                                                                 |

**JSON output:**

```json
{
  "op": "credit_tempo_reconcile",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "credit_id": "imp:tempo:challenge-9",
  "drain_id": "drain-7",
  "channel_id": "0x3a1b...",
  "transaction": "0xb1c2...",
  "settled_amount": "400000",
  "amount_micro": 400000,
  "amount_native": 400000,
  "currency": "usd",
  "replayed": false,
  "display": "Booked drain drain-7 on imp:tempo:challenge-9 against the refund the channel close already paid (0xb1c2...).",
  "hint": "The reclaim is reported to the platform on the DVM's own retry loop, so its liability view catches up without another command."
}
```

**Error anchors:**

| Code                       | Trigger                                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------------ |
| `drain_conflict`           | The close refunded less than the ledger debited. The message names both figures            |
| `drain_not_found`          | No drain with that id on that credit                                                       |
| `drain_not_repairable`     | The drain isn't a Tempo cooperative close — this verb repairs those only                   |
| `drain_not_wedged`         | The drain was released, so no close is waiting to be booked                                |
| `close_not_confirmed`      | No confirmed cooperative close on this drain, so there is no receipt to book against       |
| `close_refund_unreported`  | The close reference names no transaction receipt, so the chain states no refund figure     |
| `chain_unreachable`        | The Tempo RPC could not be read — retryable, and it says nothing about what the close paid |
| `tempo_repair_unavailable` | The DVM has no durable Tempo session store                                                 |

***

credit tempo-write-off [#credit-tempo-write-off]

Record that you reviewed a wedged Tempo close and are not booking it.

Books nothing anywhere. The close paid the caller less than this ledger extinguished, and no dvmkit row can express that difference: the channel is closed, so there is nothing left to refund through it, and re-crediting the balance here would pay the caller twice for the part the chain *did* return. Making the shortfall good is an out-of-band decision — this verb records that you took it, so the row leaves the queue without pretending it booked.

Reversing it is `tempo-reconcile`, and a reconcile that then refuses leaves the write-off exactly as it found it — note, timestamp and all — so a drain never sits in the queue advertising a decision that was undone.

```sh
dvmctl credit tempo-write-off my-dvm imp:tempo:challenge-9 drain-7 --note "chain refunded 390000 of 400000; made good by transfer 0x…"
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--note <text>`         | Why you are not booking it. Recorded on the drain row                                        |
| `--endpoint <url>`      | DVM admin endpoint URL (skips the platform lookup; use for self-hosted DVMs or local dev)    |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Prose output                                                                                 |

**JSON output:**

```json
{
  "op": "credit_tempo_write_off",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "credit_id": "imp:tempo:challenge-9",
  "drain_id": "drain-7",
  "channel_id": "0x3a1b...",
  "amount_micro": 400000,
  "amount_native": 400000,
  "currency": "usd",
  "note": "chain refunded 390000 of 400000; made good by transfer 0x…",
  "replayed": false,
  "display": "Closed this drain without booking it. No ledger row moved: the caller keeps the on-chain refund the close paid them, and the shortfall against what was extinguished is not expressible here — make it good out of band if you owe it.",
  "hint": "Reversible: `dvmctl credit tempo-reconcile` still accepts a written-off drain if you change your mind."
}
```

`replayed: true` means it was already written off and this call changed nothing — including the note, which stays whatever the first write-off recorded.

**Error anchors:**

| Code                   | Trigger                                                                                                                                                   |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `drain_not_found`      | No drain with that id on that credit                                                                                                                      |
| `drain_not_repairable` | The drain isn't a Tempo cooperative close                                                                                                                 |
| `drain_not_wedged`     | The drain was released, or already booked as sent — either way there is nothing to decide about, and a write-off on a close that paid would say it didn't |

***

credit tempo-close-reports [#credit-tempo-close-reports]

List hosted Tempo close-report obligations: records that track whether the builder's payout report can be sent after a channel closes. Requires hosted settlement reports on the target DVM with `@dvmkit/sdk` 0.10.0 or later. These commands use the same signed admin authentication as the Tempo drain commands.

The default action queue contains owned, unsubmitted `unmatched` rows with an available action. `--all` also shows terminal `no_report` rows, including retired attempts, resolved payer exits, completed write-offs, submitted rows, and rows without an available action. It does not list every report state. `retryable` and `write_off_allowed` are server snapshots; a concurrent change can still refuse an action.

```sh
dvmctl credit tempo-close-reports my-dvm
dvmctl credit tempo-close-reports my-dvm --all --limit 50 --human
dvmctl credit tempo-close-reports my-dvm --all --after <next_after>
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--limit <n>`           | Page size (default: 20, max 50)                                                              |
| `--after <cursor>`      | Continue from `next_after`, keeping the same `--all` setting                                 |
| `--all`                 | Audit view, including terminal `no_report` rows and rows without available actions           |
| `--endpoint <url>`      | DVM admin endpoint URL, skipping the platform lookup                                         |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Human-readable output instead of JSON                                                        |

Each row's `amount_native` is a decimal string in native token units, preserved without floating-point conversion. It is the reserved highest voucher less the amount already settled: the builder payout at stake. Timestamps ending in `_ms` are Unix milliseconds. `delivered_at_ms` is nullable and does not prove delivery of a terminal report. `written_off` records a retained decision and can remain true after an explicit retry; `write_off_note` and `written_off_at_ms` retain its details. Human output shows the amount, unit, action flags, and write-off details. `next_after` is omitted on a page shorter than the limit.

**JSON output:**

```json
{
  "op": "credit_tempo_close_reports",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "reports": [
    {
      "obligation_id": "close-test",
      "channel_id": "0x1234",
      "amount_native": "9007199254740993",
      "status": "unmatched",
      "created_at_ms": 1755200000000,
      "updated_at_ms": 1755200001000,
      "delivered_at_ms": null,
      "retryable": true,
      "write_off_allowed": true,
      "written_off": false,
      "write_off_note": null,
      "written_off_at_ms": null
    }
  ],
  "report_count": 1,
  "amount_unit": "native token units",
  "display": "1 Tempo close report(s). Each amount is a potential builder payout in native token units.",
  "hint": "Retry reopens the search for the close so the builder's payout report can still be sent. Write-off permanently gives up that payout report if the close lands later; it does not refund the caller."
}
```

HTTP: `GET /admin/credit/tempo-close-reports?limit=20`; `--all` sends `all=1`, and `--after` sends the opaque `after` cursor. Invalid queries return HTTP 400 `invalid_query`.

***

credit tempo-close-report-retry [#credit-tempo-close-report-retry]

Reopen the search for a close so the builder's payout report can still be sent. Restore complete chain history before retrying. The next sweep searches again without broadcasting or changing the caller's drain. Success means the search was reopened, not that the payout report was delivered.

```sh
dvmctl credit tempo-close-report-retry my-dvm close-test
dvmctl credit tempo-close-report-retry my-dvm close-test --human
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--endpoint <url>`      | DVM admin endpoint URL, skipping the platform lookup                                         |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Human-readable output instead of JSON                                                        |

Accepts only unsubmitted `unmatched` or `no_report` obligations with no competing report for that channel. A reserved, observed, delivered, or otherwise unresolved successor can block retry. Another unsubmitted `no_report` row does not compete. The server clears the durable search cursor and returns `status: "reserved"`.

The CLI reads at most five audit pages of 50 rows to find the amount before retrying, preserving its decimal string. This is a snapshot, not an eligibility check. If the amount is not found within those pages, or a row becomes eligible only after that read, retry still proceeds and can succeed with `amount_native: null` and an unavailable-amount message. Inspect the retained service report evidence for its amount.

**JSON output:**

```json
{
  "op": "credit_tempo_close_report_retry",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "status": "reserved",
  "obligation_id": "close-test",
  "amount_native": "9007199254740993",
  "amount_unit": "native token units",
  "display": "Reopened the search for close close-test (9007199254740993 native token units) so the builder's payout report can still be sent.",
  "hint": "The next service sweep searches again without broadcasting or changing the caller's drain. Check service events for delivery; the report has not been sent by this command."
}
```

HTTP: `POST /admin/credit/retry-tempo-close-report` with `{ "obligation_id": "close-test" }`. The server response contains only `status` and `obligation_id`; the CLI adds the pre-retry amount and output envelope.

***

credit tempo-close-report-write-off [#credit-tempo-close-report-write-off]

Permanently give up the builder's payout report if the missing close lands later. Only an unsubmitted `unmatched` report can be written off. This discharges that report's cleanup blocker; it never moves caller money, releases caller refund liabilities, or declares a refund paid. The exact abandoned builder payout is printed as `amount_forgone_native` in native token units.

If history becomes recoverable, an explicit `tempo-close-report-retry` can reopen the written-off row **before** a late close lands. A close that lands while written off will not have its payout reported. Do not use write-off as a routine retry or cleanup operation.

```sh
dvmctl credit tempo-close-report-write-off my-dvm close-test --note "History unavailable"
dvmctl credit tempo-close-report-write-off my-dvm close-test --note "History unavailable" --human
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--note <text>`         | Required reason, 1–2000 characters after trimming; retained on the report                    |
| `--endpoint <url>`      | DVM admin endpoint URL, skipping the platform lookup                                         |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Human-readable output instead of JSON                                                        |

Like the existing `credit` write-off commands, this command has no interactive confirmation prompt. Running it authorizes the write-off; review the payout amount and action flags with `tempo-close-reports` first. A repeat write-off returns a conflict rather than replaying success.

**JSON output:**

```json
{
  "op": "credit_tempo_close_report_write_off",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "status": "written_off",
  "obligation_id": "close-test",
  "channel_id": "0x1234",
  "amount_forgone_native": "9007199254740993",
  "note": "History unavailable",
  "amount_unit": "native token units",
  "display": "Wrote off close-test: 9007199254740993 native token units forgone. This permanently gives up the builder's payout report if the close lands later.",
  "hint": "No caller funds moved or refund liability was discharged. If recovery becomes possible, explicitly retry before the close lands; a payout from a close that lands while written off will not be reported."
}
```

HTTP: `POST /admin/credit/write-off-tempo-close-report` with `{ "obligation_id": "close-test", "note": "History unavailable" }`. Both action routes trim the obligation ID before lookup and response.

**Error anchors for all three close-report commands:**

| Code                             | Trigger and next step                                                                                                                                                           |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tempo_close_report_conflict`    | HTTP 409: the server refused the transition, including repeat write-offs. Read its reason, then inspect `tempo-close-reports --all` and the action flags before deciding again. |
| `not_found`                      | HTTP 404: this DVM does not serve the close-report routes. Upgrade the DVM to `@dvmkit/sdk` 0.10.0 or later, then retry.                                                        |
| `tempo_close_report_not_found`   | HTTP 404: missing obligation, another deployment's obligation, or another operation. Check the target DVM and the ID in `tempo-close-reports --all`.                            |
| `tempo_close_report_unavailable` | HTTP 503: hosted settlement reports are not configured. Configure them on a DVM using SDK 0.10.0 or later, then retry.                                                          |
| `invalid_request`                | HTTP 400: malformed JSON, ID, or note. Correct the request; the CLI trims IDs and validates notes locally.                                                                      |
| `invalid_query`                  | HTTP 400: invalid page query. Use the documented page size, cursor, and audit flag.                                                                                             |
| `invalid_limit`                  | Local page size outside 1..50. Use a valid limit and follow `next_after`.                                                                                                       |
| `invalid_note`                   | Local missing, empty, or oversized note. Supply 1–2000 characters after trimming.                                                                                               |
| `invalid_obligation_id`          | Local empty ID. Copy the ID from the list command.                                                                                                                              |
| `admin_bad_signature`            | HTTP 401 with `bad_signature`: the builder identity does not match the DVM's lock key. Restore the correct builder identity before retrying.                                    |

Other authentication refusals retain HTTP 401. Refused actions print no success output and include the server's reason and a next step.

***

credit liability [#credit-liability]

Show the satoshis your DVMs owe callers, and how much of your hub balance is earnings you can sweep.

Prepaid Bitcoin credit is a deposit. The caller can ask for it back at any moment, and what they get back is the Bitcoin they sent, pro rata to the share they never spent, rather than a dollar figure converted at whatever the rate is on the day. So your hub holds two pots in one balance: deposits, which are theirs, and earnings, which are yours. The sweep rule is to bank the second and never the first, and this command is that number.

Every figure comes off the funding lots each deposit recorded, at the rate that funding actually landed at. Nothing here reads an exchange rate, because nothing about the obligation depends on one.

Name every DVM your hub backs. One hub normally serves several, and a sweep netted against a single DVM's floor is wrong by all the others. Pass `--hub-sats` with your hub's spendable balance to get the sweepable figure directly instead of subtracting by hand.

Read-only.

```sh
dvmctl credit liability scrape cast scribe narrate
dvmctl credit liability scrape --hub-sats 250000 --human
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--hub-sats <sats>`     | Your hub's spendable balance, in sats. Supply it to get the sweepable figure directly        |
| `--endpoint <url>`      | DVM admin endpoint URL (skips the platform lookup; use for self-hosted DVMs or local dev)    |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Prose output                                                                                 |

**JSON output:**

```json
{
  "op": "credit_liability",
  "handles": ["scrape"],
  "dvms": [
    {
      "handle": "scrape",
      "dvm_id": "550e8400-e29b-41d4-a716-446655440000",
      "deposit_liability_sats": 1142,
      "deposit_credits": 1,
      "deposit_by_rail": [{ "rail": "lightning", "sats": 1142, "credits": 1 }],
      "deposit_by_currency": [{ "currency": "usd", "micro": 1142000, "credits": 1 }],
      "drain_liability_sats": 400,
      "drain_count": 1,
      "total_owed_sats": 1542,
      "uncovered_credits": 0,
      "uncovered_micro": 0,
      "unbacked_credits": 0,
      "unbacked_micro": 0,
      "unpriced_drains": 0
    }
  ],
  "deposit_liability_sats": 1142,
  "drain_liability_sats": 400,
  "total_owed_sats": 1542,
  "hub_sats": 250000,
  "sweepable_sats": 248458,
  "solvent": true,
  "display": "Callers are owed 1542 sats across 1 DVM(s): 1142 sats of prepaid balance nobody has drawn yet, and 400 sats already promised to reclaims in flight. The hub holds 250000 sats, so 248458 sats of it are earnings and the rest has to stay put.",
  "hint": "Sweep no more than `sweepable_sats`. These are satoshis the DVMs owe back as satoshis, so the figure does not move with the exchange rate."
}
```

`deposit_liability_sats` is undrawn prepaid balance: money with no reclaim registered against it yet, which is exactly the liability a payout sweep used to be blind to. `drain_liability_sats` is what a registered reclaim has already promised. Their sum is `total_owed_sats`, the floor your hub may never be banked below.

A hub below that floor is an operational error to repair, not a routine state: `solvent` says so and `sweepable_sats` goes negative rather than clamping to zero. Nothing gates on it. Funding rails stay advertised whatever your treasury is doing, because a rail that appears and disappears with internal state is worse product than one that is honestly absent.

Two counts describe balance the sats figures cannot speak for, published rather than folded into the totals. `unbacked_credits` is credit funded before dvmkit recorded a rail basis, whose reclaim still prices off a live rate. `uncovered_credits` is balance with no funding lot behind it at all, which is a defect: the DVM logs `credit_funding_lot_backfill` at boot and repairs it there, so a count that is not falling is worth investigating. When either is non-zero a `gap_note` field says how much ledger value is involved, so you can leave headroom for it.

**Error anchors:**

| Code                  | Trigger                                                                |
| --------------------- | ---------------------------------------------------------------------- |
| `invalid_hub_balance` | `--hub-sats` was not a whole number of satoshis                        |
| `admin_bad_signature` | The DVM's lock pubkey doesn't match the key derived from this mnemonic |
| `admin_unreachable`   | The DVM's admin endpoint didn't answer                                 |
| `dvm_url_unset`       | No platform URL for this handle yet, so pass `--endpoint`              |

***

credit drains-owed [#credit-drains-owed]

List the stablecoin refunds your DVM owes callers that nothing will ever pay on its own — the queue behind every `drain_manual_settlement_required` log line.

These are one-payment reclaims: a credit funded by a single x402 `exact` authorization or a Tempo charge. The caller named a payout address, the DVM debited their balance and countersigned the request, and the money is owed from that moment — but there is no builder-held on-chain send key anywhere in dvmkit, so nothing sends it.

A channel-backed refund never appears here, even on the same rail. Its own cooperative close settles it, and one sitting `pending` is usually that close still reconciling — the DVM classifies it `settlement: "channel"` and names the channel on the row, so listing it would send you to pay a refund the channel is about to pay itself.

That stays a person's job by decision rather than by omission. Automating the send means a chain spending key live on your `melt-pending` host with your whole stablecoin balance behind it.

Read-only, and every figure comes off the drain row: `amount_micro` is what the caller was debited in your ledger's currency, `amount_native` is the same debit in the payout token's own units — that second one is what you send. These rows deliberately carry no sats figure, because nothing here prices or pays them.

```sh
dvmctl credit drains-owed my-dvm
dvmctl credit drains-owed my-dvm --human
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--endpoint <url>`      | DVM admin endpoint URL (skips the platform lookup; use for self-hosted DVMs or local dev)    |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Prose output                                                                                 |

**JSON output:**

```json
{
  "op": "credit_drains_owed",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "drains": [
    {
      "credit_id": "imp:x402:0xabc...",
      "drain_id": "drain-7",
      "method": "x402",
      "payout": { "address": "0x1234567890abcdef1234567890abcdef12345678" },
      "currency": "usd",
      "amount_micro": 400000,
      "amount_sats": null,
      "amount_msats": null,
      "sats_basis": null,
      "amount_native": 400000,
      "settlement": "manual",
      "channel_id": null,
      "created_at": 1754000000000,
      "age_ms": 7200000
    }
  ],
  "owed_count": 1,
  "owed_totals": [{ "currency": "usd", "amount_micro": 400000, "count": 1 }],
  "display": "1 stablecoin refund(s) are owed to callers and no job will pay them: 0.400000 USD. Each one was debited from the caller's balance already, so the money is owed whether or not it is sent.",
  "hint": "Send each payout on its own rail (`method` names it, `payout.address` is the destination, `amount_native` is the figure in the token's own units), then record it with `dvmctl credit drain-settle <handle> <credit-id> <drain-id> --tx <hash>`."
}
```

Rows come oldest first — a refund's age is the reason to act on it. `owed_totals` groups by currency rather than summing to one number, because the admin read is host-wide and a multi-mount host can hold credits in two denominations. `amount_native` is `null` only on a credit that records no rail basis, where the fiat figure is all the ledger knows.

**Error anchors:**

| Code                  | Trigger                                                                |
| --------------------- | ---------------------------------------------------------------------- |
| `admin_bad_signature` | The DVM's lock pubkey doesn't match the key derived from this mnemonic |
| `admin_unreachable`   | The DVM's admin endpoint didn't answer                                 |
| `dvm_url_unset`       | No platform URL for this handle yet — pass `--endpoint`                |

***

credit drain-settle [#credit-drain-settle]

Record that you settled an owed stablecoin refund on chain. **Idempotent** — running it twice records once.

Moves no money. The payout happened in your own wallet; this is the ledger catching up with it. The drain flips `pending → sent`, the caller's next reclaim poll sees it settled with a countersigned receipt, and the reclaim is reported to the platform inside the same transaction as the transition — so its outstanding-liability view stops counting a debt you have paid, exactly once however many times you run this.

Both ids are named because `(credit-id, drain-id)` is the ledger's key and the drain id is chosen by the caller, so it is not unique on its own. `dvmctl credit drains-owed` prints the pair side by side.

`--tx` is required: it is the only evidence this row will ever carry, and no shape is enforced on it because an x402 payout settles on Base and a Tempo one does not — refusing an unfamiliar hash would refuse a real settlement.

```sh
dvmctl credit drains-owed my-dvm
dvmctl credit drain-settle my-dvm imp:x402:0xabc... drain-7 --tx 0xfeed... --note "sent from ops wallet"
```

| Flag                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `--tx <hash>`           | On-chain transaction that paid the refund (required)                                         |
| `--note <text>`         | Recorded alongside the transaction, e.g. which wallet sent it                                |
| `--endpoint <url>`      | DVM admin endpoint URL (skips the platform lookup; use for self-hosted DVMs or local dev)    |
| `--mount-prefix <path>` | DVM mount path, such as `/feed` (no trailing slash); see [Admin endpoints](#admin-endpoints) |
| `--org <handle>`        | Target this org, overriding the `dvmctl switch` context                                      |
| `--human`               | Prose output                                                                                 |

**JSON output:**

```json
{
  "op": "credit_drain_settle",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "credit_id": "imp:x402:0xabc...",
  "drain_id": "drain-7",
  "transaction": "0xfeed...",
  "replayed": false,
  "display": "Recorded the payout for drain drain-7 on imp:x402:0xabc.... The caller's next reclaim poll sees it settled, with a countersigned receipt.",
  "hint": "The reclaim is reported to the platform inside the same transaction as this transition, so its liability view catches up without another command — and exactly once, however many times this runs."
}
```

`replayed: true` means the drain was already recorded as sent and this call changed nothing, including the settlement reference — which stays whatever was recorded first. On a payout you believe you just made, read that as "check the transaction on file before sending another": it may already have been paid.

**Error anchors:**

| Code                  | Trigger                                                                                                                                                                                               |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `missing_transaction` | No `--tx` given                                                                                                                                                                                       |
| `drain_not_found`     | No drain with that id on that credit                                                                                                                                                                  |
| `drain_conflict`      | The drain is `parked` or `picked_up` — a cashu refund, which `melt-pending` settles                                                                                                                   |
| `channel_bound_drain` | The reclaim settles through a payment channel, not by hand — its cooperative close owns the transition, and recording it here would take the row out of the reconciliation that would have settled it |
| `invalid_drain_state` | The drain is not `pending` (already released, or a cashu row still awaiting its park)                                                                                                                 |
| `admin_bad_signature` | The DVM's lock pubkey doesn't match the key derived from this mnemonic                                                                                                                                |
| `dvm_url_unset`       | No platform URL for this handle yet — pass `--endpoint`                                                                                                                                               |

***

set-payout [#set-payout]

Persist the default Lightning payout address for a DVM. `dvmctl melt-pending` reads this when no `--payout` flag is supplied. Pre-flights the LNURL-pay metadata endpoint by default to catch typos.

```sh
dvmctl set-payout my-dvm builder@example.com
dvmctl set-payout my-dvm builder@example.com --skip-preflight
dvmctl set-payout my-dvm builder@example.com --self-hosted
```

| Flag               | Description                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------ |
| `--skip-preflight` | Skip the LNURL pre-flight check (use when the provider is temporarily down)                |
| `--self-hosted`    | Target local state created by `dvmctl init --self-hosted`; cannot be combined with `--org` |
| `--org <handle>`   | Target this org, overriding the `dvmctl switch` context                                    |
| `--human`          | Prose output                                                                               |

**JSON output:**

```json
{
  "status": "set",
  "handle": "my-dvm",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "payout_ln_address": "builder@example.com"
}
```

**Error anchors:**

| Code                  | Trigger                                 |
| --------------------- | --------------------------------------- |
| `dvm_not_initialized` | No `builder.json` entry for this handle |

***

feedback send [#feedback-send]

Send a note to the dvmkit team. This command submits the message; an invitation from another command does not send anything by itself. Keep credentials, source files, and environment values out of the message.

```sh
dvmctl feedback send "The deploy failed after the image upload" --trace <trace-id>
dvmctl feedback send --body @feedback.txt --org my-org
printf 'The setup step was unclear' | dvmctl feedback send --body @-
```

| Flag                       | Description                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------ |
| `--body <text\|@path\|@->` | Read the message from text, a file, or standard input instead of the positional text |
| `--trace <id>`             | Attach a related platform trace ID                                                   |
| `--org <handle>`           | Send in this org context, overriding `dvmctl switch`                                 |
| `--human`                  | Prose output                                                                         |

Messages must be 1–4,096 UTF-8 bytes. A builder can send 20 messages in a rolling 24-hour window across all orgs; the `rate_limited` error says when to retry. The platform keeps these notes for its operators. They do not appear in a DVM's caller-feedback list.

The CLI adds bounded context when it can verify it: its version, the installed SDK version in a DVM project, the operating system, the Node version, and a related DVM ID. After a feedback invitation it may also add the command, error code, and invitation trigger. It does not attach your project files or environment values. Check the text you write before sending.

**JSON output:**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-09-29T12:00:00.000Z",
  "display": "Sent to the dvmkit team.",
  "hint": "Feedback was sent to the dvmkit team."
}
```

**Error anchors:** `feedback_body_required` for a missing message, `feedback_body_conflict` for both positional text and `--body`, `feedback_body_invalid` for an empty or oversized message, and `rate_limited` after 20 submissions in 24 hours.

***

feedback posture [#feedback-posture]

Show or set how your agent should handle feedback invitations. The default is `ask`: the agent proposes a note and gets your agreement before it runs [`feedback send`](#feedback-send). `auto` tells the agent it may send its own short note without asking. Neither setting makes `dvmctl` submit feedback automatically. `off` hides invitations; you can still send a note explicitly.

```sh
dvmctl feedback posture
dvmctl feedback posture off
dvmctl feedback posture ask
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

**JSON output:**

```json
{ "posture": "ask", "source": "default", "display": "Feedback posture: ask (default)." }
```

The CLI may invite feedback after a failed platform command, the first deploy of a DVM, or a check-in after 14 days. It limits failure invitations to one per 24 hours, first-deploy invitations to one per DVM, and check-ins to one per 14 days. A 24-hour cooldown also prevents a check-in soon after another invitation. CI runs show no invitations.

***

feedback list [#feedback-list]

List caller-submitted feedback for a DVM in your current org context, newest-first. Cursor-paginated.

```sh
dvmctl feedback list my-dvm
dvmctl feedback list my-dvm --since 7d --limit 100
dvmctl feedback list my-dvm --cursor <next_cursor>
dvmctl feedback list my-dvm --org my-org
```

| Flag                   | Description                                              |
| ---------------------- | -------------------------------------------------------- |
| `--org <handle>`       | Read as this org, overriding the `dvmctl switch` context |
| `--verdict <up\|down>` | Filter by job verdict                                    |
| `--since <duration>`   | Look-back window (`24h`, `7d`, or ISO 8601 timestamp)    |
| `--cursor <c>`         | Opaque cursor from a prior page's `next_cursor`          |
| `--limit <n>`          | Max rows per page (1–100, default 50)                    |
| `--human`              | Prose output                                             |

**JSON output:**

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "feedback": [
    {
      "id": "b41e7a52-9d38-4f6b-a0c7-2e58d3f1c964",
      "dvm_id": "dvm-my-dvm",
      "slug": "my-dvm",
      "owner_handle": "my-org",
      "job_id": null,
      "trace_id": null,
      "caller_pubkey": "9b01215ba08abbd9c3048ea7bf233776043369dbd4b45abc6627c03111c85c0e",
      "body": "Search ranks recency too low",
      "created_at": "2026-05-27T12:00:00.000Z"
    }
  ],
  "next_cursor": null,
  "org": {
    "id": "acffd753-105a-4958-9f37-243ac032f332",
    "handle": "my-org",
    "role": "admin",
    "personal": false
  }
}
```

`verdict` is `up`, `down`, or `null` for note-only feedback. `tier` is `receipt_verified`, `claimed` (router claim without a receipt), or `null` for non-job notes. Accepted feedback and its revisions, including text, trace links and necessary attribution/proof, have no age-only purge. Personal-field purpose is reviewed annually. The platform response includes `submission_id` for the current revision and `is_current_ranking_vote` for the latest eligible vote. Restriction hides the affected contribution from these reads; erasure or permanent service removal deletes its proof.

`caller_pubkey` is the x-only BIP-340 key from the caller's signed-request envelope (64 hex chars). Age alone does not clear this key or delete the row. `job_id`/`trace_id` are populated when the caller anchored their feedback to a specific job or trace, else `null`. Page forward by passing the returned `next_cursor` back via `--cursor`; `next_cursor` is `null` on the last page. `org` is the context the page was read from — see [`list`](#list).

***

Ordinary claimed job feedback returns `feedback_expired` after its 90-day collection limit while its retained record remains. Receipt-backed verdicts have no age-only collection limit. To change an existing verified verdict, the caller must include its stored original signed receipt. A claimed-only replacement returns `receipt_required` (409). A text-only edit leaves the verified verdict and proof unchanged.

feedback enable [#feedback-enable]

`--org <handle>` selects the owning org for this one command.

Enable free-text feedback notes for one of your DVMs (default on creation). When enabled, callers can submit `dvm feedback --dvm <dvm-id>` rows; the platform stores them against your DVM for `dvmctl feedback list`.

```sh
dvmctl feedback enable my-dvm
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

**JSON output:**

```json
{ "dvm_id": "dvm-my-dvm", "dvmId": "550e8400-e29b-41d4-a716-446655440000", "slug": "my-dvm", "settings": { "feedback_enabled": true } }
```

***

feedback disable [#feedback-disable]

`--org <handle>` selects the owning org for this one command.

Disable free-text feedback notes for one of your DVMs. Note-only submissions get a `feedback_disabled` error. Job verdicts remain enabled in both eligibility tiers; the platform records the verdict and drops its note.

```sh
dvmctl feedback disable my-dvm
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

**JSON output:**

```json
{ "dvm_id": "dvm-my-dvm", "dvmId": "550e8400-e29b-41d4-a716-446655440000", "slug": "my-dvm", "settings": { "feedback_enabled": false } }
```

***

trace get [#trace-get]

Fetch a forensic trace by ID. Traces capture cross-component spans (router → platform → SDK → payment rail) for a single request; useful when reconstructing a money-flow incident or debugging a specific job.

```sh
dvmctl trace get 4bf92f3577b34da6a3ce929d0e0e4736
dvmctl trace get 4bf92f3577b34da6a3ce929d0e0e4736 --human
dvmctl trace get 4bf92f3577b34da6a3ce929d0e0e4736 --human --no-color
```

| Flag             | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `--org <handle>` | Read as this org, overriding the `dvmctl switch` context |
| `--human`        | Render as a waterfall instead of JSON                    |
| `--no-color`     | Disable ANSI colors in human output                      |

Only isolate-dataset spans are visible, and only for DVMs in your current org context. Default JSON output is the raw span list; `--human` is the waterfall you'd read at a glance during an incident. A miss names the scope it searched (`No trace <id> in org "my-org"`), so a bad trace ID reads differently from the right ID under the wrong org.

**JSON output:**

```json
{
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": "ok",
  "duration_ms": 842,
  "started_at_ms": 1747785600000,
  "ended_at_ms": 1747785600842,
  "dimensions": { "dvm_id": "4bf92f3577b34da6a3ce929d0e0e4736", "dvm_slug": "my-dvm" },
  "span_count": 1,
  "truncated": false,
  "spans": [
    {
      "span_id": "00f067aa0ba902b7",
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "parent_span_id": null,
      "name": "POST /v1/job",
      "dataset": "isolate",
      "level": "info",
      "status": "ok",
      "started_at_ms": 1747785600000,
      "ended_at_ms": 1747785600842,
      "duration_ms": 842,
      "service": "dvmkit-platform",
      "service_version": "0.1.0",
      "host": "dvmkit-3f2b1c88-5a4d-4e6f-9b0a-7c1d2e3f4a5b",
      "dimensions": { "dvm_id": "4bf92f3577b34da6a3ce929d0e0e4736", "dvm_slug": "my-dvm" },
      "attributes": { "http.status_code": 200 },
      "error_message": null,
      "error_stack": null
    }
  ]
}
```

A trace whose spans were capped adds `truncation_hint` (a string) alongside `truncated: true`; it is absent otherwise. This is the one payload that carries its own `trace_id` rather than the injected one.

***

db connect [#db-connect]

`--org <handle>` selects the owning org for this one command.

Open an interactive `psql` session against a DVM's per-DVM Postgres. Requires local `psql` on `PATH`. The platform brokers credentials through a chosen running machine — pass `--machine` to target a specific one.

```sh
dvmctl db connect my-dvm
dvmctl db connect my-dvm --machine 1234abcd
```

| Flag             | Description                                                            |
| ---------------- | ---------------------------------------------------------------------- |
| `--machine <id>` | Broker through a specific Fly machine (default: first running machine) |
| `--human`        | Print connection status to stderr while `psql` runs                    |

No JSON output — relays the interactive `psql` session to your terminal and exits with `psql`'s exit code.

**Error anchors:**

| Code                 | Trigger                                      |
| -------------------- | -------------------------------------------- |
| `psql_not_found`     | `psql` not installed locally                 |
| `no_running_machine` | DVM has no running machine to broker through |

***

db proxy [#db-proxy]

`--org <handle>` selects the owning org for this one command.

Bind a **local TCP port** to a DVM's per-DVM Postgres and hold it open until Ctrl-C, so any Postgres client can connect — `pg_dump`, drizzle-kit, Prisma, TablePlus, pgAdmin. Unlike [`db connect`](#db-connect) it needs no local `psql`, and unlike `fly proxy` it needs no Fly credential: the platform brokers the tunnel and enforces the same ownership gate.

```sh
dvmctl db proxy my-dvm
dvmctl db proxy my-dvm --port 15433
dvmctl db proxy my-dvm --human
```

| Flag             | Description                                                            |
| ---------------- | ---------------------------------------------------------------------- |
| `--port <n>`     | Local port to bind (default: an OS-assigned free port)                 |
| `--machine <id>` | Broker through a specific Fly machine (default: first running machine) |
| `--human`        | Human-readable output instead of JSON                                  |

**JSON output** (one line, then the command blocks until interrupted):

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "host": "127.0.0.1",
  "port": 15433,
  "user": "postgres",
  "database": "my_dvm",
  "database_url": "postgres://postgres:pw@127.0.0.1:15433/my_dvm?sslmode=disable",
  "display": "Postgres proxy for my-dvm listening on 127.0.0.1:15433.",
  "hint": "Point any Postgres client at database_url (psql, pg_dump, drizzle-kit, a GUI client). The proxy stays up until it is interrupted."
}
```

Then, from another shell:

```sh
pg_dump "postgres://postgres:pw@127.0.0.1:15433/my_dvm?sslmode=disable" > backup.sql
```

`sslmode=disable` is required and already present in `database_url`: the hop to your loopback port is plaintext, while the leg to the platform is the encrypted WebSocket. In JSON output the password appears only inside `database_url` — never as its own field, and never in a log line or span. (`--human` does print it as a labelled field, since GUI clients ask for the parts separately.)

If a client connection can't get a tunnel, the proxy stays up and reports it on stderr rather than dying — `{"event":"connection_error","code":"…","message":"…"}` in JSON mode, a `Connection failed:` line under `--human`.

Two consequences of the platform relaying **one Postgres connection per tunnel**:

* **Every client connection opens its own tunnel**, so concurrent clients (a GUI opening a pool) work — but each new connection pays one platform round-trip before the Postgres handshake begins.
* **A tunnel is reaped after 60 minutes.** A long-lived pooled client will see that connection dropped and must reconnect; a fresh connection gets a fresh hour.

**Error anchors:**

| Code                    | Trigger                                                    |
| ----------------------- | ---------------------------------------------------------- |
| `invalid_port`          | `--port` is not an integer in 1–65535                      |
| `local_listener_failed` | The local port is already in use (or otherwise unbindable) |
| `no_running_machine`    | DVM has no running machine to broker through               |
| `db_not_provisioned`    | DVM has no managed Postgres                                |
| `not_found`             | Unknown slug, or you don't own the DVM                     |

***

secrets list [#secrets-list]

`--org <handle>` selects the owning org for this one command.

List secret names and last-applied timestamps for a DVM. Never returns values; platform-injected keys are excluded.

```sh
dvmctl secrets list cast
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

**JSON output:**

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "cast",
  "secrets": [
    {
      "name": "SPOTIFY_CLIENT_ID",
      "last_applied_at": "2026-05-10T09:12:00Z",
      "digest_hash": "31160254d1297393d2ad00e1c01851aec834361e02c524b89fe06aff2879ce6a"
    }
  ]
}
```

`digest_hash` is the opaque digest the host reports for the secret, never the value itself — compare it across DVMs to tell whether they share a secret, but don't parse it (the format is the host's, not ours).

***

transfer [#transfer]

`--org <handle>` selects the source org for this one command.

Transfer ownership of a DVM to an org (by handle) or back to personal. The new owner picks up the DVM's revenue ledger, payment-rail config, and `dvmctl env` access from this point forward.

```sh
dvmctl transfer my-dvm acme                     # transfer to existing org "acme"
dvmctl transfer my-dvm acme --create-org \
  --display-name "Acme Inc"                     # create the org first, then transfer
dvmctl transfer my-dvm personal                 # transfer back to personal ownership
```

| Flag                    | Description                                                                 |
| ----------------------- | --------------------------------------------------------------------------- |
| `--create-org`          | Create the target org if it doesn't exist (`to` becomes the desired handle) |
| `--display-name <name>` | Display name for the new org (with `--create-org`)                          |
| `--human`               | Prose output                                                                |

**JSON output:**

```json
{
  "status": "transferred",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "to": "acme",
  "org": { "id": "acffd753-105a-4958-9f37-243ac032f332", "handle": "acme" },
  "treasuryRekeyPending": true
}
```

`org` is present when transferring to an org (omitted when transferring back to `personal`). `treasuryRekeyPending` is `true` when the DVM's Cashu treasury must be re-keyed to the new owner before payouts resume.

***

revenue summary [#revenue-summary]

Show revenue totals and a by-rail breakdown for a date range, for your current org context.

```sh
dvmctl revenue summary --from 2026-05-01 --to 2026-05-27
dvmctl revenue summary --from 2026-05-01 --to 2026-05-27 --currency eur
dvmctl revenue summary --from 2026-05-01 --to 2026-05-27 --org my-org
```

| Flag             | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `--org <handle>` | Read as this org, overriding the `dvmctl switch` context |
| `--from <date>`  | Start date (`YYYY-MM-DD`, required)                      |
| `--to <date>`    | End date (`YYYY-MM-DD`, required)                        |
| `--currency <c>` | Reporting currency (`gbp`, `eur`, `usd`, `chf`)          |
| `--human`        | Prose output                                             |

**JSON output:**

```json
{
  "summary": {
    "fiat_currency": "usd",
    "period": { "from": "2026-05-01", "to": "2026-05-27" },
    "by_source_type_rail": [
      { "source_type": "job", "rail": "cashu", "gross_fiat_minor": 8010, "count": 240 },
      { "source_type": "job", "rail": "lightning", "gross_fiat_minor": 4122, "count": 95 }
    ],
    "total_gross_fiat_minor": 14237,
    "total_count": 372
  },
  "series": {
    "monthly_by_rail": [],
    "monthly_by_source_type": [],
    "cumulative_net_by_date": []
  },
  "stale_fx_warnings": [],
  "org": {
    "id": "acffd753-105a-4958-9f37-243ac032f332",
    "handle": "my-org",
    "role": "admin",
    "personal": false
  }
}
```

Aggregates need `member` role in a shared org; the raw [`revenue events`](#revenue-events) and [`revenue csv`](#revenue-csv) exports need `admin`. All amounts are integer minor units (`gross_fiat_minor: 14237` = $142.37). Revenue is bucketed by `source_type` + `rail` tuples, not a fixed rail map. `stale_fx_warnings` lists any FX conversions that used a stale rate, and `summary.cross_rate_note` — a string, **absent** from the payload rather than `null` when it doesn't apply — appears only when an amount had to be derived through a cross rate. The `series` arrays back the dashboard charts.

***

revenue events [#revenue-events]

List individual revenue events for your current org context, optionally filtered by rail and date range. Requires `admin` role in a shared org.

```sh
dvmctl revenue events
dvmctl revenue events --from 2026-05-01 --to 2026-05-27 --rail cashu --limit 100
dvmctl revenue events --org my-org
```

| Flag             | Description                                                    |
| ---------------- | -------------------------------------------------------------- |
| `--org <handle>` | Read as this org, overriding the `dvmctl switch` context       |
| `--from <date>`  | Start date (`YYYY-MM-DD`)                                      |
| `--to <date>`    | End date (`YYYY-MM-DD`)                                        |
| `--rail <r>`     | Filter by payment rail (`cashu`, `lightning`, `tempo`, `x402`) |
| `--limit <n>`    | Max events to return (default 50)                              |
| `--human`        | Prose output                                                   |

**JSON output:**

```json
{
  "events": [
    {
      "date": "2026-05-15",
      "source_type": "job",
      "rail": "cashu",
      "dvm_slug": "my-dvm",
      "line_description": "Job completion",
      "fiat_amount_minor": 100,
      "fiat_currency": "usd",
      "net_fiat_minor": 100
    }
  ],
  "total": 50,
  "org": {
    "id": "acffd753-105a-4958-9f37-243ac032f332",
    "handle": "my-org",
    "role": "admin",
    "personal": false
  }
}
```

Amounts are integer minor units, which round each event on its own: a $0.003 job shows `0`. Each event also carries `fiat_amount_micro`, `processor_fee_fiat_micro`, and `net_fiat_micro` in millionths, and those are the fields to add up. It carries the same `valued_by`, `credit_amount_micro`, `credit_currency`, `credit_fx_rate`, `fx_rate_currency`, and `cross_fx_rate` fields as a [`revenue csv`](#revenue-csv) row, with `credit_amount_micro` `null` on an event that is not a credit draw. `total` is the number of events returned (capped by `--limit`). `org` is the context the events were read from — see [`list`](#list).

***

revenue csv [#revenue-csv]

Export revenue events for your current org context as CSV. Useful for spreadsheets, accounting, or downstream reporting tools. Requires `admin` role in a shared org.

```sh
dvmctl revenue csv --from 2026-05-01 --to 2026-05-27
dvmctl revenue csv --from 2026-05-01 --to 2026-05-27 --rail cashu --out cashu-may.csv
dvmctl revenue csv --from 2026-05-01 --to 2026-05-27 --org my-org
```

| Flag             | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `--org <handle>` | Read as this org, overriding the `dvmctl switch` context |
| `--from <date>`  | Start date (`YYYY-MM-DD`, required)                      |
| `--to <date>`    | End date (`YYYY-MM-DD`, required)                        |
| `--currency <c>` | Reporting currency (`gbp`, `eur`, `usd`, `chf`)          |
| `--rail <r>`     | Filter by payment rail                                   |
| `--out <path>`   | Write CSV to file instead of stdout                      |

Output is raw CSV (no JSON envelope) so the `--out` flag and shell redirection both work cleanly. The `fiat_amount_micro`, `processor_fee_fiat_micro`, and `net_fiat_micro` columns repeat each row's amounts in millionths; sum those rather than the minor-unit columns, which round every row on its own. The summary rows at the bottom already do. The org the export was scoped to is printed to stderr as `Org: <handle>` (or `Org: personal`) and echoed on the response's `X-Org` header — stdout stays pure CSV, and an empty export still says which org it was empty for.

Each row's `valued_by` column says how its amount was reached. A `native_at_rate` row was priced from its `native_amount` at that day's exchange rate. A `credit_obligation` row is a draw on a prepaid credit, and it counts the credit it used, not the payment that funded the credit. Its native columns still show that payment, so they won't add up to its amount. Instead `credit_amount_micro` (millionths of `credit_currency`) times `credit_fx_rate`, rounded to a whole millionth, is its `fiat_amount_micro`. The three credit columns are empty on every other row.

A row's `fx_rate` is the rate stored when the payment landed, and it prices the native asset in `fx_rate_currency`, the currency the platform keeps its books in. That can differ from the export's `fiat_currency`, so `cross_fx_rate` is the number of `fiat_currency` units per unit of `fx_rate_currency` on `fx_rate_snapshot_date`, and it is `1` when the two match. For a `native_at_rate` row, `native_amount / 10^native_decimals × fx_rate × 1,000,000 × cross_fx_rate`, rounded to a whole number, is its `fiat_amount_micro`.

***

billing status [#billing-status]

Read the account's hosting billing state: plan and service term, the current usage period, usage and outbound against the plan's allowances, unpaid card balance, prepaid hosting balance, active restrictions, the no-card hosting trial, and the monthly budget. The read is free and changes nothing. It buys no plan, creates no billing account, starts no trial, and clears no restriction.

The `billing` commands read and authorise **hosting** charges: what you pay dvmkit to run your DVMs. They are separate from the job payments your callers send you, which [`revenue summary`](#revenue-summary) reports. No `billing` command pays on its own. Each one that asks for a payment returns a hosted card (Stripe) page or a Bitcoin Lightning invoice for a person to pay, plus a `continuation.status_command` to check the result.

```sh
dvmctl billing status
dvmctl billing status --org my-org
```

| Flag             | Description                                                             |
| ---------------- | ----------------------------------------------------------------------- |
| `--org <handle>` | Read this org's billing account, overriding the `dvmctl switch` context |
| `--human`        | Print the same JSON, indented, on stderr and without `trace_id`         |

**JSON output: an expired trial in recovery** (abridged):

```json
{
  "version": 1,
  "can_edit": true,
  "account_id": "4b0d3c2e-8f61-4a7e-9a52-1f0c6d2b7e10",
  "as_of": "2026-10-15T09:00:00.000Z",
  "display": "Hosting has active restrictions.",
  "hint": "Amounts are in US dollars. Unknown readings are not zero. This reading does not make a payment or change hosting.",
  "restrictions": {
    "coverage": "complete",
    "items": [
      {
        "reason": "trial_expiry",
        "mode": "pause",
        "dvm_id": null,
        "set_at": "2026-10-12T09:00:00.000Z",
        "deadline_at": null,
        "episode_reset_not_before_at": null,
        "next_actions": [
          {
            "code": "upgrade_plan",
            "display": "Choose and purchase a hosting plan that covers your usage.",
            "deadline_at": null,
            "hint": "Other active restrictions still apply. Contact support if the action is unavailable."
          }
        ],
        "display": "Choose and purchase a hosting plan that covers your usage.",
        "hint": "Ordinary hosting is paused for this reason. Other restrictions may also apply."
      }
    ],
    "display": "Each active restriction must be resolved separately.",
    "hint": "Resolve each listed restriction separately. Clearing one does not guarantee that hosting can resume."
  },
  "trial": {
    "recovery": {
      "data": "managed_database",
      "available": true,
      "export": {
        "route": "/api/v1/builder/dvms/550e8400-e29b-41d4-a716-446655440000/db-tunnel",
        "display": "Export the managed database before the recovery deadline."
      },
      "restore": {
        "route": "/api/v1/builder/dvms/550e8400-e29b-41d4-a716-446655440000/trial-restore",
        "display": "Explicitly purchase Builder, then restore after other restrictions clear."
      },
      "purchase": {
        "stripe": "/api/v1/builder/billing/checkout",
        "lightning": "/api/v1/builder/billing/lightning/checkout"
      },
      "display": "The managed database remains available for export. Ordinary hosting is stopped. Export or purchase Builder before the fixed deadline; requests and failures do not extend it."
    },
    "state": "expired",
    "coverage": "complete",
    "started_at": "2026-09-12T09:00:00.000Z",
    "ends_at": "2026-10-12T09:00:00.000Z",
    "remaining_days": { "amount": 0, "unit": "days", "display": "0 days remaining" },
    "remaining_credit": { "amount": null, "currency": "USD", "unit": "cents", "display": "Trial credit reading unavailable." },
    "remaining_outbound": { "amount": null, "unit": "bytes", "display": "Outbound reading unavailable." },
    "credit_used_percent": null,
    "outbound_used_percent": null,
    "limit_fired": "time",
    "recovery_deadline_at": "2026-10-19T09:00:00.000Z",
    "reason": "time",
    "action": { "route": "/dashboard/billing", "display": "Explicitly purchase Builder to continue hosting." },
    "display": "Your hosting trial has ended.",
    "hint": "Hosting stops when the meter observes a trial limit. No plan is purchased automatically. Account and local tooling remain free."
  }
}
```

The full response also carries `plan`, `period`, `usage`, `outbound`, `card`, `prepaid`, `continuing_costs`, `eligibility`, and `budget` blocks. Each block has its own `coverage`, `display`, and `hint`. Relay `display` and `hint` as written; they are the platform's words for the human.

The same billing state can arrive inside an error from another command. When [`deploy`](#deploy), [`resume`](#resume), or [`scale`](#scale) is refused for a hosting reason and the platform offers no next step, dvmctl reads billing state for that account and adds it to the error object as `billing_state`, with its own `billing_state_trace_id`. If that read fails, the error carries `billing_state_error` and a `billing_status_command` to run instead. Any platform error that includes `options`, `reasons`, or `next_actions` keeps them on the error object, so read them before retrying.

* **Money** is `{ "minor_units": 125, "currency": "USD", "basis": "estimated" }`: 125 means $1.25. `basis` says whether the amount is `actual`, `estimated`, `invoiced`, or `collected`. Hosting is priced in US dollars whichever rail pays for it.
* **Unknown is not zero.** A block with `coverage: "unknown"` has null amounts. Never read a null as nothing used or nothing owed.
* **Every restriction counts.** `restrictions.items` lists every active reason, each scoped to the account (`dvm_id: null`) or to one DVM. Resolving one leaves the others in force. `next_actions[].code` is stable for agents (`upgrade_plan`, `settle_card`, `top_up_hosting`, `wait_for_period`, `resume_hosting`, `raise_or_remove_budget`, `contact_support`); its `display` can change.
* **`trial`** is null for an account that never had a no-card trial while the platform is not admitting trials. When it is admitting them, such an account gets a block with `state: "none"`. In recovery it carries `recovery_deadline_at`, seven days after the trial ended, and the export, restore, and purchase actions that [`trial export`](#trial-export) and [`trial restore`](#trial-restore) use.
* **`budget`** is always a block. Its `availability` is null when monthly budgets apply to the account. Otherwise `availability.code` says why they do not: `budget_not_available`, `budget_paid_plan_required`, or `budget_plan_unsupported`. A budget that is already set stays visible and removable either way. See [`billing budget get`](#billing-budget-get).

**Error anchors** (shared by every `billing` and `trial` command):

| Code                          | Trigger                                                                                                                                                        |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `billing_version_unsupported` | The platform returned a billing-state version this dvmctl does not understand. Upgrade dvmctl before reading it                                                |
| `billing_not_available`       | The platform does not serve this billing route. Either the feature is not switched on there (hosting top-ups are not offered yet), or the platform predates it |
| `not_found`                   | The invoice, quote, or top-up ID does not exist in this account                                                                                                |
| `billing_scope_unsupported`   | A route that bills only the authenticated key's own account was given an org (see [`billing checkout`](#billing-checkout))                                     |
| `billing_failed`              | Any other refusal without its own code. When the platform sent no message, the message names the HTTP status                                                   |

***

billing budget get [#billing-budget-get]

Read the account's monthly hosting budget and the `version` you pass to [`billing budget set`](#billing-budget-set). A budget is a USD limit on one usage period's hosting spend. It counts gross compute, storage, and outbound, including usage the plan's included credit covers, plus spend reserved for work in progress.

Budgets are not available to every account. Where they are not, the platform refuses with `budget_not_available` ("Monthly budgets are not available yet"), and a budget that was already set stays readable and removable. Budgets need a paid plan.

```sh
dvmctl billing budget get
dvmctl billing budget get --org my-org
```

| Flag             | Description                                                     |
| ---------------- | --------------------------------------------------------------- |
| `--org <handle>` | Read this org's budget, overriding the `dvmctl switch` context  |
| `--human`        | Print the same JSON, indented, on stderr and without `trace_id` |

**JSON output:**

```json
{
  "state": "ok",
  "period": { "start": "2026-10-01T00:00:00.000Z", "end": "2026-11-01T00:00:00.000Z" },
  "limit_cents": 5000,
  "actual_cents": 1840,
  "reserved_cents": 120,
  "coverage": "complete",
  "warn_at_cents": 4000,
  "version": 3,
  "continuing_costs": { "plan_cents": 1900, "retained_storage_cents": 30, "recovery_cents": null },
  "can_edit": true,
  "display": "Your hosting usage is within your monthly budget.",
  "hint": "Included hosting credit counts toward the budget. Reserved spend has not been charged. Plan fees and retained storage keep billing while paused; storage shown here is rated so far this period.",
  "stops_jobs": true
}
```

Every amount is in US cents. `state` is `none` (no budget set), `ok`, `warning` (actual plus reserved spend has reached `warn_at_cents`, 80% of the limit), `paused` (the platform reports the budget as reached), or `unknown` (spend is not fully known, which takes precedence). Whether hosting is actually held back for a reached budget shows as a `customer_budget` restriction in [`billing status`](#billing-status); this command does not report it. `reserved_cents` has not been charged. `continuing_costs` are costs that keep accruing regardless of the budget: the plan fee for the period and storage rated so far. An unset budget reads as version `0`. `can_edit` is true only for an owner or admin using a builder key. `stops_jobs` says whether reaching the budget stops new jobs. It is `false` only on the `internal` plan, which only dvmkit assigns, where the budget warns but never stops jobs. On that plan `state` never reads `paused`, and it reads `warning` past the limit.

**Error anchors:**

| Code                   | Trigger                                                                 |
| ---------------------- | ----------------------------------------------------------------------- |
| `budget_not_available` | Monthly budgets are not available to this account, and no budget is set |
| `not_found`            | The org does not exist or you are not a member                          |

***

billing budget set [#billing-budget-set]

Set, change, or remove the monthly hosting budget. Pass the limit in US cents, or `none` to remove the budget. The write needs the `version` from [`billing budget get`](#billing-budget-get), so two people editing at once cannot silently overwrite each other, and an idempotency key you save before running it.

```sh
dvmctl billing budget set 5000 --expected-version 3 --idempotency-key budget-2026-10-a
dvmctl billing budget set none --expected-version 4 --idempotency-key budget-2026-10-b
```

| Flag                           | Description                                                                                                                               |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `--expected-version <version>` | The `version` from `billing budget get` (required)                                                                                        |
| `--idempotency-key <key>`      | 8 to 128 letters, digits, underscores, or hyphens (required). Save it first; after an interruption, rerun with the same key and arguments |
| `--org <handle>`               | Set this org's budget, overriding the `dvmctl switch` context                                                                             |
| `--human`                      | Print the same JSON, indented, on stderr and without `trace_id`                                                                           |

**JSON output:** the same shape as [`billing budget get`](#billing-budget-get), after the change, plus the `idempotency_key` you sent.

The limit must be above the plan's included hosting credit, because that credit counts toward the budget. Removing or lowering a budget does not change usage already rated or charges already made. Only an owner or admin can write, and only with a builder key: an org API key can read the budget but not change it. Removing an existing budget is always allowed, whatever the plan.

**Error anchors:**

| Code                           | Trigger                                                                                                                            |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `bad_request`                  | The limit is not a positive whole number of cents or `none`, `--expected-version` is not a whole number, or the key is malformed   |
| `budget_conflict`              | The budget changed since you read it, or the key was used with different arguments. Run `billing budget get` again before deciding |
| `budget_below_included_credit` | The limit is at or below the plan's included hosting credit                                                                        |
| `budget_paid_plan_required`    | The account is not on a paid plan                                                                                                  |
| `budget_plan_unsupported`      | Enterprise plans set hosting limits by contract. Contact dvmkit                                                                    |
| `budget_not_available`         | Monthly budgets are not available to this account                                                                                  |
| `budget_actor_refused`         | You are not an owner or admin, or you used an org API key                                                                          |

***

billing topup [#billing-topup]

Ask for a Bitcoin Lightning invoice that adds prepaid hosting funds to the account. Give the amount as US cents; the minimum is 100 ($1). The platform converts it to a Lightning invoice at a quoted exchange rate. This is a hosting balance in US dollars, separate from a plan subscription and from any caller's prepaid credit at your DVM.

Hosting top-ups are not offered yet, so `billing topup` and [`billing topup-status`](#billing-topup-status) currently return `billing_not_available` on dvmkit's hosted platform. The rest of this section describes the command for when they are switched on.

The command creates the invoice and stops. It does not pay. A person pays the `bolt11` invoice from a Lightning wallet, then you check it with [`billing topup-status`](#billing-topup-status). Only `state: "paid"` adds funds.

```sh
dvmctl billing topup 2500 --idempotency-key topup-2026-10-15-a
```

| Flag                      | Description                                                                                                                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--idempotency-key <key>` | 8 to 128 letters, digits, underscores, or hyphens (required). Save it first; after an interruption, rerun with the same key and amount to get the same invoice back |
| `--org <handle>`          | Top up this org's hosting balance, overriding the `dvmctl switch` context. Needs an owner or admin, or that org's own API key                                       |
| `--human`                 | Print the same JSON, indented, on stderr and without `trace_id`                                                                                                     |

**JSON output:**

```json
{
  "id": "0f6e2a91-3c47-4d8b-b1e5-7a2c9d4e6f80",
  "billingAccountId": "4b0d3c2e-8f61-4a7e-9a52-1f0c6d2b7e10",
  "requestKey": "topup-2026-10-15-a",
  "quote": {
    "usdCents": 2500,
    "nativeSats": 27411,
    "nativeMsats": 27411000,
    "fxUsdPerBtc": "91207.15",
    "fxSource": "coingecko",
    "fxObservedAt": 1792424700000,
    "quotedAt": 1792425600000,
    "expiresAt": 1792426500000,
    "rounding": "ceil_sats"
  },
  "state": "invoiced",
  "paymentHash": "a3f1c9e2...",
  "bolt11": "lnbc274110n1p...",
  "providerExpiresAt": 1792426500000,
  "display": "$25.00 hosting value; Lightning invoice 27411 sats (Bitcoin units). Quote expires: 2026-10-19T16:15:00.000Z. Status: invoiced.",
  "hint": "Only paid confirms hosting credit. Check the saved invoice status; do not create another top-up to resume.",
  "continuation": {
    "invoice_id": "0f6e2a91-3c47-4d8b-b1e5-7a2c9d4e6f80",
    "status_command": ["dvmctl", "billing", "topup-status", "0f6e2a91-3c47-4d8b-b1e5-7a2c9d4e6f80"]
  }
}
```

`quote.usdCents` is the hosting value you asked for. `quote.nativeSats` is the Lightning invoice amount, rounded up to whole satoshis. Times are Unix milliseconds. `quote.expiresAt` and `providerExpiresAt` come from different places, so treat the earlier one as the deadline. `state` is `creating`, `provider_ambiguous`, `invoiced`, `expired`, or `paid`. While it is `creating` or `provider_ambiguous`, `bolt11` can be null: poll, and do not create another top-up.

**Error anchors:**

| Code                        | Trigger                                                                                                                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `bad_request`               | The amount is below 1000 or not a whole number of cents, or the key is malformed                                                                                                           |
| `hosting_topup_conflict`    | The key was already used with a different amount. Use a new key                                                                                                                            |
| `hosting_topup_unavailable` | The platform cannot create a hosting top-up right now                                                                                                                                      |
| `forbidden`                 | With no org selected, an org API key was used: the personal top-up needs a builder key. With an org selected, you are not an owner or admin of it and are not using that org's own API key |
| `billing_not_available`     | Hosting top-ups are not offered on this platform, which today includes dvmkit's hosted platform                                                                                            |

***

billing topup-status [#billing-topup-status]

Check a top-up you already created, by the `id` that [`billing topup`](#billing-topup) returned. The platform checks the invoice once and records the payment if it has arrived. It never creates another invoice.

```sh
dvmctl billing topup-status 0f6e2a91-3c47-4d8b-b1e5-7a2c9d4e6f80
```

| Flag             | Description                                                           |
| ---------------- | --------------------------------------------------------------------- |
| `--org <handle>` | The org the top-up belongs to, overriding the `dvmctl switch` context |
| `--human`        | Print the same JSON, indented, on stderr and without `trace_id`       |

**JSON output:** the same shape as [`billing topup`](#billing-topup), with the current `state`. After `paid`, the funds appear under `prepaid` in [`billing status`](#billing-status).

**Error anchors:**

| Code                        | Trigger                                                  |
| --------------------------- | -------------------------------------------------------- |
| `not_found`                 | No top-up with this ID in this account                   |
| `hosting_topup_unavailable` | The platform could not check the top-up right now. Retry |
| `billing_not_available`     | Hosting top-ups are not offered on this platform         |

***

billing invoice [#billing-invoice]

Check a Bitcoin Lightning subscription invoice once, by the `invoice_id` that [`billing checkout --rail lightning`](#billing-checkout) returned. Use it to resume an interrupted Lightning checkout instead of starting another one. This route bills only the key's own account, so it refuses an org (see [`billing checkout`](#billing-checkout)).

```sh
dvmctl billing invoice 7d3b5e10-92a4-4c6f-8e17-b0c2d9f41a36
```

| Flag             | Description                                                                           |
| ---------------- | ------------------------------------------------------------------------------------- |
| `--org <handle>` | Refused with `billing_scope_unsupported`: this route bills only the key's own account |
| `--human`        | Print the same JSON, indented, on stderr and without `trace_id`                       |

**JSON output:**

```json
{
  "status": "paid",
  "display": "Payment received. Your plan is active.",
  "bolt11": "lnbc523100n1p...",
  "amountSats": 52310,
  "amountCents": 4560,
  "fiatCurrency": "gbp",
  "planUsdCents": 5700,
  "expiresAt": 1792425600000,
  "paidAt": 1792424900000,
  "invoiceId": "7d3b5e10-92a4-4c6f-8e17-b0c2d9f41a36",
  "amount_display": "£45.60",
  "plan_usd_display": "$57.00",
  "hint": "A hosted payment page or invoice is a human payment step. Only the platform's confirmed status establishes payment and activation.",
  "continuation": {
    "url": null,
    "invoice_id": "7d3b5e10-92a4-4c6f-8e17-b0c2d9f41a36",
    "status_command": ["dvmctl", "billing", "invoice", "7d3b5e10-92a4-4c6f-8e17-b0c2d9f41a36"]
  }
}
```

| `status`           | Meaning                                                                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending`          | No payment recorded yet. Check again                                                                                                                    |
| `payment_received` | The payment arrived and the plan is being applied. Do not pay again; check again later                                                                  |
| `payment_recovery` | The payment arrived, but the plan change it paid for could not be applied. Do not pay again. Relay `display`, which tells the person to contact support |
| `paid`             | The plan is active                                                                                                                                      |
| `expired`          | The invoice expired with no payment recorded                                                                                                            |

`bolt11` is null while the status is `payment_received` or `payment_recovery`, so nobody is shown an invoice to pay twice; the other statuses return the original invoice. `amountCents` is in the invoice's reporting currency (`fiatCurrency`), not necessarily US cents, and `amount_display` labels it. `planUsdCents` is the subscription's US dollar value before any credit, and is null for an older invoice whose value cannot be recovered. Times are Unix milliseconds.

**Error anchors:**

| Code                        | Trigger                                                   |
| --------------------------- | --------------------------------------------------------- |
| `not_found`                 | No invoice with this ID in this account                   |
| `billing_scope_unsupported` | An org was selected, by `--org` or by `dvmctl switch`     |
| `lightning_error`           | The platform could not check the Lightning invoice. Retry |

***

billing checkout [#billing-checkout]

Start buying a paid plan, including converting a no-card trial. Pass a plan ID such as `builder-monthly`, `builder-yearly`, `studio-monthly`, `studio-yearly`, or `scale-yearly`, and choose how to pay with `--rail`. The command opens the payment; it does not pay. A person completes the card (Stripe) page or pays the Bitcoin Lightning invoice, and the platform's status is the only proof that the plan is active.

```sh
dvmctl billing checkout builder-monthly --rail stripe
dvmctl billing checkout builder-monthly --rail lightning --months 3
```

| Flag                | Description                                                                                                                   |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `--rail <rail>`     | `stripe` (card) or `lightning` (Bitcoin Lightning) (required)                                                                 |
| `--months <months>` | Lightning only: prepay 1, 3, 6, or 12 months. Omit it for the platform's default. Yearly plans are sold as one 12-month block |
| `--org <handle>`    | Card checkout for this org, overriding the `dvmctl switch` context. Refused on the Lightning rail                             |
| `--human`           | Print the same JSON, indented, on stderr and without `trace_id`                                                               |

**JSON output: `--rail stripe`**

```json
{
  "url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3...",
  "display": "Payment action returned. Check status to confirm service activation.",
  "hint": "A hosted payment page or invoice is a human payment step. Only the platform's confirmed status establishes payment and activation.",
  "continuation": {
    "url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3...",
    "invoice_id": null,
    "status_command": ["dvmctl", "billing", "status"]
  }
}
```

**JSON output: `--rail lightning`**

```json
{
  "invoiceId": "7d3b5e10-92a4-4c6f-8e17-b0c2d9f41a36",
  "bolt11": "lnbc523100n1p...",
  "paymentHash": "9be0c4d7...",
  "amountSats": 52310,
  "amountCents": 4560,
  "fiatCurrency": "gbp",
  "planUsdCents": 5700,
  "expiresAt": 1792425600000,
  "amount_display": "£45.60",
  "plan_usd_display": "$57.00",
  "display": "$57.00 USD plan value before credit; £45.60 invoice value; Lightning invoice 52310 sats (Bitcoin units).; Expires: 2026-10-19T16:00:00.000Z.",
  "hint": "A hosted payment page or invoice is a human payment step. Only the platform's confirmed status establishes payment and activation.",
  "continuation": {
    "url": null,
    "invoice_id": "7d3b5e10-92a4-4c6f-8e17-b0c2d9f41a36",
    "status_command": ["dvmctl", "billing", "invoice", "7d3b5e10-92a4-4c6f-8e17-b0c2d9f41a36"]
  }
}
```

For the card rail, hand `url` to the person and confirm the plan with [`billing status`](#billing-status) afterwards. For Lightning, the invoice expires at `expiresAt` (Unix milliseconds); check it with [`billing invoice`](#billing-invoice). Neither rail takes an idempotency key, and dvmctl never retries the request. If a checkout is interrupted, check `billing status` and any saved invoice before asking for another.

**Which account is billed.** Card checkout bills the org that `--org` or the `dvmctl switch` context selects, and checkout for an org needs an owner or admin, or that org's own API key. Lightning checkout, [`billing invoice`](#billing-invoice), and the `billing plan` commands bill only the account that owns the API key. They refuse any selected org, including one saved by `dvmctl switch`, rather than bill a different account. Lightning checkout also needs a personal (builder) API key: an org API key is refused with `forbidden`. Use a builder key for the account you mean and run `dvmctl switch --personal` first.

**Error anchors:**

| Code                        | Trigger                                                                                                                                                  |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bad_request`               | `--rail` is missing or not `stripe` or `lightning`, `--months` was given with `stripe`, `--months` is not 1, 3, 6, or 12, or the plan is not a paid plan |
| `billing_scope_unsupported` | Lightning checkout with an org selected, by `--org` or by `dvmctl switch`                                                                                |
| `payment_received`          | A Lightning payment has already been received and is being applied. Do not pay again                                                                     |
| `lightning_error`           | The platform could not create the Lightning invoice                                                                                                      |
| `stripe_error`              | The platform could not create the card checkout session for an org                                                                                       |
| `forbidden`                 | Lightning checkout with an org API key, or org card checkout by someone who is neither an owner or admin nor using that org's own API key                |
| `billing_not_available`     | This platform does not offer checkout on that rail                                                                                                       |

***

billing plan quote [#billing-plan-quote]

Price a change from your current paid plan to another one, without buying anything. This is for an account that already has a settled paid term; to buy a first plan or convert a trial, use [`billing checkout`](#billing-checkout). The quote credits unused time on the current term against the new price. Plan changes are off unless the platform operator has enabled them, so on most platforms all three `billing plan` commands return `plan_changes_unavailable`.

```sh
dvmctl billing plan quote studio-monthly --request-key studio-upgrade-2026-10
```

| Flag                  | Description                                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| `--request-key <key>` | 1 to 128 characters (required). Save it; rerunning with the same key and plan returns the same quote |
| `--org <handle>`      | Refused with `billing_scope_unsupported`; plan changes bill only the key's own account               |
| `--human`             | Print the same JSON, indented, on stderr and without `trace_id`                                      |

**JSON output:**

```json
{
  "id": "2e8d7c64-1b9f-4a35-8c02-6d4a9e3f17b8",
  "state": "quoted",
  "quote": {
    "currentPlanId": "builder-monthly",
    "targetPlanId": "studio-monthly",
    "kind": "purchase",
    "currency": "USD",
    "createdAt": 1792425600000,
    "expiresAt": 1792429200000,
    "effectiveAt": 1792425600000,
    "serviceStartsAt": 1791763200000,
    "serviceEndsAt": 1794441600000,
    "usageAnchorAt": 1791763200000,
    "usagePeriodStart": 1791763200000,
    "usagePeriodEnd": 1794441600000,
    "unusedSubscriptionCreditCents": 1430,
    "guaranteedUnusedSubscriptionCreditCents": 1430,
    "appliedSubscriptionCreditCents": 1430,
    "remainingSubscriptionCreditCents": 0,
    "newSubscriptionCostCents": 7450,
    "payableCents": 6020,
    "monthlyCreditCentsAfter": 2000,
    "monthlyOutboundGbAfter": 25,
    "creditAdjustmentMicrocents": "750000000",
    "outboundAdjustmentBytes": "15000000000",
    "requiredResourceReductions": [],
    "eligibilityAssessedAt": 1792425600000
  },
  "trailing30DayGrossMicrocents": "3120000000",
  "trailing30DayLimitMicrocents": "75000000000",
  "request_key": "studio-upgrade-2026-10",
  "display": "Plan quote: $60.20 payable. No purchase has been made.",
  "hint": "Use the saved quote id for an explicit purchase. A renewal downgrade requires scheduling on the platform."
}
```

`payableCents` is what [`billing plan purchase`](#billing-plan-purchase) would charge, in the quote's `currency`. Times are Unix milliseconds. `kind: "renewal_downgrade"` means a move to a lower plan, which takes effect at the end of the current term: it is scheduled on the platform, and this CLI cannot purchase it. A non-empty `requiredResourceReductions` lists what you must shrink before the target plan accepts your DVMs.

**Error anchors:**

| Code                        | Trigger                                                                           |
| --------------------------- | --------------------------------------------------------------------------------- |
| `plan_changes_unavailable`  | Plan changes are not enabled on this platform                                     |
| `settled_term_unavailable`  | The account has no settled paid term to change from. Use `billing checkout`       |
| `billing_account_missing`   | The key's account has no billing account yet, so it has no plan to change         |
| `invalid_plan`              | The target plan does not exist or is not on sale                                  |
| `conflicting_request_key`   | The request key was already used for a different plan                             |
| `plan_change_ineligible`    | Your usage or resources exceed what the target plan allows                        |
| `usage_evidence_incomplete` | The platform cannot yet price the change from complete usage records. Retry later |
| `billing_scope_unsupported` | An org was selected, by `--org` or by `dvmctl switch`                             |

***

billing plan purchase [#billing-plan-purchase]

Buy a saved quote by its `id`. dvmctl reads the quote first, then asks the platform for a card invoice or a Bitcoin Lightning invoice. With `--rail lightning`, when unused credit covers the whole price, the change applies without an invoice.

```sh
dvmctl billing plan purchase 2e8d7c64-1b9f-4a35-8c02-6d4a9e3f17b8 --rail lightning
```

| Flag             | Description                                                                            |
| ---------------- | -------------------------------------------------------------------------------------- |
| `--rail <rail>`  | `stripe` (card) or `lightning` (Bitcoin Lightning) (required)                          |
| `--org <handle>` | Refused with `billing_scope_unsupported`; plan changes bill only the key's own account |
| `--human`        | Print the same JSON, indented, on stderr and without `trace_id`                        |

**JSON output: `--rail lightning`**

```json
{
  "id": "2e8d7c64-1b9f-4a35-8c02-6d4a9e3f17b8",
  "rail": "lightning",
  "invoiceId": "c19a4f27-5e83-4b0d-9a62-3f7e1d8b05c4",
  "bolt11": "lnbc659800n1p...",
  "paymentHash": "4c7d21aa...",
  "amountSats": 65980,
  "amountCents": 6020,
  "fiatCurrency": "usd",
  "planUsdCents": 6020,
  "expiresAt": 1792426500000,
  "quote_currency": "USD",
  "amount_display": "$60.20",
  "plan_usd_display": "$60.20",
  "display": "$60.20 USD plan value before credit; $60.20 invoice value; Lightning invoice 65980 sats (Bitcoin units).; Expires: 2026-10-19T16:15:00.000Z.",
  "hint": "A hosted payment page or invoice is a human payment step. Only the platform's confirmed status establishes payment and activation.",
  "continuation": {
    "url": null,
    "invoice_id": "c19a4f27-5e83-4b0d-9a62-3f7e1d8b05c4",
    "status_command": ["dvmctl", "billing", "plan", "status", "2e8d7c64-1b9f-4a35-8c02-6d4a9e3f17b8"]
  }
}
```

With `--rail stripe` the platform returns a card invoice instead: `invoiceId`, `status`, `subtotalCents`, `taxCents`, `totalCents`, and `hostedInvoiceUrl`, which also appears as `continuation.url`. When credit covers the full price on the Lightning rail, nothing is owed and no invoice is created. The output is `id`, `state`, and `payableCents: 0`, plus `quote_currency`, the generic `display` ("Payment action returned. Check status to confirm service activation."), `hint`, and a `continuation` whose `url` and `invoice_id` are null. Read `state` in that case, not the display. Whatever the rail, confirm the result with [`billing plan status`](#billing-plan-status).

**Error anchors:**

| Code                          | Trigger                                                                                |
| ----------------------------- | -------------------------------------------------------------------------------------- |
| `bad_request`                 | `--rail` is missing or not `stripe` or `lightning`                                     |
| `not_found`                   | No quote with this ID in this account                                                  |
| `downgrade_requires_schedule` | The quote is a renewal downgrade, which the platform schedules for the end of the term |
| `settled_term_unavailable`    | The current paid term changed or ended since the quote                                 |
| `plan_change_ineligible`      | Usage or resources now exceed the target plan                                          |
| `usage_evidence_incomplete`   | The platform cannot confirm complete usage records. Retry later                        |
| `payment_received`            | A Lightning payment has already been received and is being applied. Do not pay again   |
| `rail_unavailable`            | This platform does not offer that payment rail                                         |
| `plan_changes_unavailable`    | Plan changes are not enabled on this platform                                          |
| `billing_scope_unsupported`   | An org was selected, by `--org` or by `dvmctl switch`                                  |

***

billing plan status [#billing-plan-status]

Check a plan change by its quote `id`. While a payment is pending, the platform checks it with the card processor or the Lightning wallet before answering.

```sh
dvmctl billing plan status 2e8d7c64-1b9f-4a35-8c02-6d4a9e3f17b8
```

| Flag             | Description                                                                            |
| ---------------- | -------------------------------------------------------------------------------------- |
| `--org <handle>` | Refused with `billing_scope_unsupported`; plan changes bill only the key's own account |
| `--human`        | Print the same JSON, indented, on stderr and without `trace_id`                        |

**JSON output:** the saved `id`, `quote`, `rail`, and `paymentRef`, the current `state`, and an `applied` block once the change has been applied, plus `display` (`Plan change status: <state>.`) and `hint`. `state` is `quoted`, `pending_payment`, `applied`, `scheduled`, or `recovery`. Only `applied` means the new plan is in force. `recovery` means the payment arrived but the change could not be applied; do not pay again, and contact support. In that state a `recovery` block (otherwise null) records what happened: `reason`, `paidAt`, `paidSubtotalCents`, `paidTotalCents`, `purchasedPlanId`, `providerServiceStartsAt`, `providerServiceEndsAt`, and `requiredResourceReductions`.

**Error anchors:**

| Code                        | Trigger                                               |
| --------------------------- | ----------------------------------------------------- |
| `not_found`                 | No quote with this ID in this account                 |
| `plan_changes_unavailable`  | Plan changes are not enabled on this platform         |
| `billing_scope_unsupported` | An org was selected, by `--org` or by `dvmctl switch` |

***

trial export [#trial-export]

Open a local database connection to a DVM whose no-card hosting trial has ended, so you can save its data. When a trial ends, the DVM stops taking jobs and its data is kept for seven days. During those seven days you can export the data, or buy a plan and [restore](#trial-restore) the DVM as it was. After that the platform deletes it, and a retry or a failed export does not extend the deadline.

dvmctl first reads [`billing status`](#billing-status). If the trial's recovery block offers no export, it stops there with `trial_export_unavailable`. Otherwise it opens a tunnel the same way [`db proxy`](#db-proxy) does. Database connections through it end at the recovery deadline, but the command itself keeps running until you interrupt it (Ctrl-C or SIGTERM).

```sh
dvmctl trial export my-dvm
dvmctl trial export my-dvm --port 15433
```

| Flag             | Description                                                                           |
| ---------------- | ------------------------------------------------------------------------------------- |
| `--port <port>`  | Local port to bind (default: an OS-assigned free port)                                |
| `--machine <id>` | Broker through a specific machine                                                     |
| `--org <handle>` | Resolve the slug and read billing as this org, overriding the `dvmctl switch` context |
| `--human`        | Print the same JSON, indented, on stderr and without `trace_id`                       |

**JSON output** (one line, then the command blocks until interrupted):

```json
{
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm",
  "database_url": "postgres://user:pw@127.0.0.1:15433/my_dvm?sslmode=disable",
  "host": "127.0.0.1",
  "port": 15433,
  "recovery_deadline_at": "2026-10-19T09:00:00.000Z",
  "recovery": {
    "data": "managed_database",
    "available": true,
    "export": {
      "route": "/api/v1/builder/dvms/550e8400-e29b-41d4-a716-446655440000/db-tunnel",
      "display": "Export the managed database before the recovery deadline."
    },
    "restore": {
      "route": "/api/v1/builder/dvms/550e8400-e29b-41d4-a716-446655440000/trial-restore",
      "display": "Explicitly purchase Builder, then restore after other restrictions clear."
    },
    "purchase": {
      "stripe": "/api/v1/builder/billing/checkout",
      "lightning": "/api/v1/builder/billing/lightning/checkout"
    },
    "display": "The managed database remains available for export. Ordinary hosting is stopped. Export or purchase Builder before the fixed deadline; requests and failures do not extend it."
  },
  "display": "Export the managed database before the recovery deadline.",
  "hint": "Use pg_dump with database_url to save the database. Keep this process running during export; the read-only tunnel ends by the recovery deadline."
}
```

Then, from another shell:

```sh
pg_dump "postgres://user:pw@127.0.0.1:15433/my_dvm?sslmode=disable" > my-dvm-export.sql
```

`database_url` carries a temporary password. Keep it private.

**Error anchors:**

| Code                       | Trigger                                                                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trial_export_unavailable` | The trial has no export available: it has not ended, recovery is over, or there is no managed database. The error object carries the `billing_state` |
| `trial_recovery_closed`    | The seven-day recovery window has ended. This does not by itself mean the DVM has been deleted                                                       |
| `invalid_port`             | `--port` is not an integer in 1 to 65535                                                                                                             |
| `local_listener_failed`    | The local port is already in use (or otherwise unbindable)                                                                                           |
| `no_running_machine`       | No machine is available to broker through                                                                                                            |
| `not_found`                | Unknown slug, or you don't own the DVM                                                                                                               |

***

trial restore [#trial-restore]

Bring a DVM back into service after its trial ended and you bought a paid plan. Restore buys nothing and does not restart the trial. Buy the plan first with [`billing checkout`](#billing-checkout) before the seven-day recovery deadline, and wait until [`billing status`](#billing-status) shows it active. If you bought the plan before the deadline, you can run restore after it.

```sh
dvmctl trial restore my-dvm
```

| Flag             | Description                                                                           |
| ---------------- | ------------------------------------------------------------------------------------- |
| `--org <handle>` | Resolve the slug and read billing as this org, overriding the `dvmctl switch` context |
| `--human`        | Print the same JSON, indented, on stderr and without `trace_id`                       |

**JSON output:**

```json
{
  "restored": true,
  "display": "Paid hosting restored.",
  "dvmId": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-dvm"
}
```

When the platform refuses, dvmctl reads [`billing status`](#billing-status) for the same account and adds it to the error object as `billing_state`, with its own `billing_state_trace_id`, beside a `status_command`. If that read fails, the error carries `billing_state_error` instead, and the original refusal still stands.

**Error anchors:**

| Code                        | Trigger                                                                                                                                                                               |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `purchase_required`         | The trial has not been converted to a paid plan. The error object names the card (`stripe`) and Bitcoin Lightning (`lightning`) checkout routes                                       |
| `trial_restore_blocked`     | The plan is paid, but other restrictions still hold the DVM, or cleanup had already started. `reasons` lists the account's active restrictions, which can include holds on other DVMs |
| `trial_recovery_closed`     | The seven-day recovery window ended before a paid plan was bought. This does not by itself mean the DVM has been deleted                                                              |
| `trial_restore_unavailable` | This DVM has no ended trial with data to restore                                                                                                                                      |
| `not_found`                 | Unknown slug, or you don't own the DVM                                                                                                                                                |

***

api-keys list [#api-keys-list]

List your builder API keys. Each key carries an `id`, `label`, `key_prefix`, `created_at`, and `last_used_at`. Secrets are write-only — they're returned exactly once at creation; this listing surfaces metadata only.

```sh
dvmctl api-keys list
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

**JSON output:**

```json
{
  "keys": [
    {
      "id": "ak_0e4220d396ef48c8",
      "label": "ci-runner",
      "key_prefix": "dvmk_9f8",
      "created_at": 1746057600000,
      "last_used_at": 1748347200000
    }
  ],
  "count": 1,
  "limit": 10
}
```

`created_at`/`last_used_at` are epoch-millisecond numbers (`last_used_at` is `null` if never used); `--human` renders them as dates. `count` is the number of keys returned, `limit` your plan's per-account key cap.

***

api-keys create [#api-keys-create]

Create a new builder API key. The secret is returned exactly once in the response — store it immediately; you can't recover it later. To rotate, create a new key, swap your CI / scripts, then `revoke` the old one.

```sh
dvmctl api-keys create
dvmctl api-keys create --label ci-runner
```

| Flag             | Description                                                  |
| ---------------- | ------------------------------------------------------------ |
| `--label <text>` | Optional label to identify the key in `dvmctl api-keys list` |
| `--human`        | Prose output                                                 |

**JSON output:**

```json
{
  "id": "ak_0e4220d396ef48c8",
  "label": "ci-runner",
  "key": "dvmk_9f86d081884c7d659a2feaa0c55ad015",
  "created_at": 1748347200000
}
```

The `key` field is the full secret and is **never** returned again. Treat the response object as do-not-log material. `created_at` is an epoch-millisecond number.

***

api-keys revoke [#api-keys-revoke]

Revoke (delete) an API key by ID. Any further request using the revoked secret returns `auth_required`. Irreversible.

```sh
dvmctl api-keys revoke ak_0e4220d396ef48c8
```

| Flag      | Description  |
| --------- | ------------ |
| `--human` | Prose output |

**JSON output:**

```json
{ "deleted": true, "id": "ak_0e4220d396ef48c8" }
```
