Atomicals CLI reference

Wallet and signing effects

Any command that builds a transaction can spend outputs. Commands with --funding draw from a funding wallet, and commands with --owner spend the owner’s outputs. Before running anything that moves an asset, model the allocation first with the allocation visualizer.

How to read this page

• Usage shows the argument shape parsed from the source, not from a written example.
• Options are the flags declared on that command. A flag absent here is not accepted.
• Defaults are recorded only where the source declares one.

Common options and what they affect:

Option	Effect
--satsbyte	Fee rate. Recompute after any Bitwork grind, which changes the transaction
--funding	The wallet that pays. Keep it cardinal
--owner	The wallet whose outputs are spent. This is where an asset moves from
--initialowner	Where a newly minted object lands
--satsoutput	The satoshi value of the output carrying the result. Keep it above the dust threshold
--bitworkc, --bitworkr	Work required on your own commit and reveal transaction ids
--mintbitworkr	Work a deployment requires of its claimants
--parent, --parentowner	Parent linkage, set once at mint
--rbf	Signals replaceability. A replacement is a different transaction with a different allocation
--disablechalk	Turns off the progress display during grinding

Safety notes that apply to every command

1. No command needs a seed phrase typed into a prompt from a web page. Manage wallets locally.
2. A confirmed Bitcoin transaction is not a successful Atomicals operation. See commit and reveal.
3. Grinding changes the transaction, so any fee estimate taken before the grind is stale.
4. Read commands are safe. Build commands are not.

• Command builder

  Generate a validated, copyable command with the applicable source revision shown.

Commands

Generated from lib/cli.ts at 1333565efbfe . 79 commands. This page is not hand maintained, so it cannot drift from the source.

address

Get balances and Atomicals stored at an address

yarn cli address <address>

Arguments

Name	Required	Type hint
address	required	string

Options

Flag	Value	Default
--history	flag	none

address-atomicals

List all atomicals owned by an address

yarn cli address-atomicals <address>

Arguments

Name	Required	Type hint
address	required	string

address-history

List address history of an address

yarn cli address-history <address>

Arguments

Name	Required	Type hint
address	required	string

address-script

Encodes an address or wallet alias as the hex output script

yarn cli address-script <addressOrAlias>

Arguments

Name	Required	Type hint
addressOrAlias	required	string

address-utxos

List all utxos owned by an address

yarn cli address-utxos <address>

Arguments

Name	Required	Type hint
address	required	string

at-location

Get Atomicals at a utxo location

yarn cli at-location <location>

Arguments

Name	Required	Type hint
location	required	string

await-utxo

Finds utxo by address

yarn cli await-utxo <address> <amount>

Arguments

Name	Required	Type hint
address	required	string
amount	required	number

balances

Get balances and atomicals stored at internal wallets

yarn cli balances

Options

Flag	Value	Default
--address <string>	required	none
--alias <string>	required	none
--all	flag	none
--noqr	flag	none
--utxos	flag	none

broadcast

broadcast a rawtx

yarn cli broadcast

Options

Flag	Value	Default
--rawtx <string>	required	none
--rawtxfile <string>	required	none

compact-outpoint

Encodes the compact id to outpoint hex format

yarn cli compact-outpoint <compactId>

Arguments

Name	Required	Type hint
compactId	required	string

custom-color

custom color operation to separate the FT Atomicals at a single UTXOs.

yarn cli custom-color <locationId>

Arguments

Name	Required	Type hint
locationId	required	string

Options

Flag	Value	Default
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	15

decodetx

Decode a tx

yarn cli decodetx

Options

Flag	Value	Default
--rawtx <string>	required	none
--rawtxfile <string>	required	none

delete

Delete keys for existing Atomical.

yarn cli delete <atomicalIdAlias> <filesWithDeleteKeys>

Arguments

Name	Required	Type hint
atomicalIdAlias	required	string
filesWithDeleteKeys	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--bitworkr <string>	required	none
--disablechalk	flag	none
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--satsoutput <number>	required	1000

diff

yarn cli diff

disable-subrealms

Delete the subrealm minting rules for a realm or subrealm

yarn cli disable-subrealms <realmOrSubRealm>

Arguments

Name	Required	Type hint
realmOrSubRealm	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--bitworkr <string>	required	none
--disablechalk	flag	none
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--satsoutput <number>	required	1000

download

Download a file from a locationId or atomicalId

yarn cli download <locationIdOrTxId>

Arguments

Name	Required	Type hint
locationIdOrTxId	required	string

Options

Flag	Value	Default
--body	flag	none

dump

dump

yarn cli dump

emit

Emit an event for an existing Atomical with data.

yarn cli emit <atomicalIdAlias> <data>

Arguments

Name	Required	Type hint
atomicalIdAlias	required	string
data	required	string

Options

Flag	Value	Default
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--satsoutput <number>	required	1000

enable-dmint

Enable dmint for a container with the dmint config file produced from the prepare-dmint command

yarn cli enable-dmint <container> <jsonFilename>

Arguments

Name	Required	Type hint
container	required	string
jsonFilename	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--satsoutput <number>	required	1000

enable-subrealms

Set and enable subrealm minting rules for a realm or subrealm

yarn cli enable-subrealms <realmOrSubRealm> <file>

Arguments

Name	Required	Type hint
realmOrSubRealm	required	string
file	required	unstated

Options

Flag	Value	Default
--bitworkc <string>	required	none
--bitworkr <string>	required	none
--disablechalk	flag	none
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--satsoutput <number>	required	1000

events

Get the event state history of an Atomical

yarn cli events <atomicalAliasOrId>

Arguments

Name	Required	Type hint
atomicalAliasOrId	required	string

Options

Flag	Value	Default
--verbose	flag	none

find-containers

Search containers

yarn cli find-containers

Options

Flag	Value	Default
--asc <string>	required	true
--q <string>	required	none

find-realms

Search realms

yarn cli find-realms

Options

Flag	Value	Default
--asc <string>	required	true
--q <string>	required	none

find-tickers

Search tickers

yarn cli find-tickers

Options

Flag	Value	Default
--asc <string>	required	true
--q <string>	required	none

ftinfo

Get FT specific info for an FT atomical

yarn cli ftinfo <atomicalAliasOrId>

Arguments

Name	Required	Type hint
atomicalAliasOrId	required	string

get

Get the status of an Atomical

yarn cli get <atomicalAliasOrId>

Arguments

Name	Required	Type hint
atomicalAliasOrId	required	string

Options

Flag	Value	Default
--verbose	flag	none

get-container

Get Atomical by container name

yarn cli get-container <container>

Arguments

Name	Required	Type hint
container	required	string

Options

Flag	Value	Default
--verbose	flag	none

get-container-item

Get an item in the container

yarn cli get-container-item <container> <itemId>

Arguments

Name	Required	Type hint
container	required	string
itemId	required	string

Options

Flag	Value	Default
--verbose	flag	none

get-container-items

Get the items in the container

yarn cli get-container-items <container> <limit> <offset>

Arguments

Name	Required	Type hint
container	required	string
limit	required	number
offset	required	number

Options

Flag	Value	Default
--verbose	flag	none

get-realm

Resolve a realm or subrealm. Alias for 'resolve'

yarn cli get-realm <realm_or_subrealm>

Arguments

Name	Required	Type hint
realm_or_subrealm	required	string

Options

Flag	Value	Default
--verbose	flag	none

get-ticker

Get Atomical by ticker name

yarn cli get-ticker <ticker>

Arguments

Name	Required	Type hint
ticker	required	string

Options

Flag	Value	Default
--verbose	flag	none

global

Get global status

yarn cli global

Options

Flag	Value	Default
--hashes <number>	required	10

init-dft

Initialize fungible token (FT) atomical in decentralized issuance mode

yarn cli init-dft <ticker> <mint_amount> <max_mints> <mint_height> <file> <mintbitworkc>

Arguments

Name	Required	Type hint
ticker	required	string
mint_amount	required	number
max_mints	required	number
mint_height	required	number
file	required	string
mintbitworkc	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--bitworkr <string>	required	none
--disablechalk	flag	none
--funding <string>	required	none
--mintbitworkr <string>	required	none
--parent <string>	required	none
--parentowner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	200

init-dft-fixed

Initialize fixed bitwork mineable fungible token (FT) atomical in decentralized issuance mode

yarn cli init-dft-fixed <ticker> <mintbitworkc>

Arguments

Name	Required	Type hint
ticker	required	string
mintbitworkc	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--bitworkr <string>	required	none
--funding <string>	required	none
--max_mints <number>	required	100000
--metadata <string>	required	none
--mint_amount <number>	required	10000
--mint_height <number>	required	0
--mintbitworkr <number>	required	none
--noimage <boolean>	required	none
--satsbyte <number>	required	200

init-dft-perpetual

Initialize perpetual bitwork mineable fungible token (FT) atomical in decentralized issuance mode

yarn cli init-dft-perpetual <ticker>

Arguments

Name	Required	Type hint
ticker	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--bitworkr <string>	required	none
--funding <string>	required	none
--max_mints <number>	required	2000
--maxglobalmints <number>	required	none
--metadata <string>	required	none
--mint_amount <number>	required	10000
--mint_height <number>	required	0
--mintbitworkcinc <number>	required	1
--mintbitworkcincstart <number>	required	none
--mintbitworkrinc <number>	required	none
--mintbitworkrincstart <number>	required	none
--mintbitworkvec <string>	required	none
--noimage <boolean>	required	none
--satsbyte <number>	required	-1

list

List feed of Atomicals minted globally

yarn cli list

Options

Flag	Value	Default
--asc <string>	required	true
--limit <number>	required	20
--offset <number>	required	-20

location

Get locations of an Atomical

yarn cli location <atomicalAliasOrId>

Arguments

Name	Required	Type hint
atomicalAliasOrId	required	string

Options

Flag	Value	Default
--verbose	flag	none

merge-atomicals

Merge Atomicals UTXOs together for test purposes

yarn cli merge-atomicals

Options

Flag	Value	Default
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	15

mint-container

Mint container non-fungible token (NFT) Atomical

yarn cli mint-container <container>

Arguments

Name	Required	Type hint
container	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--bitworkr <string>	required	none
--container <string>	required	none
--disablechalk	flag	none
--funding <string>	required	none
--initialowner <string>	required	none
--parent <string>	required	none
--parentowner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--satsoutput <number>	required	1000

mint-dft

Mint coins for a decentralized fungible token (FT)

yarn cli mint-dft <ticker>

Arguments

Name	Required	Type hint
ticker	required	string

Options

Flag	Value	Default
--current	flag	none
--disablechalk	flag	none
--funding <string>	required	none
--initialowner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1

mint-ft

Mint fungible token (FT) Atomical in direct issuance mode

yarn cli mint-ft <ticker> <supply> <file>

Arguments

Name	Required	Type hint
ticker	required	string
supply	required	number
file	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--bitworkr <string>	required	none
--disablechalk	flag	none
--funding <string>	required	none
--initialowner <string>	required	none
--parent <string>	required	none
--parentowner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1

mint-item

Mint item non-fungible token (NFT) Atomical from a decentralized container

yarn cli mint-item <containerName> <itemName> <manifestFile>

Arguments

Name	Required	Type hint
containerName	required	string
itemName	required	string
manifestFile	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--bitworkr <string>	required	none
--container <string>	required	none
--disablechalk	flag	none
--funding <string>	required	none
--initialowner <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--satsoutput <number>	required	1000

mint-nft

Mint non-fungible token (NFT) Atomical

yarn cli mint-nft <file>

Arguments

Name	Required	Type hint
file	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--bitworkr <string>	required	none
--container <string>	required	none
--disablechalk	flag	none
--funding <string>	required	none
--initialowner <string>	required	none
--parent <string>	required	none
--parentowner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--satsoutput <number>	required	1000

mint-nft-json

Mint non-fungible token (NFT) Atomical with JSON only data

yarn cli mint-nft-json <jsonFile>

Arguments

Name	Required	Type hint
jsonFile	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--bitworkr <string>	required	none
--container <string>	required	none
--disablechalk	flag	none
--funding <string>	required	none
--initialowner <string>	required	none
--parent <string>	required	none
--parentowner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--satsoutput <number>	required	1000

mint-realm

Mint top level Realm non-fungible token (NFT) Atomical

yarn cli mint-realm <realm>

Arguments

Name	Required	Type hint
realm	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--bitworkr <string>	required	none
--container <string>	required	none
--disablechalk	flag	none
--funding <string>	required	none
--initialowner <string>	required	none
--parent <string>	required	none
--parentowner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--satsoutput <number>	required	1000

mint-subrealm

Mint subrealm non-fungible token (NFT) Atomical

yarn cli mint-subrealm <realm>

Arguments

Name	Required	Type hint
realm	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--bitworkr <string>	required	none
--container <string>	required	none
--disablechalk	flag	none
--funding <string>	required	none
--initialowner <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	200
--satsoutput <number>	required	1000

outpoint-compact

Decodes hex outpoint to compact location id form

yarn cli outpoint-compact <hex>

Arguments

Name	Required	Type hint
hex	required	string

pending-subrealms

Display pending subrealm Atomical requests and make payments

yarn cli pending-subrealms

Options

Flag	Value	Default
--display	flag	none
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--verbose	flag	none

prepare-dmint

Prepare the dmint config and item manifest from a folder of images

yarn cli prepare-dmint <folder> <mintHeight> <bitworkc>

Arguments

Name	Required	Type hint
folder	required	string
mintHeight	required	number
bitworkc	required	string

prepare-dmint-items

Prepare the dmint config and item manifest from a folder of images

yarn cli prepare-dmint-items <folder> <outputFolderName>

Arguments

Name	Required	Type hint
folder	required	string
outputFolderName	required	string

realm-info

Get realm and subrealm information of an atomical

yarn cli realm-info <atomicalIdAlias>

Arguments

Name	Required	Type hint
atomicalIdAlias	required	string

Options

Flag	Value	Default
--verbose	flag	none

resolve

Resolve a realm or subrealm. Alias for 'get-realm'

yarn cli resolve <realm_or_subrealm>

Arguments

Name	Required	Type hint
realm_or_subrealm	required	string

Options

Flag	Value	Default
--verbose	flag	none

script-address

Decodes a script as an address

yarn cli script-address <script>

Arguments

Name	Required	Type hint
script	required	string

seal

Seal any NFT Atomical type permanently so that it can never be updated or transferred ever again.

yarn cli seal <atomicalIdAlias>

Arguments

Name	Required	Type hint
atomicalIdAlias	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1

server-version

Get electrumx server version info

yarn cli server-version

set

Set (update) an existing Atomical with data.

yarn cli set <atomicalIdAlias> <jsonFilename>

Arguments

Name	Required	Type hint
atomicalIdAlias	required	string
jsonFilename	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--disableautoencode	flag	none
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--satsoutput <number>	required	1000

set-container-data

Update container data with json file contents

yarn cli set-container-data <containerName> <jsonFilename>

Arguments

Name	Required	Type hint
containerName	required	string
jsonFilename	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--disableautoencode	flag	none
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--satsoutput <number>	required	1000

set-relation

Set relationship an existing Atomical with data.

yarn cli set-relation <atomicalId> <relationName> <relationValues>

Arguments

Name	Required	Type hint
atomicalId	required	string
relationName	required	string
relationValues	required	string

Options

Flag	Value	Default
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	15
--satsoutput <number>	required	1000

splat

Extract an NFT Atomical from a UTXO which contains multiple Atomicals

yarn cli splat <locationId>

Arguments

Name	Required	Type hint
locationId	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--satsoutput <number>	required	1000

split

Split operation to separate the FT Atomicals at a single UTXOs.

yarn cli split <locationId>

Arguments

Name	Required	Type hint
locationId	required	string

Options

Flag	Value	Default
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	15

state

Get the state of an Atomical

yarn cli state <atomicalAliasOrId>

Arguments

Name	Required	Type hint
atomicalAliasOrId	required	string

Options

Flag	Value	Default
--verbose	flag	none

state-history

Get the state history of an Atomical

yarn cli state-history <atomicalAliasOrId>

Arguments

Name	Required	Type hint
atomicalAliasOrId	required	string

Options

Flag	Value	Default
--verbose	flag	none

store-file

Store general immutable data transaction that is not an NFT or FT

yarn cli store-file <filepath> <givenFileName>

Arguments

Name	Required	Type hint
filepath	required	string
givenFileName	required	string

Options

Flag	Value	Default
--bitworkc <string>	required	none
--bitworkr <string>	required	none
--disablechalk	flag	none
--funding <string>	required	none
--parent <string>	required	none
--parentowner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	-1
--satsoutput <number>	required	1000

summary-containers

Show summary of owned containers by wallet

yarn cli summary-containers

Options

Flag	Value	Default
--filter <string>	required	none
--owner <string>	required	none

summary-realms

Show summary of owned realms by wallet

yarn cli summary-realms

Options

Flag	Value	Default
--filter <string>	required	none
--owner <string>	required	none

summary-subrealms

Show summary of owned subrealms by wallet

yarn cli summary-subrealms

Options

Flag	Value	Default
--filter <string>	required	none
--owner <string>	required	none

summary-tickers

Show summary of owned tokens by tickers by wallet

yarn cli summary-tickers

Options

Flag	Value	Default
--filter <string>	required	none
--owner <string>	required	none

transfer-builder

Transfer plain regular UTXOs to another addresses

yarn cli transfer-builder

Options

Flag	Value	Default
--atomicalreceipt <string>	required	none
--atomicalreceipttype <string>	required	none
--funding <string>	required	none
--nofunding	flag	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	15
--skipvalidation	flag	none

transfer-ft

Transfer Atomical FT to other addresses

yarn cli transfer-ft <atomicalId>

Arguments

Name	Required	Type hint
atomicalId	required	string

Options

Flag	Value	Default
--atomicalreceipt <string>	required	none
--funding <string>	required	none
--nofunding	flag	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	15

transfer-nft

Transfer Atomical NFT to new address

yarn cli transfer-nft <atomicalId> <address>

Arguments

Name	Required	Type hint
atomicalId	required	string
address	required	string

Options

Flag	Value	Default
--funding <string>	required	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	15
--satsoutput <number>	required	546

transfer-utxos

Transfer plain regular UTXOs to another addresses

yarn cli transfer-utxos

Options

Flag	Value	Default
--atomicalreceipt <string>	required	none
--funding <string>	required	none
--nofunding	flag	none
--owner <string>	required	none
--rbf	flag	none
--satsbyte <number>	required	15

tx

Get any transaction

yarn cli tx <txid>

Arguments

Name	Required	Type hint
txid	required	string

Options

Flag	Value	Default
--verbose	flag	none

tx-history

Get the history of an Atomical

yarn cli tx-history <atomicalAliasOrId>

Arguments

Name	Required	Type hint
atomicalAliasOrId	required	string

Options

Flag	Value	Default
--verbose	flag	none

validate-container-item

Validate a container item from the manifest

yarn cli validate-container-item <containerName> <itemName> <manifestFile>

Arguments

Name	Required	Type hint
containerName	required	string
itemName	required	string
manifestFile	required	string

Options

Flag	Value	Default
--sealed --no-sealed	flag	none

wallet-create

Creates and displays new 12-word secret mnemonic phrase along with the primary and funding addresses

yarn cli wallet-create

wallet-decode

Decode secret mnemonic phrase to display derive address and key at provided path

yarn cli wallet-decode <phrase>

Arguments

Name	Required	Type hint
phrase	required	string

Options

Flag	Value	Default
-p, --path <string>	required	Passphrase for the wallet

wallet-import

Import a wallet by WIF and assign it to provided alias

yarn cli wallet-import <wif> <alias>

Arguments

Name	Required	Type hint
wif	required	string
alias	required	string

wallet-init

Initializes a new wallet at wallet.json

yarn cli wallet-init

Options

Flag	Value	Default
--n <number>	required	none
--path <string>	required	Provide a passphrase for the wallet
--phrase <string>	required	none

wallets

Get balances and atomicals stored at internal wallets

yarn cli wallets

Options

Flag	Value	Default
--address <string>	required	none
--alias <string>	required	none
--all	flag	none
--balances	flag	none
--extra	flag	none
--history	flag	none
--identify <string>	required	none
--noqr	flag	none
--type <string>	required	none