dvmctl CLI reference

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 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). Two outputs carry no trace_id at all: auth and deploy --target self-host, 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. 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

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

MethodHow
Interactive browser flowdvmctl auth — opens browser, stores key in ~/.dvmctl/config.json
Environment variableDVMKIT_API_KEY=dvmk_... — takes precedence over stored key, useful in CI

Environment variables

VariableDefaultDescription
DVMKIT_API_KEY—API key; overrides stored credentials
DVMKIT_PLATFORM_URLhttps://api.dvmkit.devPlatform API base URL
DVMKIT_WEB_URLhttps://dvmkit.comWeb app base URL (used by dvmctl auth)
DVMKIT_CONFIG_DIR~/.dvmkitBuilder state directory: secrets and per-DVM records. See State directories
DVMCTL_CONFIG_DIR~/.dvmctlLogin directory: the stored API key and switch context. See 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.

VariableDefaultHolds
DVMKIT_CONFIG_DIR~/.dvmkitBuilder secrets: builder.mnemonic (Cashu lock keys, from lock create) and builder.key (signing identity, from 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~/.dvmctlconfig.json: the API key from auth and the active switch context
DVM_CONFIG_DIR~/.dvmThe 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 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 on another machine needs builder.mnemonic and builder.json from this directory.

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

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

{
  "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, a direct line to us. You can ask us there, or write to support@dvmkit.com. Agents can also run dvmctl feedback send. Relay these help options to the human when they need help. In --human mode, the link prints as one line.

Exit codes

CodeMeaning
0Success
1Any error

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).

dvmctl auth
dvmctl auth --status
dvmctl auth --logout

See Logging in to dvmkit 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.

FlagDescription
--statusShow current authentication state
--logoutRemove stored credentials
--humanProse output

JSON output — --status (authenticated):

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

JSON output — --logout:

{ "status": "logged_out" }

create

Scaffold a new DVM project in the current directory.

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.

FlagDescription
--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

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

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.

FlagDescription
--port <port>HTTP port (default: PORT env var or 3000)
--no-reloadDisable hot reload
--humanHuman-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 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:

CodeTrigger
handler_load_failedThe handler threw while loading, has a syntax error, or exports no configureDVM() result
dev_port_in_useAnother process is already listening on the port, often an earlier dvmctl dev. Stop it or pass --port
dev_listen_failedThe port can't be opened for any other reason, such as a number above 65535

deploy

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

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.

FlagDescription
--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)
--localRegister 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-runValidate and build locally without contacting platform
--create-identityCreate the builder signing identity when it is absent; intended for noninteractive first deploys
--yesSkip the SDK-staleness confirmation prompt and proceed automatically
--env-stdinRead 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-dirtyAllow 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
--humanProse output

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:

{
  "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

Cloud deploy (success):

{
  "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. 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 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:

{
  "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:

{
  "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.

Error anchors:

CodeTrigger
auth_requiredNot authenticated
dirty_worktreePackaged files differ from HEAD on a cloud deploy without --allow-dirty
build_context_requiredNeither 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_contextThe 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_foundNeither 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_dockerfileNo Dockerfile at the project root. Cloud deploys run as containers, so dvmctl create scaffolds one
isolate_runtime_unavailableThe platform refused --runtime isolate, or a redeploy of a DVM that was on the isolate runtime: that runtime is limited to operator accounts
invalid_slugSlug is too short (min 3 chars)
docker_build_failedLocal Docker build failed
invalid_dvmkit_configMalformed dvmkit field in package.json
terms_not_acceptedThe account has not accepted the current Builder Terms; the message names the page to accept them on
handle_requiredA cloud deploy from an owner with no handle. The DVM would have no address, so claim one with dvmctl handle set and deploy again

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.

dvmctl deploy-status 3dcc9623-8db4-4c03-9929-a0cd5841c1d2
FlagDescription
--humanProse output

JSON output:

{
  "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

Ask Coinbase's public x402 validator about each x402 route a deployed DVM serves. It runs the same check a cloud 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.

dvmctl x402 listing-check my-dvm
dvmctl x402 listing-check my-dvm --human
FlagDescription
--org <handle>Read as this org, overriding the dvmctl switch context
--humanProse 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 covers what keeps a listing there.

JSON output:

{
  "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:

StatusMeaning
listedThe 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_problemsThe route carries a listing, but some of Coinbase's checks failed. Each one is in problems
not_listedThe 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_invalidThe route answers 402, but its payment challenge fails Coinbase's checks
not_x402The route did not answer an unpaid POST with HTTP 402
unreachableCoinbase could not reach the route, or its address is not public HTTPS. A non-HTTPS route is not sent to the validator
check_unavailableThe 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:

CodeTrigger
dvm_url_unsetThe DVM has no public URL yet: it is still deploying, or its owner has no handle
x402_info_unavailableThe DVM's /v1/info could not be read. Check that it is serving, then retry
not_foundNo DVM with this slug exists in the selected org. Check the slug, or pass --org

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.

dvmctl validate
dvmctl validate --handler src/handler.ts
dvmctl validate --human
FlagDescription
--handler <path>Handler module to load (default: handler.ts, then handler.js)
--humanProse output

JSON output — success:

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

Error anchors:

CodeTrigger
missing_package_jsonNo package.json in the current directory
invalid_dvmkit_configMalformed dvmkit field (bad vmConfig or inheritSecrets pattern)

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.

dvmctl doctor
dvmctl doctor --human
FlagDescription
--humanProse 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:

{
  "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

Start a production DVM server for a handler file.

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.

FlagDescription
--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:

CodeTrigger
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 the DVMs in your current org context — the org set by switch, or your personal account when none is set.

dvmctl list

# One-off: read a shared org without changing your context
dvmctl list --org my-org
FlagDescription
--org <handle>Read as this org, overriding the dvmctl switch context
--humanProse output (columnar table)

JSON output:

{
  "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. 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 below.


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.

dvmctl info my-dvm
FlagDescription
--org <handle>Read as this org, overriding the dvmctl switch context
--humanProse output

JSON output:

{
  "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. 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 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

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.

dvmctl payout-routing my-dvm
dvmctl payout-routing my-dvm --base false --tempo false
dvmctl payout-routing my-dvm --base null --org my-team
FlagDescription
--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
--humanPrint 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

{
  "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 before declining a rail, including the effect on open Base channels.

Error codeMeaning
bad_requestA rail flag is not exactly true, false, or null, or the platform refused the update
forbiddenThe signed-in account member lacks the required admin or owner role
not_foundThe DVM or org was not found in the selected context
platform_unreachableThe platform could not be reached; follow the error hint before retrying

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.

dvmctl visibility my-dvm --hidden
dvmctl visibility my-dvm --listed
FlagDescription
--hiddenHide from discovery
--listedList in discovery
--org <handle>Target this org, overriding the dvmctl switch context
--humanProse output

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

JSON output:

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

hidden is false after --listed. Read the current value in info or list. In --human output, info shows Visibility: hidden or Visibility: listed.


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 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.

dvmctl status my-dvm

# Prose summary
dvmctl status my-dvm --human
FlagDescription
--org <handle>Read as this org, overriding the dvmctl switch context
--humanPrint a per-machine summary instead of JSON

JSON output:

{
  "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 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 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): 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, restart, ssh and env refuse with idle, and deploy fails with deploy_failed carrying the same advice. Run dvmctl resume first when you want to act on it rather than wait for traffic.

Error anchors:

CodeTrigger
not_foundThe slug doesn't exist, or the caller doesn't own it (non-owners get 404, not 403, to avoid leaking which slugs exist)
goneThe DVM has been destroyed

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.

dvmctl content-holds list my-dvm job_abc123 --org my-org
FlagDescription
--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
--humanReadable 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

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.

dvmctl content-holds place my-dvm job_abc123 --org my-org --purpose support --reason 'Investigating result' --review-due-at 2030-01-01T00:00:00Z
FlagDescription
--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
--humanReadable output

The list response 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

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.

dvmctl content-holds renew my-dvm job_abc123 hold_abc123 --org my-org --reason 'Review continues' --review-due-at 2030-02-01T00:00:00Z
FlagDescription
--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
--humanReadable output

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.

dvmctl content-holds clear my-dvm job_abc123 hold_abc123 --org my-org --reason 'Review complete'
FlagDescription
--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
--humanReadable output

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

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 instead.

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:

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 shows it under withdrawal. A DVM that owes nobody is deleted straight away.

FlagDescription
--confirmSkip confirmation prompt
--keep-dbPreserve the Postgres cluster (allows re-attachment on redeploy)
--mount-prefix <path>DVM mount path for its admin liability lookup (no trailing slash)
--humanProse output

JSON output:

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

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.

dvmctl metrics my-dvm
dvmctl metrics my-dvm --hours 48
FlagDescription
--hours <hours>Look-back window in hours (default: 24)
--org <handle>Read as this org, overriding the dvmctl switch context
--humanProse output (aggregated totals + error breakdown)

JSON output:

{
  "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

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.

dvmctl events my-dvm
dvmctl events my-dvm --since 24h
dvmctl events my-dvm --since 1h --human
FlagDescription
--since <duration>Look-back window — 30s, 5m, 2h, 7d (default: 7d)
--org <handle>Read as this org, overriding the dvmctl switch context
--humanProse 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:

{
  "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:

CodeTrigger
bad_request--since is not a valid duration (e.g. 5x)
not_foundUnknown or unowned slug

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 covers when to redeploy with --env-stdin instead.

# 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
FlagDescription
--set <KEY=value>Set an environment variable (repeatable)
--unset <KEY>Unset an environment variable (repeatable)
--humanProse output

JSON output — list:

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

JSON output — after set/unset:

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

Error anchors:

CodeTrigger
bad_request--set value missing = separator

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.

# 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
FlagDescription
--tailStream 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

--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.

# 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"
FlagDescription
--command <cmd>Run a one-shot command instead of opening an interactive shell
--machine <id>Target a specific machine (default: first running machine)
--humanPrint stdout/stderr directly instead of JSON (one-shot --command only)

JSON output (one-shot --command):

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

Error anchors:

CodeTrigger
not_a_ttyInteractive shell requested without an attached terminal (use --command)
forbiddenCaller lacks the admin role on the owning org
no_running_machineThe 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

--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 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, deploy, destroy).

# 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
FlagDescription
--machine <id>Restart a single machine (default: all running machines)
--humanPrint a machine/state summary instead of JSON

JSON output:

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

Error anchors:

CodeTrigger
forbiddenCaller lacks the admin role on the owning org
no_running_machineThe 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

--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. 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 can't do (it floors at one machine) and dvmctl destroy does far too much of.

dvmctl resume brings it back on the same image, with no redeploy.

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

dvmctl pause my-dvm

# Prose summary
dvmctl pause my-dvm --human
FlagDescription
--humanPrint a machine/state summary instead of JSON

JSON output:

{
  "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.

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:

CodeTrigger
forbiddenCaller lacks the admin role on the owning org
invalid_stateThe DVM isn't deployed (e.g. still deploying, or a failed first deploy)
suspended_by_platformThe DVM is already suspended by the platform (operator, enforcement, or reputation) — it's offline already, so there's nothing to pause
machine_stop_failedFly refused to stop a machine. The DVM is already refusing traffic; re-run pause to retry

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.

dvmctl resume my-dvm
FlagDescription
--humanPrint a machine/state summary instead of JSON

JSON output:

{
  "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:

CodeTrigger
forbiddenCaller lacks the admin role on the owning org
not_pausedThe DVM isn't suspended (nothing to resume)
suspended_by_platformThe DVM was suspended by the platform, not paused by you and not idle — only the platform can lift it
withdrawnA 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_failedFly refused to start a machine. The DVM stays offline; re-run resume to retry

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 or dvmctl deploy-status).

# 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
FlagDescription
--to <deploy-id>Roll back to a specific deploy_id (default: previous deploy)
--humanProse output

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

JSON output:

{
  "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

--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 and dvmctl ssh.

# 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
FlagDescription
--count <n>Number of machines to run (1–100, subject to your plan's cap)
--size <vm-size>Fly VM size (see below)
--humanPrint 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:

{
  "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:

CodeTrigger
bad_requestNeither --count nor --size given, count out of range, unknown size, or count below the DVM's min_machines_running
forbiddenCaller lacks the admin role on the owning org
idleThe DVM is idle-suspended (free_tier_idle) — the platform stopped its machines after a quiet spell. Run dvmctl resume first
pausedThe DVM is paused — scaling it would start machines it can't serve traffic from. Resume it first
plan_limit_exceededRequested 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:

{
  "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

Set or inspect the active org context. When an org is active, every dvmctl command runs against it: reads (list, feedback list, revenue summary, trace get) answer for that org, and 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.

# 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.

FlagDescription
--personalClear org context (run as personal builder)
--humanProse output

JSON output — show current:

{ "activeOrg": "my-org" }

JSON output — after switch:

{ "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:

{ "activeOrg": null }

Error anchors:

CodeTrigger
auth_requiredNot authenticated
bad_argumentsBoth <handle> and --personal passed

orgs

List every org membership. Use a shared-org handle with 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.

dvmctl orgs
dvmctl orgs --human
FlagDescription
--humanPrint a membership table

JSON output:

{
  "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

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.

dvmctl whoami
dvmctl whoami --human
FlagDescription
--humanPrint the identity, profile, and membership table

JSON output:

{
  "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

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, list and 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.

dvmctl handle set alice
FlagDescription
--humanProse output

JSON output:

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

handle check

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

dvmctl handle check alice
FlagDescription
--humanProse output

JSON output:

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

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.

dvmctl domains add my-dvm api.example.com
FlagDescription
--humanProse output

JSON output:

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

domains remove

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

Remove a custom domain from a deployed DVM.

dvmctl domains remove my-dvm api.example.com
FlagDescription
--humanProse output

JSON output:

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

domains verify

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

Verify that DNS is correctly configured for a custom domain.

dvmctl domains verify my-dvm api.example.com
FlagDescription
--humanProse output

JSON output:

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

domains list

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

List all custom domains configured for a DVM.

dvmctl domains list my-dvm
FlagDescription
--humanProse output

JSON output:

{
  "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

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.

These paths sit under DVMKIT_CONFIG_DIR when it is set; ~/.dvmkit is the default. See State directories.

dvmctl identity create
dvmctl identity create --force
FlagDescription
--forceOverwrite the local identity. This does not change the account’s bound pubkey; deploys with a replacement key are rejected once the account is bound
--humanProse output

JSON output:

{
  "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 prints).

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

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. 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

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.

dvmctl identity import < builder.key
dvmctl identity import --from-file ./builder.key
dvmctl identity import --from-file ./builder.key --force
FlagDescription
--from-file <path>Read the secret from a file instead of stdin
--forceReplace a different existing identity, backing up the old key first. Redeploy DVMs that used the old key
--humanProse output

JSON output:

{
  "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

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

dvmctl identity show
FlagDescription
--humanProse output

JSON output:

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

Errors with identity_missing when no identity has been created yet.


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.

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.

dvmctl lock create
dvmctl lock create --import "word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12"
dvmctl lock create --force
FlagDescription
--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
--forceReplace an existing mnemonic with a freshly generated one
--humanProse output

JSON output — generated or imported:

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

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

JSON output — an existing mnemonic was replaced:

{
  "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:

{
  "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:

CodeTrigger
invalid_mnemonicProvided --import value is not a valid 12-word BIP-39 phrase
mnemonic_existsA 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

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.

dvmctl init my-dvm --self-hosted
FlagDescription
--self-hostedMark the DVM as self-hosted (required)
--humanProse output

JSON output:

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

Error anchors:

CodeTrigger
init_requires_self_hosted--self-hosted flag not passed
invalid_handleHandle doesn't match slug pattern (3-40 lowercase alphanumeric or hyphens)
already_initializedHandle already has a canonical_dvm_id in builder.json

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.

dvmctl rotate my-dvm
dvmctl rotate my-dvm --endpoint https://my-dvm.example.com
dvmctl rotate my-dvm --sync-platform
FlagDescription
--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
--sync-platformFinish 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
--humanProse output

JSON output — rotated:

{
  "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 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:

CodeTrigger
no_builder_mnemonicNo mnemonic found — run dvmctl lock create first
dvm_not_initializedNo builder.json entry for this handle
platform_lock_sync_failedRotation is saved locally, but the platform update is unconfirmed
platform_lock_sync_pendingA prior platform update must finish before another rotation
no_pending_platform_lock_sync--sync-platform has no recorded cloud update to finish
endpoint_requiredSelf-hosted DVM without --endpoint
auth_requiredNot authenticated (needed to resolve endpoint via platform)
admin_bad_signatureDVM's lock pubkey doesn't match the derived privkey
dvm_url_unsetDVM has no platform URL yet (still deploying)

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). dvmkit Cloud does not run it for you. 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.

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"
FlagDescription
--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
--org <handle>Target this org, overriding the dvmctl switch context
--watchRun as a long-lived daemon polling on an interval
--interval <seconds>Poll cadence under --watch (default: 60, range: 10–3600)
--drains-onlySettle 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
--humanProse output

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

{
  "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:

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:

{
  "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:

CodeTrigger
no_builder_mnemonicNo mnemonic found — run dvmctl lock create first
dvm_not_initializedNo builder.json entry for this handle
no_payout_destinationNo --payout flag and no default set via dvmctl set-payout (not required under --drains-only)
auth_requiredNot authenticated (needed to resolve endpoint via platform)
admin_bad_signatureDVM's lock pubkey doesn't match the derived privkey — raised by whichever admin call hits it first, including the drain fetch
pending_batches_fetch_failedFailed to fetch pending batches from DVM admin endpoint
batches_failedOne or more batches failed during the sweep (one-shot only)
drains_unsettledOne or more credit drains went unsettled — failed, or awaiting manual settlement (one-shot --drains-only only)
drain_state_unknownThe DVM's pending drains could not be read, so nothing beyond a recovered park was settled (one-shot --drains-only only)
drain_state_unknown_sustainedThe 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_unsetDVM 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_foundNo melt for that quote is journalled for this DVM on this machine
melt_quote_resolvedThe melt for that quote is already resolved, so there is nothing to acknowledge
melt_quote_too_youngThe melt has been in flight for less than 24 hours

melt-status

Report when 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.

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
FlagDescription
--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
--humanProse output

JSON output:

{
  "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:

CodeTrigger
melt_staleOne 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 --excepted
invalid_duration--max-age is not one count and one unit (e.g. 30h, 2d)
invalid_except_handleAn --except value is not a handle. Usually the next flag was swallowed as its value, e.g. --except --max-age
dvm_not_initializedA handle was named with no builder.json entry for it
ambiguous_dvm_handleTwo builder.json entries claim that handle, either named positionally or passed to --except

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.

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
FlagDescription
--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
--confirmSubmit 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
--org <handle>Target this org, overriding the dvmctl switch context
--humanProse 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

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.

dvmctl credit blocked my-dvm
dvmctl credit blocked my-dvm --include-resolved
dvmctl credit blocked my-dvm --limit 10 --after eyJ...
FlagDescription
--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
--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-resolvedAlso list rows you already reconciled or wrote off — the audit view
--humanProse output

JSON output:

{
  "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:

CodeTrigger
invalid_limit--limit outside 1..200
admin_bad_signatureThe DVM's lock pubkey doesn't match the key derived from this mnemonic
admin_unreachableThe DVM's admin endpoint didn't answer
dvm_url_unsetNo platform URL for this handle yet — pass --endpoint

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.

dvmctl credit blocked my-dvm
dvmctl credit reconcile my-dvm 9a3f... --credit-id fnd:ab12...:topup-7
FlagDescription
--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
--org <handle>Target this org, overriding the dvmctl switch context
--humanProse output

JSON output:

{
  "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:

CodeTrigger
missing_credit_idNo --credit-id given
invoice_not_foundNo invoice for that payment hash
invoice_not_blockedThe invoice is pending, settled or expired — nothing to reconcile
invoice_already_reconciledAlready credited, to a different credit than the one named
funding_replayedSomething else already holds (named credit, payment hash) — name a different credit
invoice_not_settledThe receive wallet reports the invoice as unpaid
invoice_unknown_to_walletThe wallet has no record of that payment — you're pointed at a different wallet than the one that minted the invoice
wallet_unreachableCouldn't reach the receive wallet to confirm the payment
lightning_receive_not_configuredThe DVM has no DVMKIT_NWC_RECEIVE_URI, so it can't confirm anything
caller_mismatchThat credit belongs to another caller
currency_mismatchThat credit is denominated in a different currency
rail_mismatchThat credit was funded on another rail
currency_driftThe DVM's declared currency changed since the invoice was minted
credit_id_unavailableThe named credit is in a namespace the provider derives and doesn't exist yet

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.

dvmctl credit write-off my-dvm 9a3f... --note "caller made whole on cashu"
FlagDescription
--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
--org <handle>Target this org, overriding the dvmctl switch context
--humanProse output

JSON output:

{
  "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:

CodeTrigger
invoice_not_foundNo invoice for that payment hash
invoice_not_blockedThe invoice isn't blocked — only a blocked one can be written off

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.

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
FlagDescription
--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
--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-resolvedAlso 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-evidenceSkip the per-row chain lookups — a fast read of the queue itself
--humanProse output

JSON output:

{
  "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:

CodeTrigger
invalid_limit--limit outside 1..50
x402_settlement_unavailableThis DVM has no durable x402 batch-settlement store, so it holds no settlements to repair
admin_bad_signatureThe DVM's lock pubkey doesn't match the key derived from this mnemonic
admin_unreachableThe DVM's admin endpoint didn't answer
dvm_url_unsetNo platform URL for this handle yet — pass --endpoint

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.

dvmctl credit x402-wedged my-dvm
dvmctl credit x402-reconcile my-dvm 5e2c...
FlagDescription
--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
--org <handle>Target this org, overriding the dvmctl switch context
--humanProse output

JSON output:

{
  "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:

CodeTrigger
settlement_not_foundNo settlement with that id
settlement_not_wedgedThe settlement isn't stuck between chain and ledger — nothing to finish
settlement_not_repairableIt's a deposit, not a cooperative refund. A wedged deposit recovers when the caller re-presents it
credit_not_boundNo credit is bound to that channel any more, so there is no liability to extinguish
settlement_unbookmarkedThe settlement recorded no submission block, so the chain can't be scanned for it
settlement_not_on_chainThe chain was read and carries no matching refund. Nothing was booked
chain_unreachableThe RPC endpoint didn't answer. This says nothing about whether the money moved
settlement_racedAnother repair, or a caller retry, moved this settlement mid-reconcile. Nothing was booked twice — re-read it with x402-wedged before acting again
drain_conflictThe chain's figure and the ledger's don't match — the message names both

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.

dvmctl credit x402-write-off my-dvm 5e2c... --note "chain paid 250000, ledger owes 400000 — investigating"
FlagDescription
--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
--org <handle>Target this org, overriding the dvmctl switch context
--humanProse output

JSON output:

{
  "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:

CodeTrigger
settlement_not_foundNo settlement with that id
settlement_not_wedgedThe settlement isn't stuck between chain and ledger — only a wedged one can be written off
settlement_not_repairableIt's a deposit, not a cooperative refund

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.

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

Options:

FlagDescription
--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
--org <handle>Target this org instead of the current switch context
--limit <n>Rows to return (default 20, maximum 50)
--include-resolvedInclude completed and definitively rejected intents
--humanHuman-readable output instead of 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

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.

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

Options:

FlagDescription
--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
--org <handle>Target this org instead of the current switch context
--humanHuman-readable output instead of 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

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.

dvmctl credit tempo-losses my-dvm
dvmctl credit tempo-losses my-dvm --limit 50
FlagDescription
--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
--org <handle>Target this org, overriding the dvmctl switch context
--humanProse 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

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.

dvmctl credit tempo-wedged my-dvm
dvmctl credit tempo-wedged my-dvm --include-resolved --limit 50
FlagDescription
--limit <n>Page size (default: 20, max 50)
--after <cursor>Continue from a previous run's next_after value
--include-resolvedAlso 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-evidenceSkip 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
--org <handle>Target this org, overriding the dvmctl switch context
--humanProse output

JSON output:

{
  "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:

CodeTrigger
invalid_limit--limit outside 1..50, refused before the DVM is called
tempo_repair_unavailableThe DVM has no durable Tempo session store, so it holds no closes to repair
admin_bad_signatureThe DVM advertises a lock pubkey your mnemonic cannot derive

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.

dvmctl credit tempo-book my-dvm credit-1 drain-1 --reason "Entire refund independently returned" --evidence "Refund audit reference" --confirm
FlagDescription
--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
--confirmSubmit 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
--org <handle>Target this org, overriding the dvmctl switch context
--humanHuman-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

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.

dvmctl credit tempo-release my-dvm credit-1 drain-1 --reason "No refund was paid" --confirm
FlagDescription
--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
--confirmSubmit 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
--org <handle>Target this org, overriding the dvmctl switch context
--humanHuman-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

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.

dvmctl credit tempo-reconcile my-dvm imp:tempo:challenge-9 drain-7
FlagDescription
--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
--org <handle>Target this org, overriding the dvmctl switch context
--humanProse output

JSON output:

{
  "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:

CodeTrigger
drain_conflictThe close refunded less than the ledger debited. The message names both figures
drain_not_foundNo drain with that id on that credit
drain_not_repairableThe drain isn't a Tempo cooperative close — this verb repairs those only
drain_not_wedgedThe drain was released, so no close is waiting to be booked
close_not_confirmedNo confirmed cooperative close on this drain, so there is no receipt to book against
close_refund_unreportedThe close reference names no transaction receipt, so the chain states no refund figure
chain_unreachableThe Tempo RPC could not be read — retryable, and it says nothing about what the close paid
tempo_repair_unavailableThe DVM has no durable Tempo session store

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.

dvmctl credit tempo-write-off my-dvm imp:tempo:challenge-9 drain-7 --note "chain refunded 390000 of 400000; made good by transfer 0x…"
FlagDescription
--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
--org <handle>Target this org, overriding the dvmctl switch context
--humanProse output

JSON output:

{
  "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:

CodeTrigger
drain_not_foundNo drain with that id on that credit
drain_not_repairableThe drain isn't a Tempo cooperative close
drain_not_wedgedThe 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

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.

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>
FlagDescription
--limit <n>Page size (default: 20, max 50)
--after <cursor>Continue from next_after, keeping the same --all setting
--allAudit 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
--org <handle>Target this org, overriding the dvmctl switch context
--humanHuman-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:

{
  "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

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.

dvmctl credit tempo-close-report-retry my-dvm close-test
dvmctl credit tempo-close-report-retry my-dvm close-test --human
FlagDescription
--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
--org <handle>Target this org, overriding the dvmctl switch context
--humanHuman-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:

{
  "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

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.

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
FlagDescription
--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
--org <handle>Target this org, overriding the dvmctl switch context
--humanHuman-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:

{
  "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:

CodeTrigger and next step
tempo_close_report_conflictHTTP 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_foundHTTP 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_foundHTTP 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_unavailableHTTP 503: hosted settlement reports are not configured. Configure them on a DVM using SDK 0.10.0 or later, then retry.
invalid_requestHTTP 400: malformed JSON, ID, or note. Correct the request; the CLI trims IDs and validates notes locally.
invalid_queryHTTP 400: invalid page query. Use the documented page size, cursor, and audit flag.
invalid_limitLocal page size outside 1..50. Use a valid limit and follow next_after.
invalid_noteLocal missing, empty, or oversized note. Supply 1–2000 characters after trimming.
invalid_obligation_idLocal empty ID. Copy the ID from the list command.
admin_bad_signatureHTTP 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

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.

dvmctl credit liability scrape cast scribe narrate
dvmctl credit liability scrape --hub-sats 250000 --human
FlagDescription
--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
--org <handle>Target this org, overriding the dvmctl switch context
--humanProse output

JSON output:

{
  "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:

CodeTrigger
invalid_hub_balance--hub-sats was not a whole number of satoshis
admin_bad_signatureThe DVM's lock pubkey doesn't match the key derived from this mnemonic
admin_unreachableThe DVM's admin endpoint didn't answer
dvm_url_unsetNo platform URL for this handle yet, so pass --endpoint

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.

dvmctl credit drains-owed my-dvm
dvmctl credit drains-owed my-dvm --human
FlagDescription
--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
--org <handle>Target this org, overriding the dvmctl switch context
--humanProse output

JSON output:

{
  "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:

CodeTrigger
admin_bad_signatureThe DVM's lock pubkey doesn't match the key derived from this mnemonic
admin_unreachableThe DVM's admin endpoint didn't answer
dvm_url_unsetNo platform URL for this handle yet — pass --endpoint

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.

dvmctl credit drains-owed my-dvm
dvmctl credit drain-settle my-dvm imp:x402:0xabc... drain-7 --tx 0xfeed... --note "sent from ops wallet"
FlagDescription
--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
--org <handle>Target this org, overriding the dvmctl switch context
--humanProse output

JSON output:

{
  "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:

CodeTrigger
missing_transactionNo --tx given
drain_not_foundNo drain with that id on that credit
drain_conflictThe drain is parked or picked_up — a cashu refund, which melt-pending settles
channel_bound_drainThe 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_stateThe drain is not pending (already released, or a cashu row still awaiting its park)
admin_bad_signatureThe DVM's lock pubkey doesn't match the key derived from this mnemonic
dvm_url_unsetNo platform URL for this handle yet — pass --endpoint

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.

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
FlagDescription
--skip-preflightSkip the LNURL pre-flight check (use when the provider is temporarily down)
--self-hostedTarget local state created by dvmctl init --self-hosted; cannot be combined with --org
--org <handle>Target this org, overriding the dvmctl switch context
--humanProse output

JSON output:

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

Error anchors:

CodeTrigger
dvm_not_initializedNo builder.json entry for this handle

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.

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 @-
FlagDescription
--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
--humanProse 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:

{
  "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

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. 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.

dvmctl feedback posture
dvmctl feedback posture off
dvmctl feedback posture ask
FlagDescription
--humanProse output

JSON output:

{ "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

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

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
FlagDescription
--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)
--humanProse output

JSON output:

{
  "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.


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

--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.

dvmctl feedback enable my-dvm
FlagDescription
--humanProse output

JSON output:

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

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.

dvmctl feedback disable my-dvm
FlagDescription
--humanProse output

JSON output:

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

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.

dvmctl trace get 4bf92f3577b34da6a3ce929d0e0e4736
dvmctl trace get 4bf92f3577b34da6a3ce929d0e0e4736 --human
dvmctl trace get 4bf92f3577b34da6a3ce929d0e0e4736 --human --no-color
FlagDescription
--org <handle>Read as this org, overriding the dvmctl switch context
--humanRender as a waterfall instead of JSON
--no-colorDisable 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:

{
  "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

--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.

dvmctl db connect my-dvm
dvmctl db connect my-dvm --machine 1234abcd
FlagDescription
--machine <id>Broker through a specific Fly machine (default: first running machine)
--humanPrint 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:

CodeTrigger
psql_not_foundpsql not installed locally
no_running_machineDVM has no running machine to broker through

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 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.

dvmctl db proxy my-dvm
dvmctl db proxy my-dvm --port 15433
dvmctl db proxy my-dvm --human
FlagDescription
--port <n>Local port to bind (default: an OS-assigned free port)
--machine <id>Broker through a specific Fly machine (default: first running machine)
--humanHuman-readable output instead of JSON

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

{
  "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:

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:

CodeTrigger
invalid_port--port is not an integer in 1–65535
local_listener_failedThe local port is already in use (or otherwise unbindable)
no_running_machineDVM has no running machine to broker through
db_not_provisionedDVM has no managed Postgres
not_foundUnknown slug, or you don't own the DVM

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.

dvmctl secrets list cast
FlagDescription
--humanProse output

JSON output:

{
  "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

--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.

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
FlagDescription
--create-orgCreate 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)
--humanProse output

JSON output:

{
  "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

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

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
FlagDescription
--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)
--humanProse output

JSON output:

{
  "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 and 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

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

dvmctl revenue events
dvmctl revenue events --from 2026-05-01 --to 2026-05-27 --rail cashu --limit 100
dvmctl revenue events --org my-org
FlagDescription
--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)
--humanProse output

JSON output:

{
  "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 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.


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.

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
FlagDescription
--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

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 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.

dvmctl billing status
dvmctl billing status --org my-org
FlagDescription
--org <handle>Read this org's billing account, overriding the dvmctl switch context
--humanPrint the same JSON, indented, on stderr and without trace_id

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

{
  "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, resume, or 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 and 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.

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

CodeTrigger
billing_version_unsupportedThe platform returned a billing-state version this dvmctl does not understand. Upgrade dvmctl before reading it
billing_not_availableThe 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_foundThe invoice, quote, or top-up ID does not exist in this account
billing_scope_unsupportedA route that bills only the authenticated key's own account was given an org (see billing checkout)
billing_failedAny other refusal without its own code. When the platform sent no message, the message names the HTTP status

billing budget get

Read the account's monthly hosting budget and the version you pass to 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.

dvmctl billing budget get
dvmctl billing budget get --org my-org
FlagDescription
--org <handle>Read this org's budget, overriding the dvmctl switch context
--humanPrint the same JSON, indented, on stderr and without trace_id

JSON output:

{
  "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; 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:

CodeTrigger
budget_not_availableMonthly budgets are not available to this account, and no budget is set
not_foundThe org does not exist or you are not a member

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, so two people editing at once cannot silently overwrite each other, and an idempotency key you save before running it.

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
FlagDescription
--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
--humanPrint the same JSON, indented, on stderr and without trace_id

JSON output: the same shape as 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:

CodeTrigger
bad_requestThe limit is not a positive whole number of cents or none, --expected-version is not a whole number, or the key is malformed
budget_conflictThe budget changed since you read it, or the key was used with different arguments. Run billing budget get again before deciding
budget_below_included_creditThe limit is at or below the plan's included hosting credit
budget_paid_plan_requiredThe account is not on a paid plan
budget_plan_unsupportedEnterprise plans set hosting limits by contract. Contact dvmkit
budget_not_availableMonthly budgets are not available to this account
budget_actor_refusedYou are not an owner or admin, or you used an org API key

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 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. Only state: "paid" adds funds.

dvmctl billing topup 2500 --idempotency-key topup-2026-10-15-a
FlagDescription
--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
--humanPrint the same JSON, indented, on stderr and without trace_id

JSON output:

{
  "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:

CodeTrigger
bad_requestThe amount is below 1000 or not a whole number of cents, or the key is malformed
hosting_topup_conflictThe key was already used with a different amount. Use a new key
hosting_topup_unavailableThe platform cannot create a hosting top-up right now
forbiddenWith 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_availableHosting top-ups are not offered on this platform, which today includes dvmkit's hosted platform

billing topup-status

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

dvmctl billing topup-status 0f6e2a91-3c47-4d8b-b1e5-7a2c9d4e6f80
FlagDescription
--org <handle>The org the top-up belongs to, overriding the dvmctl switch context
--humanPrint the same JSON, indented, on stderr and without trace_id

JSON output: the same shape as billing topup, with the current state. After paid, the funds appear under prepaid in billing status.

Error anchors:

CodeTrigger
not_foundNo top-up with this ID in this account
hosting_topup_unavailableThe platform could not check the top-up right now. Retry
billing_not_availableHosting top-ups are not offered on this platform

billing invoice

Check a Bitcoin Lightning subscription invoice once, by the invoice_id that billing checkout --rail lightning 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).

dvmctl billing invoice 7d3b5e10-92a4-4c6f-8e17-b0c2d9f41a36
FlagDescription
--org <handle>Refused with billing_scope_unsupported: this route bills only the key's own account
--humanPrint the same JSON, indented, on stderr and without trace_id

JSON output:

{
  "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"]
  }
}
statusMeaning
pendingNo payment recorded yet. Check again
payment_receivedThe payment arrived and the plan is being applied. Do not pay again; check again later
payment_recoveryThe 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
paidThe plan is active
expiredThe 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:

CodeTrigger
not_foundNo invoice with this ID in this account
billing_scope_unsupportedAn org was selected, by --org or by dvmctl switch
lightning_errorThe platform could not check the Lightning invoice. Retry

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.

dvmctl billing checkout builder-monthly --rail stripe
dvmctl billing checkout builder-monthly --rail lightning --months 3
FlagDescription
--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
--humanPrint the same JSON, indented, on stderr and without trace_id

JSON output: --rail stripe

{
  "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

{
  "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 afterwards. For Lightning, the invoice expires at expiresAt (Unix milliseconds); check it with 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, 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:

CodeTrigger
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_unsupportedLightning checkout with an org selected, by --org or by dvmctl switch
payment_receivedA Lightning payment has already been received and is being applied. Do not pay again
lightning_errorThe platform could not create the Lightning invoice
stripe_errorThe platform could not create the card checkout session for an org
forbiddenLightning 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_availableThis platform does not offer checkout on that rail

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. 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.

dvmctl billing plan quote studio-monthly --request-key studio-upgrade-2026-10
FlagDescription
--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
--humanPrint the same JSON, indented, on stderr and without trace_id

JSON output:

{
  "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 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:

CodeTrigger
plan_changes_unavailablePlan changes are not enabled on this platform
settled_term_unavailableThe account has no settled paid term to change from. Use billing checkout
billing_account_missingThe key's account has no billing account yet, so it has no plan to change
invalid_planThe target plan does not exist or is not on sale
conflicting_request_keyThe request key was already used for a different plan
plan_change_ineligibleYour usage or resources exceed what the target plan allows
usage_evidence_incompleteThe platform cannot yet price the change from complete usage records. Retry later
billing_scope_unsupportedAn org was selected, by --org or by dvmctl switch

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.

dvmctl billing plan purchase 2e8d7c64-1b9f-4a35-8c02-6d4a9e3f17b8 --rail lightning
FlagDescription
--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
--humanPrint the same JSON, indented, on stderr and without trace_id

JSON output: --rail lightning

{
  "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.

Error anchors:

CodeTrigger
bad_request--rail is missing or not stripe or lightning
not_foundNo quote with this ID in this account
downgrade_requires_scheduleThe quote is a renewal downgrade, which the platform schedules for the end of the term
settled_term_unavailableThe current paid term changed or ended since the quote
plan_change_ineligibleUsage or resources now exceed the target plan
usage_evidence_incompleteThe platform cannot confirm complete usage records. Retry later
payment_receivedA Lightning payment has already been received and is being applied. Do not pay again
rail_unavailableThis platform does not offer that payment rail
plan_changes_unavailablePlan changes are not enabled on this platform
billing_scope_unsupportedAn org was selected, by --org or by dvmctl switch

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.

dvmctl billing plan status 2e8d7c64-1b9f-4a35-8c02-6d4a9e3f17b8
FlagDescription
--org <handle>Refused with billing_scope_unsupported; plan changes bill only the key's own account
--humanPrint 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:

CodeTrigger
not_foundNo quote with this ID in this account
plan_changes_unavailablePlan changes are not enabled on this platform
billing_scope_unsupportedAn org was selected, by --org or by dvmctl switch

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 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. 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 does. Database connections through it end at the recovery deadline, but the command itself keeps running until you interrupt it (Ctrl-C or SIGTERM).

dvmctl trial export my-dvm
dvmctl trial export my-dvm --port 15433
FlagDescription
--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
--humanPrint the same JSON, indented, on stderr and without trace_id

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

{
  "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:

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:

CodeTrigger
trial_export_unavailableThe 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_closedThe 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_failedThe local port is already in use (or otherwise unbindable)
no_running_machineNo machine is available to broker through
not_foundUnknown slug, or you don't own the DVM

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 before the seven-day recovery deadline, and wait until billing status shows it active. If you bought the plan before the deadline, you can run restore after it.

dvmctl trial restore my-dvm
FlagDescription
--org <handle>Resolve the slug and read billing as this org, overriding the dvmctl switch context
--humanPrint the same JSON, indented, on stderr and without trace_id

JSON output:

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

When the platform refuses, dvmctl reads 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:

CodeTrigger
purchase_requiredThe trial has not been converted to a paid plan. The error object names the card (stripe) and Bitcoin Lightning (lightning) checkout routes
trial_restore_blockedThe 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_closedThe seven-day recovery window ended before a paid plan was bought. This does not by itself mean the DVM has been deleted
trial_restore_unavailableThis DVM has no ended trial with data to restore
not_foundUnknown slug, or you don't own the DVM

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.

dvmctl api-keys list
FlagDescription
--humanProse output

JSON output:

{
  "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

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.

dvmctl api-keys create
dvmctl api-keys create --label ci-runner
FlagDescription
--label <text>Optional label to identify the key in dvmctl api-keys list
--humanProse output

JSON output:

{
  "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

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

dvmctl api-keys revoke ak_0e4220d396ef48c8
FlagDescription
--humanProse output

JSON output:

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