ada-dev-cli

A Cardano development CLI. Run a local devnet, fund a wallet, check balances, transfer ADA and native assets, and settle two-party atomic swaps — all from the terminal.

It is a developer instrument, not a consumer wallet: it works on devnet, preview and preprod, and refuses mainnet outright.

Built for two audiences: developers starting a Cardano project who want a funded wallet on a local chain in under five minutes, and AI agents (Claude Code, Cursor, any MCP client) using the same primitives through a built-in MCP server.

Status: working, not yet released. Wallets, balances, funding, transfers, native assets, atomic swaps, the devnet lifecycle, chain inspection and Aiken contracts all work, verified against a local devnet and against preprod. Not on npm yet — see Install below. ada help --json reports which commands are implemented; tasks/IMPLEMENTATION.md is the full checklist.

Install

Not on npm yet, so link it from a clone:

git clone https://github.com/kuiralabs/ada-dev-cli
cd ada-dev-cli
npm install
npm run build     # the global binary runs the bundle, not the sources
npm link          # puts `ada` on your PATH

Then ada status should answer. To remove it: npm unlink -g ada-dev-cli.

Working on the code? npx tsx src/ada.ts <command> runs the sources directly, so you skip the rebuild. The linked ada keeps running the last npm run build until you run it again — worth knowing before you wonder why a change had no effect.

Related MCP server: agenti

Why this exists

Doing anything on Cardano takes four separate things: a chain to talk to, a way to ask it questions, somewhere to keep keys, and a way to build transactions. Each is a different project with its own interface, and each is good at its job — but getting from nothing to "I sent a transaction and I can see why it failed" means learning all four first.

This is one interface over them. It composes rather than reimplements, and fills the gaps nobody covers: transfers between arbitrary addresses, native-asset bundles, atomic swaps, and a single agent-callable surface across the lot.

docs/STACK.md is the map — what each project in the stack is, what it is for, and which of the two APIs a local chain serves answers which kind of question. Worth ten minutes before writing any Cardano code, whether or not you use this tool.

Planned commands

Contracts

Aiken validators, from compiling one to spending what it guards.

Run ada help --json for the current list — it marks which commands are implemented, and ada help <command> lists every flag that command takes.

The address moves every time you edit. A validator has no identity apart from its compiled code — the address is a hash of it — so any source change puts your contract somewhere else, and anything locked at the old address cannot be spent by the new build. Nothing says so on its own: contract address reports the new one happily and the funds at the old one stop being mentioned. ada dev watches for saves, reruns the tests, and says when the address changed and how much was left behind.

Publish a script once, point at it after. ada contract publish writes a CIP-33 reference script — the validator's bytes parked in a UTxO — and ada contract unlock --script-ref <ref> spends by pointing at that copy instead of carrying one. On the hello-world example that is 574 bytes against 342, and the saving scales with the script: for a large validator it decides whether the transaction fits at all.

A validator that keeps state. unlock can do more than drain a script. --continue <ada> with --continue-datum <json> returns value to the same address under a new datum, which is what makes a validator a state machine rather than a one-shot escrow — an auction taking a higher bid, a vesting schedule releasing one tranche, an order partially filled. --pay <addr>:<ada> covers the other half of that shape: an output to someone who is not the spender, such as the bidder being refunded. Change cannot express that, because change all goes back to one address.

# outbid the standing leader: new bid to the script, refund to whoever it displaces
ada contract unlock --tx-in <ref> --redeemer '{"alternative":0,"fields":[]}' \
  --continue 40 --continue-datum '{"alternative":0,"fields":["<bidder-hash>",40000000]}' \
  --pay <displaced-addr>:25 --valid-until <slot> --yes

--mint <name>:<qty> builds a spend and a mint in one transaction, for validators that release funds only when a token is issued alongside.

Public testnets need no setup. --network preprod or --network preview works on any read command with no account and no API key, via the free community API. Set ADA_BLOCKFROST_KEY if you prefer Blockfrost or want higher rate limits.

Unknown flags are an error. A flag a command does not implement stops it rather than being ignored, and the message names the closest one that exists. This catches the mistake worth catching — --wallett alice used to report the active wallet's balance and call it a success — but it means a script that passes flags defensively will now fail on the commands that take neither: ada help <command> lists exactly what each one accepts.

Installing provides two binaries: ada and ada-mcp.

How it works

• docs/STACK.md — start here. What every piece in the stack is, who makes it, and why it is there. Yaci DevKit, Yaci Store, MeshJS, cardano-node, and the two APIs the local chain serves.

• docs/ARCHITECTURE.md — how our own code is arranged, and a command traced end to end.

• docs/DEVNET.md — running the local chain, and diagnosing it when it will not start.

Built on

Deliberately composed rather than written from scratch:

• MeshJS — wallet, transaction building, native assets, multi-signature co-signing. The headless server-side wallet is what makes a CLI possible without a browser extension.

• Yaci DevKit — the local devnet: one-second blocks, a faucet, a bundled Blockfrost-compatible indexer, and multi-node mode for rollback testing.

• cardano-address — derivation and address ground truth.

MCP server

ada-mcp will expose the wallet operations as tools, so an agent can fund a wallet, send a transfer, and read back the result without a human copying commands between a terminal and a chat window. Not built yet — stage 3.

Yaci DevKit ships its own MCP server for chain operations — devnet lifecycle, faucet, rollback. The two are complementary and do not overlap: theirs owns the chain, this one owns the wallet.

License

Apache-2.0