Quickstart
Install the CLI and the dvm agent skill, try a free call, then fund a wallet for paid work.
This is the one procedure that lives in the docs, because it runs before your agent has the skill that carries every other procedure. From here on the loop lives in the skill, and the pages under Understand explain what is happening underneath it.
Reading this as a human rather than handing it to an agent? Every command below runs the same way in your own terminal. Append --human to any of them and you get prose instead of JSON.
This is the caller quickstart. Building a service instead? Start with the builder quickstart.
1. Install the CLI
npm install --global @dvmkit/dvm-cliThe command it installs is dvm.
It needs Node.js 22 or later. Check with node --version; if it is older or missing, install the current LTS release from nodejs.org.
2. Install the agent skill
The CLI is the tool; the skill is the instructions for using it. It carries the runtime loop, the failure modes, and the rules about what is safe to relay. Install it before the first job.
Copy the complete bundled skill directory so the skill can load its task procedures. For Claude Code:
mkdir -p ~/.claude/skills
cp -R "$(npm root --global)/@dvmkit/dvm-cli/skills/dvm" ~/.claude/skills/Keep the skill and CLI on the same package version. After npm update --global @dvmkit/dvm-cli, copy the skill again.
This example is for Claude Code. Codex loads the entry file from ~/.codex/skills/dvm/SKILL.md (or $CODEX_HOME/skills/dvm/SKILL.md), and Agent Skills-compatible harnesses use ~/.agents/skills/dvm/SKILL.md. Use the destination your harness recognizes; none of these harnesses is required to use the CLI. Agent setup has the full matrix, plus the network allowlist you need if the commands below fail with a network error inside a sandboxed coding agent.
3. Initialize config
dvm initCreates ~/.dvm/config.json and a default signing identity.
4. Try it before you fund a wallet
Your signing identity is enough to search, get a quote, list narrate's voices, and list your cast feeds. No wallet is needed for these calls. The same catalog dvm search ranks is also readable without the CLI at /explore.md.
dvm search "transcription"
dvm quote -d dvmkit--narrate/synthesise --data '{"quality":"balanced","input":{"text":"hello world"}}'
dvm request -d dvmkit--narrate/list-voices --param quality=balanced
dvm request -d dvmkit--cast/list-feeds --data '{}'The quote gives the price of generating speech without generating or paying for it. The free requests return matching voices and your feed list. When payload_in is "messages", follow the response's next_step_hint to read the result.
5. Fund a wallet for paid work
dvm wallet setupThat lists the four funding routes, none of them the default: US dollars as USDC.e on the Tempo network, US dollars as native USDC on Base, a Lightning wallet you already run connected as a self-refilling float, and privacy-focused ecash. Each row names who it suits, the command that starts it, and the facts for this machine: the exact token, network, and address once a route is connected. Two of the four never ask you to hold Bitcoin.
You can also skip the wallet and fund one provider's prepaid credit by card. With CLI 0.19.0 or later, callers anywhere can pay a Stripe-hosted checkout link when the provider offers it. Stripe Link is another option for agents in the US and Canada. Each top-up needs your approval and must meet the provider's advertised card minimum. Unspent card credit goes back to the card, less its share of Stripe's processing fee; see paying by card.
Pick by where your money already lives: the funding guide settles the route in three questions and walks the money across, exchange withdrawals included. The Cashu row's setup command is dvm wallet init. Before either of its verification commands, add the primary accepted mint:
dvm wallet init
dvm wallet mint-add https://mint.coinos.ioThe funding guide's Cashu mint table names the accepted fallback. If you have not picked a service yet, $1 is a practical first top-up. If you have, run dvm quote before funding and raise the amount when the live price or ceiling is higher. The funding guide explains the arithmetic and Cashu's mint-specific minimum. Then finish the selected route, send the amount, and confirm it arrived. Cashu runs both checks below; the other three routes run only dvm wallet balance:
dvm wallet mint-health
dvm wallet balanceA route that generates keys says what to back up and never prints a secret by default; wallets explains what you are trusting on each route, and every amount you type in a command stays quoted ('$5.00') so the shell cannot eat it.
6. Find a service
dvm search "transcription"Every result carries an identifier that passes straight to the next command. One row per capability, so the identifier names both: dvmkit--scribe/transcribe is the transcribe capability of the dvmkit--scribe DVM. Save a provider you will reuse with dvm fav add. That command takes the row's endpoint, not the identifier.
7. Quote before you commit
dvm quote -d dvmkit--scribe/transcribe --param audio_url=https://example.com/audio.mp3Swap the example URL for your own audio. The DVM checks the URL before quoting, so one that doesn't resolve answers source_unreachable instead of a price.
upfront.amount and upfront.currency are the budget number to put in front of your user before anything is spent. Use --param key=value, repeatable, for DVMs with an input schema, or -i "<text>" for the ones that take plain text. dvm describe <identifier> says which a provider expects.
A quote carries more than a price: what happens to your money if the job fails, whether the DVM offers prepaid credit, and when the quote expires. Payments covers what each field means.
8. Make the paid call
dvm request -d dvmkit--scribe/transcribe --param audio_url=https://example.com/audio.mp3 \
--auto-pay --budget '$0.50'--auto-pay pays without stopping to ask, but not up to the whole budget: unless you say otherwise it auto-approves a single charge only up to 20% of --budget and asks about anything larger. Set that per-charge threshold yourself with --auto-pay-below <amount>, which carries consent on its own and needs no --auto-pay.
Two fields drive everything after this.
payload_in says where the work actually is. "summary" means the summary string is the whole result. "messages" means you must run dvm messages <job-id> and read the artifacts, because relaying the summary alone loses the output.
next_action says what to do next. null means done. Otherwise it is respond (the provider asked a question), pay (a mid-job payment is due), poll (still working), refund (money is coming back to you), or one of the setup and recovery actions, which arrive carrying the exact command to run. Each one explains itself in the response; the dvm CLI reference has the full taxonomy and every shape.
Next steps
- How it works: what actually happened in steps 6 to 8.
- Wallets: where the money lives, and the other three ways to fund it.
- Budgets: what your agent can spend without asking you first.
dvmCLI reference: every command, flag, JSON shape, and error code.