CLI reference
The tx-manifest-wallet CLI (txmanifest_wallet)
executes manifest actions interactively. This book invokes it as txw <subcommand>
(an alias for tx-manifest-wallet — see Installing the CLI for
the install options). Manifest paths are relative to your current directory.
Commands
validate <manifest>
Statically check a manifest and report obvious problems — without touching the
network, wallet, or filesystem. Catches unknown utxo_type references, outputs
missing a required amount_sat, duplicate input and output ids, malformed
destinations, hooks writing to targets nothing declares, unreferenced UTXO
types, and clear-signing text a wallet could not render. Exits non-zero if any
errors are found (warnings alone still exit zero).
Note that a misspelled or unknown field does not reach validate: it is a hard
parse error, raised by any command that reads the manifest at all. So is a
manifest_version from a different format revision.
txw validate examples/p2pk/txmanifest.json
Future versions will add deeper checks (compiling SimplicityHL leaves, verifying formula references resolve).
describe <manifest>
Explore a manifest interactively. Presents a menu of the contract's overview,
contract templates, and standalone actions; drill into any template to list its
fields and actions, and into any action to see its params, inputs, outputs and
witnesses — without reading the raw JSON. When stdout is not a terminal (e.g.
piped to a file or less), it prints a full non-interactive dump of everything
instead.
txw describe examples/lending/txmanifest.json
run <manifest> <action>
Walk through the lifecycle of a manifest action interactively: resolve params and inputs, validate, build the PSET, dry-run the Simplicity covenant, sign, and broadcast.
| Flag | Default | Purpose |
|---|---|---|
--network <net> | config default_network | Network for param-file auto-discovery. |
--params <file> | — | Flat JSON string→string overrides (takes precedence over auto-discovered file). |
--wallet <file> | wallet.json | Wallet for input selection and signing. |
--data-dir <dir> | platform data dir | Where wallet state is persisted. |
--instance <file> | none | Instance file to read (template field values locked at deploy). Never auto-discovered — pass it for any action that reads instance.*. |
--state <file> | none | State file to read, locating covenant UTXOs. Never auto-discovered — pass it for any action that spends one. |
--instance-out <file> | <stem>.instance.N.json | Where a constructor writes the new instance. |
--state-out <file> | <stem>.state.N.json | Where the run writes state after broadcast. |
--input <id>=<txid>:<vout> | — | Pin one input to a specific outpoint. Repeatable; outranks the state file. |
--manual-inputs | off | Prompt for every input instead of auto-selecting. |
--export-pset <file> | — | Write signed PSET/tx to a file instead of broadcasting. |
--debug-jets | off | Print every Simplicity jet call during dry-runs. |
Neither
--instancenor--statehas a default. Leave them off and the run starts with no instance and no state — which is right for a first action, and wrong for every action after it. Outputs are written to a fresh numbered file (txmanifest.state.1.json, then.2.json, …) so a run never overwrites the file it read. Pass the file the previous run wrote.Every run also appends to
<stem>.state.history.json, which is not versioned.
create-wallet
Create a new wallet JSON file. --out <file> (default wallet.json),
--mainnet <bool> (defaults to config network).
info
Show wallet fingerprint, master xpub, oracle pubkey, and a receive address.
--wallet <file>.
sync
Sync wallet state against an Esplora server and print the balance.
--wallet <file>, --esplora <url>, --data-dir <dir>.
get-balance
Print the last known balance from persisted state (no network call).
--wallet <file>, --data-dir <dir>.
prepare <manifest> <action>
Ensure the wallet has the UTXOs an action needs; broadcasts a split transaction if
not. --wallet, --esplora, --data-dir, --split-amount <sats> (default
10000).
split
Split a wallet asset into N equal UTXOs and broadcast. -n/--count <N>,
--asset <hex|lbtc> (default lbtc), --amount-each <sats> (optional — splits
balance evenly if omitted), --wallet, --esplora, --data-dir.
config [key] [value]
With no args, print config. With key value, set it. Valid keys:
default_network (testnet|mainnet), default_esplora (URL).
Typical session
txw config default_network testnet
txw config default_esplora https://blockstream.info/liquidtestnet/api
txw create-wallet --out wallet.json
txw info --wallet wallet.json # → fund this address
txw sync --wallet wallet.json
txw prepare examples/p2pk/txmanifest.json Pay --wallet wallet.json
txw run examples/p2pk/txmanifest.json Pay --network testnet --wallet wallet.json