CLI reference (v0.11)

RGB v0.11 line (rgb-cmd 0.11.1)

This page covers the rgb binary from the rgb-cmd crate (RGB Protocol Association). The v0.12 binary has the same name but different commands: see CLI reference (v0.12) and Two RGB lines.

This reference was generated from rgb --help and rgb <command> --help of the pinned binary (cached in scripts/cli-help/B.json), and from the clap definitions in cli/src/command.rs of rgb-protocol/rgb-api 0.11.1. The general wallet commands (list, default, create, address, finalize, extract) come from bp-wallet 0.11.1-alpha.2 (src/cli/command.rs).

cargo install --locked rgb-cmd --version 0.11.1
rgb --version

rgb --version prints rgb-cmd 0.11.1.

rgb-cmd keeps watch-only wallets and does the RGB work. It doesn't sign: sign PSBTs with a wallet that holds the keys, such as bp-hot sign from bp-wallet, as rgb-sandbox does. For applications, use rgb-lib instead of the CLI.

Global options

All of these options can be given before or after the command.

Option	Env	Default	Meaning
`-d, --data-dir <DIR>`	`LNPBP_DATA_DIR`	`~/.lnp-bp`	Data directory
`-n, --network <NET>`	`LNPBP_NETWORK`	`testnet3`	Network (`bitcoin`, `testnet3`, `testnet4`, `signet`, `regtest`)
`--no-network-prefix`	—	off	Don't add the network subdirectory to `--data-dir`
`-w, --wallet <NAME>`	—	the default wallet	Use a named wallet
`-W, --wallet-path <PATH>`	—	—	Use the wallet at this path
`--wpkh <DESCRIPTOR>`	—	—	Use a `wpkh(KEY)` descriptor given on the command line
`--tapret-key-only <DESCRIPTOR>`	—	—	Use a `tapret(KEY)` descriptor given on the command line
`--electrum[=<URL>]`	`ELECRTUM_SERVER` (sic)	bare: `example.com:50001`	Electrum indexer
`--esplora[=<URL>]`	`ESPLORA_SERVER`	bare: `https://blockstream.info/{network}/api`	Esplora indexer
`--mempool[=<URL>]`	`MEMPOOL_SERVER`	bare: `https://mempool.space/{network}/api`	Mempool indexer
`--sync`	—	off	Sync the wallet with the indexer before the command runs
`-H, --from-height <N>`	—	—	Check witness transactions for re-orgs starting at this height
`-v, --verbose`	—	—	More output. Repeat it for more
`-V, --version`	—	—	Print the version

The = is required with the indexer options: write --electrum=localhost:50001. A bare --electrum falls back to the placeholder example.com:50001, so always give a URL.
The Electrum environment variable is misspelt ELECRTUM_SERVER (bp-wallet 0.11.1-alpha.2, src/cli/opts.rs:59).
Any command that syncs (--sync, --wpkh, --tapret-key-only, or create) needs exactly one indexer option. Otherwise it fails with Error: no blockchain indexer specified; use either --esplora --mempool or --electrum argument.
Data goes in <data-dir>/<network>, for example data0/regtest, which contains stash.dat, state.dat, index.dat and rgb.toml. Named wallets are subdirectories of the same directory. There is no init command: the directory is created on first use. Unless rgb.toml there holds a valid config, each command first prints Unable to find or parse config file; using config defaults. This is harmless.

Commands

Command	Purpose
`list`	List named wallets
`default`	Get or set the default wallet
`create`	Create a named wallet
`address`	Generate wallet addresses
`utxos`	Show the wallet's UTXOs and balance
`taprets`	List the wallet's known tapret tweaks
`schemata`	List known schemas
`contracts`	List known contracts
`import`	Import a kit (schemas) or a contract consignment
`export`	Export a contract
`armor`	Convert a binary RGB file to ASCII armour
`issue`	Issue a contract from a YAML description
`state`	Show a contract's state
`history`	Show a contract's operation history
`invoice`	Create an invoice
`transfer`	Create a transfer: consignment + PSBT
`prepare`	Low-level: build the transfer PSBT
`consign`	Low-level: build the consignment for a prepared PSBT
`validate`	Validate a transfer consignment
`accept`	Validate and accept a transfer consignment
`finalize`	Finalize a signed PSBT, optionally publish
`extract`	Extract the signed transaction from a PSBT
`inspect`	Dump any RGB file as YAML
`dump`	Debug-dump the whole stash

There is also a hidden reconstruct command, which rebuilds a consignment from YAML.

Wallet commands

list

rgb list. Lists named wallets.

default

rgb default [NAME]. Prints the default wallet, or sets it to NAME.

create

rgb [--wpkh <DESCRIPTOR> | --tapret-key-only <DESCRIPTOR>] create <NAME>. Saves a descriptor as a named wallet and syncs it, so it needs an indexer. The descriptor is an account xpub with origin and keychains, for example [598d26fe/86h/1h/0h]tpubDCwK…/<0;1;9>/* as in rgb-sandbox.

rgb -n regtest --electrum=localhost:50001 -d data0 create --wpkh "$descriptor_0" issuer

Example output, from the rgb-sandbox README:

Loading descriptor from command-line argument ... success
Syncing keychain 0 .......... keychain 1 .......... keychain 9 .......... success
Saving the wallet as 'issuer' ... success

address

rgb address [-k KEYCHAIN] [-1] [-i INDEX] [-D] [-C COUNT]. Generates addresses.

-k, --keychain <N>: a custom keychain. rgb-sandbox uses -k 9.
-1, --change: the change keychain.
-i, --index <N>: a custom address index.
-D, --dry-run: don't advance the last-used index.
-C, --count <N>: how many addresses to generate (default 1).

utxos

rgb utxos [--sync]. Shows the wallet's UTXOs with height, amount and outpoint, then the total balance.

taprets

rgb taprets. Prints <witness txid>\t<tapret tweak> for each tapret commitment the stash knows.

Back up tapret tweaks and the stash

To spend an output that carries a tapret commitment, you need the tweak, and the seed alone doesn't hold it. Losing the data directory also loses the RGB state. Back up <data-dir>/<network> (stash, state, index) together with the wallet.

Contract commands

schemata

rgb schemata. Lists imported schemas. Real output after importing NIA:

NonInflatableAsset      	rgb:sch:RWhwUfTMpuP2Zfx1~j4nswCANGeJrYOqDcKelaMV4zU#remote-digital-pegasus

contracts

rgb contracts. Lists contracts: ID, network, issue date, schema, and developer. Real output:

rgb:7Wf1Rne9-BQWvPlL-P50XBTB-D1sZQlF-Wn7eRYV-3_wZZg8	BitcoinRegtest	2026-10-19	rgb:sch:RWhwUfTMpuP2Zfx1~j4nswCANGeJrYOqDcKelaMV4zU#remote-digital-pegasus
  Developer: ssi:issuer

import

rgb import [-a] <FILE>. Imports one file: a kit (schemas, script libraries and types, for example NonInflatableAsset.rgb from rgb-schemas) or a contract consignment. Use -a for ASCII-armoured input.

rgb -n regtest -d data0 import NonInflatableAsset.rgb

Real output:

Importing kit rgb:kit:qxyONQWD-WY7Sha7-wzsRSMW-MaNI6PI-T74uzx9-sBzUztg:
- schema NonInflatableAsset RWhwUfTMpuP2Zfx1~j4nswCANGeJrYOqDcKelaMV4zU#remote-digital-pegasus
- script library alu:q~CZ0ovt-UN9eBlc-VMn86mz-Kfd3ywu-f7~9jTB-k6A8tiY#japan-nylon-center
- strict types: 35 definitions
Kit is imported

export

rgb export [-a] <CONTRACT_ID> [FILE]. Exports a contract consignment to FILE, or prints it to stdout. -a asks for ASCII armour.

armor

rgb armor <FILE>. Prints a binary RGB file as ASCII armour.

issue

rgb issue <ISSUER> <CONTRACT_PATH>. Issues a contract from a YAML file, where <ISSUER> is an identity string such as ssi:issuer. The file names the schema, its globals and its assignments. Each assignment has a seal (txid:vout) and an amount. Only fungible assignments can be issued this way. Void and structured assignments hit a todo!() in 0.11.1. See rgb-sandbox contracts/ for templates.

rgb -n regtest -d data0 issue "ssi:issuer" demo.yaml

Real output (the ID is different each time, because genesis seals are blinded with random values):

A new contract rgb:7Wf1Rne9-BQWvPlL-P50XBTB-D1sZQlF-Wn7eRYV-3_wZZg8 is issued and added to the stash.
Use `export` command to export the contract.

state

rgb state [-a] <CONTRACT_ID>. Prints global state, then owned state with its seal and witness. Use -a, --all to include spent state and state the wallet doesn't own.

history

rgb history [--details] <CONTRACT_ID>. Prints the operation history.

Transfer commands

invoice

rgb invoice [--amount N] [--address-based] [--assignment-name NAME] [--token-index I [--token-fraction F]] <CONTRACT_ID>

--amount <N>: the amount in the smallest unit.
--address-based: use an address-based (witness-output) invoice instead of a blinded UTXO.
--assignment-name <NAME>: the state to invoice. It is detected if you leave it out.
--token-index and --token-fraction: the token and fraction for NFT (UDA) transfers.

Use long option names

In 0.11.1 the short flag -a belongs to three options of invoice: --address-based, --assignment-name and --amount (see rgb invoice --help). Spell them out.

The invoice grammar is rgb:<contract>/<schema|~>/<state|~>/<chain>:<utxob:…|wvout:…>[?expiry=…&endpoints=…]. Example output, from the rgb-sandbox README:

rgb:Tk3d0h5w-8v4XYCg-7e~Sc0o-Lu6rp~X-~Jt7VHS-jqgzFD8/~/BF/bcrt:utxob:MSLQCKkW-w6caphB-12do1nJ-HNfgxvv-WE3zOOC-s8yZyHq-Ihoa5

See Invoices.

transfer

rgb transfer [-2] [--sats N] [-f FEE] <INVOICE> <CONSIGNMENT> [PSBT]

Creates the transfer consignment, and a PSBT that already contains the RGB commitment. Without PSBT, it prints the PSBT to stdout.

-f, --fee <N>: the fee in sats (default 400).
--sats <N>: the sats paid to an address-based beneficiary (default 2000).
-2: write a PSBT v2.

Consignment before broadcast

Give the consignment to the recipient, and let them validate it, before you sign and publish the transaction. If the transaction is published and the consignment is lost, the assets are lost. Also, spend the wallet's UTXOs only through RGB-aware tools. A plain Bitcoin wallet that spends an output holding RGB state destroys it.

prepare

rgb prepare [-2] [--sats N] <INVOICE> <FEE> [PSBT]. The first half of transfer: builds the PSBT. The help says that in most cases you should use transfer instead.

consign

rgb consign <INVOICE> <PSBT> <CONSIGNMENT>. The second half of transfer: adds the commitment to a prepared PSBT and writes the consignment.

validate

rgb validate <FILE>. Validates a transfer consignment. On success it prints The provided consignment is valid. Otherwise it prints the validation status.

accept

rgb accept [-f] <FILE>. Validates the consignment and adds it to the stash, printing Transfer accepted into the stash. Use -f, --force to accept consignments whose terminal witness transaction isn't mined yet.

finalize

rgb finalize [-p] <PSBT> [TX]. Finalizes the signed PSBT, and saves the transaction to TX if given. -p, --publish extracts the transaction and sends it to the network. The flag is -p. There is no --broadcast.

rgb -n regtest --electrum=localhost:50001 -d data0 -w issuer finalize -p data0/tx.psbt data0/tx.tx

extract

rgb extract [-p] <PSBT> [TX]. Extracts the signed transaction without modifying the PSBT. Without TX, it prints the transaction to stdout. -p, --publish sends it.

Debugging

inspect

rgb inspect [--dir] <FILE> [PATH]. Dumps any RGB file (consignment, kit, contract) as YAML, to PATH or to stdout. With --dir and a PATH, compound bundles are written in directory form.

dump

rgb dump [ROOT_DIR]. Dumps the whole stash and inventory into a directory (default ./rgb-dump).

Global options​

Commands​

Wallet commands​

list​

default​

create​

address​

utxos​

taprets​

Contract commands​

schemata​

contracts​

import​

export​

armor​

issue​

state​

history​

Transfer commands​

invoice​

transfer​

prepare​

consign​

validate​

accept​

finalize​

extract​

Debugging​

inspect​

dump​

See also​