Factom CLI Commands

Command reference for the Factom CLI

factom-cli is a command line interface program for interacting with factomd and factom-walletd.

factom-cli [OPTIONS] SUBCOMMAND [OPTIONS]

Flags

-f

$ echo hello | factom-cli addchain -f -n moe -n larry \
 EC2DKSYyRcNWf7RS963VFYgMExoHRYLHVeCfQ9PGPmNzwexample

The f flag, used with the addchain, addentry, buyec, composechain, composeentry, sendfct, sendtx, and signtx subcommands, tells factom-cli to continue on with processing without waiting for acknowledgment of the success of the subcommand to be generated. This can be useful for scripts where you can execute a long string of subcommands in a fraction of the time it would take if you had to wait for an acknowledgment of each command individually.

-q

$ echo goodbye | factom-cli addentry -q -n moe -n larry -e curly \
 EC2DKSYyRcNWf7RS963VFYgMExoHRYLHVeCfQ9PGPmNzwexample

The q flag specifies "quiet" execution of the addchain, addentry, addtxecoutput, addtxfee, addtxinput, addtxoutput, buyec, newtx, sendfct, sendtx, signtx, and subtxfee subcommands. This means that no output will be returned back to the user. This again can be useful for scripts where there is no need for feedback from factom-cli.

-e -x

$ factom-cli addentry [-fq] [-n NAME1 -h HEXNAME2 ...|-c CHAINID] \
[-e EXTID1 -e EXTID2 -x HEXEXTID ...] [-CET] ECADDRESS <STDIN>

The addentry subcommands support the -e and -x flags for adding external ids to the Entries they create. Multiple -e and -x flags may be used, and -e and -x may be used in combination. -e string will encode the string as binary and set it as the next external id. -x hexstring will decode the hexstring into binary and set it as the next external id.

-n -h

$ factom-cli get chainhead -n test -h 3031

The get firstentry, get chainhead, and get allentries subcommands support the -n and -h flags for using Chain Names as an alternative for providing a ChainID. The Chain Name is the combination of External IDs on the first Entry in the Chain.

-r

$ factom-cli sendfct -r $my_factoid_address factom.michaeljbeam.me

The r flag tells factom-cli to try and resolve a public Factoid or Entry Credit Address from a DNS name registered through Netki.

-C

$ echo hello | factom-cli addchain -n moe -n larry -C \
 EC2DKSYyRcNWf7RS963VFYgMExoHRYLHVeCfQ9PGPmNzwexample

The C flag, used with the addchain subcommand, limits the subcommand output to a single field, the ChainID with no headers. This means that a variable can be assigned to the value of the executed command directly.

-E

$ echo goodbye | factom-cli addentry -n moe -n larry -e curly -E \
 EC2DKSYyRcNWf7RS963VFYgMExoHRYLHVeCfQ9PGPmNzwexample

The E flag, used with the addchain and addentry subcommands, limits the subcommand output to a single field, the Entry Hash with no headers. This means that a variable can be assigned to the value of the executed command directly.

-T

$ factom-cli get pendingtransactions -T

The T flag, used with the addchain, addentry, buyec, get pendingtransactions, listtxs address, listtxs subcommands, limits the subcommand output to a single field, the Entry Hash with no headers. This means that a variable can be assigned to the value of the executed command directly.

Commands

addchain

factom-cli addchain [-fq] [-n NAME1 -n NAME2 -h HEXNAME3 ] [-CET] \
ECADDRESS <STDIN>

Create a new Factom Chain. Read data for the First Entry from stdin. Use the Entry Credits from the specified address.

Optional output flags will display only specific information used for scripting

-C display only the ChainID

-E display only the Entry Hash

-T display only the Transaction ID

addentry

factom-cli addentry [-fq] [-n NAME1 -h HEXNAME2 ...|-c CHAINID] \
 [-e EXTID1 -e EXTID2 -x HEXEXTID ...] [-CET] ECADDRESS <STDIN>

Create a new Factom Entry. Read data for the Entry from stdin. Use the Entry Credits from the specified address.

Optional output flags will display only specific information used for scripting

-C display only the ChainID

-E display only the Entry Hash

-T display only the Transaction ID

addtxecoutput

factom-cli addtxecoutput [-rq] TXNAME ADDRESS AMOUNT

Add an Entry Credit output to a transaction in the wallet. -r Netki DNS resolve. -q quiet.

addtxfee

factom-cli addtxfee [-q] TXNAME ADDRESS

Add the transaction fee to an input of a transaction in the wallet. -q quiet.

addtxinput

factom-cli addtxinput [-q] TXNAME ADDRESS AMOUNT

Add a Factoid input to a transaction in the wallet. -q quiet.

addtxoutput

factom-cli addtxoutput [-rq] TXNAME ADDRESS AMOUNT

Add a Factoid output to a transaction in the wallet. -r Netki DNS resolve. -q quiet.

backupwallet

factom-cli backupwallet

Backup the running wallet

balance

factom-cli balance [-r] ADDRESS

If this is an EC Address, returns the number of Entry Credits. If this is a Factoid Address, returns the Factoid balance.

balancetotals

factom-cli balancetotals [-FS -FA -ES -EA]

This is the total number of Factoids and Entry Credits in the wallet

Optional output flags will display only specific information used for scripting

-EA Display only the ackEC value

-ES Display only the savedEC value

-FA Display only the ackFCT value

-FS Display only the savedFCT value

buyec

factom-cli buyec [-fqrT] FCTADDRESS ECADDRESS ECAMOUNT

Buy ECAMOUNT number of entry credits. -f force. -q quiet. -r Netki DNS resolve. -T TxID.

composechain

$ factom-cli composechain [-f] [-n NAME1 -n NAME2 -h HEXNAME3 ] \
ECADDRESS <STDIN>

Create API calls to create a new Factom Chain. Read data for the First Entry from stdin. Use the Entry Credits from the specified address.

composeentry

$ factom-cli composeentry [-f] [-n NAME1 -h HEXNAME2 ...|-c CHAINID] \
[-e EXTID1 -e EXTID2 -x HEXEXTID ...] ECADDRESS <STDIN>

Create API calls to create a new Factom Entry. Read data for the Entry from stdin. Use the Entry Credits from the specified address.

composetx

$ factom-cli composetx TXNAME

Compose a wallet transaction into a JSON RPC object

diagnostics

$ factom-cli diagnostics [server|network|sync|election|authset]

Get diagnostic information about the Factom network

diagnostics authset

$ factom-cli diagnostics authset

Get diagnostic information about the Factom authorized servers

diagnostics election

$ factom-cli diagnostics election {-PVFIR]

Get diagnostic information about the Factom network election process

Optional output flags will display only specific information used for scripting

-F display only the Federated Index

-I display only the Federated ID

-P display only the progress status

-R display only the current round

-V display only the VM Index

diagnostics network

$ factom-cli diagnostics network [-LMDPHTB]

Get diagnostic information about the Factom network

Optional output flags will display only specific information used for scripting

-B display only the last block from the DBState

-D display only the current minute duration

-H display only the balance hash

-L display only the Leader height

-M display only the current minute

-P display only the previous minute duration

-T display only the temporary balance hash

diagnostics server

$ factom-cli diagnostics server [-NIKR]

Get diagnostic information about the Factom API server

Optional output flags will display only specific information used for scripting

-I display only the ID of the API server

-K display only the public key of the API server

-N display only the name of the API server

-R display only the role of the API server

diagnostics sync

$ factom-cli diagnostics sync [-SRE]

Get diagnostic information about the network syncing

Optional output flags will display only specific information used for scripting

-E display only the expected status

-R display only the received status

-S display only the syncing status

ecrate

factom-cli ecrate

It takes this many Factoids to buy an Entry Credit. Displays the larger between current and future rates. Also used to set Factoid fees.

exportaddresses

factom-cli exportaddresses

List the private addresses stored in the wallet

exportidentitykeys

factom-cli exportidentitykeys

List the identity key pairs (public and private) stored in the wallet

get

factom-cli get allentries|authorities|chainhead|currentminute|ablock|dblock|eblock|ecblock|fblock|
entry|firstentry|head|heights|pendingentries|pendingtransactions|raw|tps|walletheight

Get data about Factom Chains, Entries, and Blocks

get abheight

factom-cli get abheight HEIGHT -r (to suppress Raw Data)

Get Admin Block by height

get ablock

factom-cli get ablock [-RDBPL] HEIGHT|KEYMR

Get an Admin Block from factom by its Key Merkel Root or by its Height

Optional output flags will display only specific information used for scripting

-B display only the Backreference Hash

-D display only the Directory Block height

-L display only the Lookup Hash

-P display only the Previous Backreference Hash

-R display the hex encoding of the raw Directory Block

get allentries

factom-cli get allentries [-n NAME1 -N HEXNAME2 ...] CHAINID

Get all of the Entries in a Chain

get authorities

factom-cli get authorities

Get information about the authority servers on the Factom network

get chainhead

factom-cli get chainhead [-n NAME1 -N HEXNAME2 ...] CHAINID

Get ebhead by chainid

get currentminute

$ factom-cli get currentminute [-BDFLMNRSTX]
LeaderHeight: 8596
DirectoryBlockHeight: 8596
Minute: 9
CurrentBlockStartTime: 1572635328110996891
CurrentMinuteStartTime: 1572635382109911982
CurrentTime: 1572635387202893194
DirectoryBlockInSeconds: 60
StallDetected: false
FaultTimeout: 30
RoundTimeout: 30

$ factom-cli get currentminute -L
8596   

$ factom-cli get currentminute -M
9

Get information about the current minute and other properties of the factom network.

Optional output flags will display only specific information used for scripting

-L display only the Leader height

-D display only the DirectoryBlock height

-M display only the Current minute

-B display only the Block start time

-N display only the Minute start time

-T display only the Current time

-S display only the Directorty Block in seconds

-X display only the Stall Detected value

-F display only the Fault timeout

-R display only the Round timeout

get dbheight

factom-cli get dbheight HEIGHT -r (to suppress Raw Data)

Get Directory Block by height

get dblock

factom-cli get dblock [-RHKAVNBPFTDC] HEIGHT|KEYMR

Get a Directory Block from factom by its Key Merkel Root or by its Height

Optional output flags will display only specific information used for scripting

-A display only the Directory Block Header Hash

-B display only the Directory Block Body Merkel Root

-C display only the Directory Block Count

-D display only the Directory Block Height

-F display only the Previous Directory Block Full Hash

-H display only the Directory Block Hash

-K display only the Directory Block Key Merkel Root

-N display only the Network ID

-P display only the Previous Directory Block Key Merkel Root

-R display the hex encoding of the raw Directory Block

-T display only the Directory Block Timestamp

-V display only the Directory Block Header Version

get eblock

factom-cli get eblock KEYMR

Get eblock by Merkle root

get echeight

factom-cli get echeight HEIGHT -r (to suppress Raw Data)

Get Entry Credit Block by height

get ecblock

factom-cli get ecblock [-RBPLDAHF] HEIGHT|KEYMR

Get ecblock by Key Merkle root or by height

Optional output flags will display only specific information used for scripting

-A display only the Head Expansion Area

-B display only the Body Hash

-D display only the Directory Block Height

-F display only the Full Hash

-H display only the Header Hash

-L display only the Previous Full Hash

-P display only the Previous Header Hash

-R display the hex encoding of the raw Entry Credit Block

get entry

factom-cli get entry [-RC] HASH

Get Entry by Hash. -R raw entry. -C ChainID

get fbheight

factom-cli get fbheight HEIGHT -r (to suppress Raw Data)

Get Factoid Block by height

get fblock

factom-cli get fblock [-RBPLED] KEYMR|HEIGHT

Get a Factoid Block by its Key Merkle Root or Height Optional output flags will display only specific information used for scripting

-B display only the Body Merkel Root

-D display only the Directory Block Height

-E display only the Exchange Rate

-L display only the Previous Ledger Key Merkel Root

-P display only the Previous Key Merkel Root

-R display the hex encoding of the raw Factoid Block

get firstentry

factom-cli get firstentry [-n NAME1 -N HEXNAME2 ...] CHAINID [-REC]

Get the first Entry in a Chain. -R RawEntry. -E EntryHash. -C ChainID

get head

factom-cli get head [-RHKAVNBPFTDC]

Get the latest completed directory block

Optional output flags will display only specific information used for scripting

-A display only the Directory Block Header Hash

-B display only the Directory Block Body Merkel Root

-C display only the Directory Block Count

-D display only the Directory Block Height

-F display only the Previous Directory Block Full Hash

-H display only the Directory Block Hash

-K display only the Directory Block Key Merkel Root

-N display only the Network ID

-P display only the Previous Directory Block Key Merkel Root

-R display the hex encoding of the raw Directory Block

-T display only the Directory Block Timestamp

-V display only the Directory Block Header Version

get heights

$ factom-cli get heights [-DLBE]
DirectoryBlockHeight: 10000
LeaderHeight: 10001
EntryBlockHeight: 10000
EntryHeight: 10000

$ factom-cli get heights -D
10000

Get the current heights of various blocks in factomd

Optional output flags will display only specific information used for scripting -D display only the DirectoryBlock height

-L display only the Leader height

-B display only the EntryBlock height

-E display only the Entry height

get pendingentries

factom-cli get pendingentries [-E]

Get all pending entries, which may not yet be written to blockchain. -E EntryHash.

get pendingtransactions

factom-cli get pendingtransactions [-T]

Get all pending factoid transacitons, which may not yet be written to blockchain. -T TxID.

get raw

factom-cli get raw HASH

Returns a raw hex representation of a block, transaction, entry, or commit

get tps

factom-cli get tps [-IT]

Get the current instant and total average rate of Transactions Per Second.

Optional output flags will display only specific information used for scripting

-I display only the instant TPS rate

-T display only the total averaged TPS rate

get walletheight

factom-cli get walletheight

Get the number of factoid blocks factom-walletd has cached

identity

factom-cli identity addchain|addkeyreplacement|addattribute| \
addattributeendorsement|composechain|composekeyreplacement| \
composeattribute|composeattributeendorsement|getactivekeys|getactivekeysatheight

Used with subcommands to create/manage Factom Identity Chains, their currently valid keys, attributes, and attribute endorsements

identity addchain

factom-cli identity addchain [-fq] [-n NAME1 -n NAME2] \
[-k PUBKEY1 -k PUBKEY2] [-CET] ECADDRESS

Create a new Identity Chain. Use the Entry Credits from the specified address.

Using the optional output flags allows you to get back information about the newly created chain and the transaction that created it. Those flags are: -C ChainID. -E EntryHash. -T TxID.

identity addkeyreplacement

factom-cli identity addkeyreplacement [-fq] \
 [-c CHAINID | -n NAME1 -n NAME2 ... -n NAMEN] \
 --oldkey PUBKEY --newkey PUBKEY --signerkey PUBKEY ECADDRESS [-CET]

Create a new Identity Key Replacement Entry using the Entry Credits from the specified address. The oldkey is replaced by the newkey, and signerkey (same or higher priority as oldkey) authorizes the replacement.

Using the optional output flags allows you to get back information about the newly created entry and the transaction that created it. Those flags are: -C ChainID. -E EntryHash. -T TxID.

identity addattribute

factom-cli identity addattribute [-fq] -c CHAINID \
-creceiver CHAINID -csigner CHAINID -signerkey PUBKEY \
-attribute ATTRIBUTE_JSON_ARRAY ECADDRESS [-CET]

Create a new Identity Attribute Entry using the Entry Credits from the specified address.

Using the optional output flags allows you to get back information about the newly created entry and the transaction that created it. Those flags are: -C ChainID. -E EntryHash. -T TxID.

The -attribute flag must be followed by a JSON array of sub-attributes (key:value mappings) surrounded by backticks like so:

-attribute `[{"key":KEY1,"value":VALUE1},{"key":KEY2,"value":VALUE2},{"key":KEYN,"value":VALUEN}]`

identity addattributeendorsement

factom-cli identity addattributeendorsement [-fq] -c CHAINID \
-csigner CHAINID -signerkey PUBKEY -entryhash ENTRYHASH ECADDRESS [-CET]

Create a new Endorsement Entry for the Identity Attribute at the given entry hash. Uses the Entry Credits from the specified address.

Using the optional output flags allows you to get back information about the newly created entry and the transaction that created it. Those flags are: -C ChainID. -E EntryHash. -T TxID.

identity composechain

factom-cli identity composechain [-f] [-n NAME1 -n NAME2] \
[-k PUBKEY1 -k PUBKEY2] ECADDRESS

Create API calls to create a new Factom Identity Chain. Use the Entry Credits from the specified address.

identity composekeyreplacement

factom-cli identity composekeyreplacement [-f] \
[-c CHAINID | -n NAME1 -n NAME2 ... -n NAMEN] \
--oldkey PUBKEY --newkey PUBKEY --signerkey PUBKEY ECADDRESS

Create API calls to create a new Identity key replacement entry using the Entry Credits from the specified address. The oldkey is replaced by the newkey, and signerkey (same or higher priority as oldkey) authorizes the replacement.

identity composeattribute

factom-cli identity composeattribute [-f] -c CHAINID \
-creceiver CHAINID -csigner CHAINID -signerkey PUBKEY \
-attribute ATTRIBUTE_JSON_ARRAY ECADDRESS

Create API calls to create a new Identity Attribute Entry using the Entry Credits from the specified address.

The -attribute flag must be followed by a JSON array of sub-attributes (key:value mappings) surrounded by backticks like so:

-attribute `[{"key":KEY1,"value":VALUE1},{"key":KEY2,"value":VALUE2},{"key":KEYN,"value":VALUEN}]`

identity composeattributeendorsement

factom-cli identity composeattributeendorsement [-f] \
-c CHAINID -csigner CHAINID -signerkey PUBKEY -entryhash ENTRYHASH ECADDRESS

Compose API calls to create a new Endorsement Entry for the Identity Attribute at the given entry hash. Uses the Entry Credits from the specified address.

identity getactivekeys

factom-cli identity getactivekeys [-c CHAINID | -n NAME1 -n NAME2 ... -n NAMEN]

Gets the set of identity public keys that are active for the given identity chain at the highest known block height.

identity getactivekeysatheight

factom-cli identity getactivekeysatheight [-c CHAINID | -n NAME1 -n NAME2 ... -n NAMEN] HEIGHT

Gets the set of identity public keys that were active for the given identity chain at the specified block height.

importaddress

factom-cli importaddress ADDRESS [ADDRESS...]

Import one or more secret keys into the wallet

importidentitykeys

factom-cli importidentitykeys SECKEY [SECKEY...]

Import one or more identity keys into the wallet from the specified idsec keys

importwords

factom-cli importwords '12WORDS'

Import 12 words from Koinify sale into the Wallet

listaddresses

factom-cli listaddresses

List the addresses stored in the wallet

listidentitykeys

factom-cli listidentitykeys

List the public identity keys stored in the wallet

listtxs

factom-cli listtxs [tmp|all|address|id|range]

List transactions from the wallet or the Factoid Chain

listtxs address

factom-cli listtxs address [-T] ECADDRESS|FCTADDRESS

List the transaction from the Factoid Chain with a specific address. This command will only list confirmed transactions.-T TxID.

listtxs [all]

factom-cli listtxs [all] [-T]

List all transactions from the Factoid Chain. This command will only list confirmed transactions.-T TxID.

listtxs id

factom-cli listtxs id [-T] TXID

List transaction from the Factoid Chain. This command will only list confirmed transactions.-T TxID.

listtxs name

factom-cli listtxs name [-T] TXID

Show a current working transaction in the wallet. -T TxID.

listtxs range

factom-cli listtxs range [-T] START END

List the transactions from the Factoid Chain within the specified range. This command will only list confirmed transactions.

listtxs tmp

factom-cli listtxs tmp

List current working transactions in the wallet

newecaddress

factom-cli newecaddress

Generate a new Entry Credit Address in the wallet

newfctaddress

factom-cli newfctaddress

Generate a new Factoid Address in the wallet

newidentitykey

factom-cli newidentitykey

Generates a new identity key in the wallet

newtx

factom-cli newtx [-q] TXNAME

Create a new transaction in the wallet

properties

factom-cli properties [-CFAWL]

Get version information about facotmd and the factom wallet

Optional output flags will display only specific information used for scripting

-A display only the factomd API version

-C display only the CLI version

-F display only the factomd version

-L display only the wallet API version

-W display only the factom-wallet version

receipt

factom-cli receipt ENTRYHASH

Returns a Receipt for a given Entry

replaydbstates

factom-cli replaydbstates STARTHEIGHT ENDHEIGHT

Emit DBStateMsgs over the LiveFeed API between two specifed block heights

rmaddress

factom-cli rmaddress ADDRESS

Removes the public and private key from the wallet for the address specified.

rmidentitykey

factom-cli rmidentitykey PUBKEY

Removes the identity key pair from the wallet for the specified idpub key.

rmtx

factom-cli rmtx TXNAME

Remove a transaction in the wallet

sendfct

factom-cli sendfct [-fqrT] FROMADDRESS TOADDRESS AMOUNT

Send Factoids between 2 addresses. -f force. -q quiet. -r Netki DNs resolve. -T TxID.

sendtx

factom-cli sendtx [-fqT] TXNAME

Send a Transaction to Factom. -f force. -q quiet. -T TxID.

signtx

factom-cli signtx [-fqT] TXNAME

Sign a transaction in the wallet. -f force. -q quiet. -T TxID.

status

factom-cli status [-TSUD] TxID|FullTx

Returns information about a factoid transaction, or an entry / entry credit transaction

Optional output flags will display only specific information used for scripting

-D display the time of the transaction

-S display the transaction status only

-T display the transaction id only

-U display the unix time of the transaction

subtxfee

factom-cli subtxfee TXNAME ADDRESS

Subtract the transaction fee from an output of a transaction in the wallet

unlockwallet

 factom-cli unlockwallet [-v] "passphrase" <seconds-to-unlock>

Unlock the wallet for some number of seconds; must be an encrypted wallet. -v verbose. (Note: it is recommended that you run the command with a leading space to prevent writing the password to the command line history.)