Factom CLI Commands
Command reference for the Factom CLI
factom-cli is a command line interface program for interacting with factomd and factom-walletd.
1
factom-cli [OPTIONS] SUBCOMMAND [OPTIONS]
Copied!

Flags

-f

1
$ echo hello | factom-cli addchain -f -n moe -n larry \
2
EC2DKSYyRcNWf7RS963VFYgMExoHRYLHVeCfQ9PGPmNzwexample
Copied!
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

1
$ echo goodbye | factom-cli addentry -q -n moe -n larry -e curly \
2
EC2DKSYyRcNWf7RS963VFYgMExoHRYLHVeCfQ9PGPmNzwexample
Copied!
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

1
$ factom-cli addentry [-fq] [-n NAME1 -h HEXNAME2 ...|-c CHAINID] \
2
[-e EXTID1 -e EXTID2 -x HEXEXTID ...] [-CET] ECADDRESS <STDIN>
Copied!
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

1
$ factom-cli get chainhead -n test -h 3031
Copied!
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

1
$ factom-cli sendfct -r $my_factoid_address factom.michaeljbeam.me
Copied!
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

1
$ echo hello | factom-cli addchain -n moe -n larry -C \
2
EC2DKSYyRcNWf7RS963VFYgMExoHRYLHVeCfQ9PGPmNzwexample
Copied!
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

1
$ echo goodbye | factom-cli addentry -n moe -n larry -e curly -E \
2
EC2DKSYyRcNWf7RS963VFYgMExoHRYLHVeCfQ9PGPmNzwexample
Copied!
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

1
$ factom-cli get pendingtransactions -T
Copied!
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

1
factom-cli addchain [-fq] [-n NAME1 -n NAME2 -h HEXNAME3 ] [-CET] \
2
ECADDRESS <STDIN>
Copied!
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

1
factom-cli addentry [-fq] [-n NAME1 -h HEXNAME2 ...|-c CHAINID] \
2
[-e EXTID1 -e EXTID2 -x HEXEXTID ...] [-CET] ECADDRESS <STDIN>
Copied!
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

1
factom-cli addtxecoutput [-rq] TXNAME ADDRESS AMOUNT
Copied!
Add an Entry Credit output to a transaction in the wallet. -r Netki DNS resolve. -q quiet.

addtxfee

1
factom-cli addtxfee [-q] TXNAME ADDRESS
Copied!
Add the transaction fee to an input of a transaction in the wallet. -q quiet.

addtxinput

1
factom-cli addtxinput [-q] TXNAME ADDRESS AMOUNT
Copied!
Add a Factoid input to a transaction in the wallet. -q quiet.

addtxoutput

1
factom-cli addtxoutput [-rq] TXNAME ADDRESS AMOUNT
Copied!
Add a Factoid output to a transaction in the wallet. -r Netki DNS resolve. -q quiet.

backupwallet

1
factom-cli backupwallet
Copied!
Backup the running wallet

balance

1
factom-cli balance [-r] ADDRESS
Copied!
If this is an EC Address, returns the number of Entry Credits. If this is a Factoid Address, returns the Factoid balance.

balancetotals

1
factom-cli balancetotals [-FS -FA -ES -EA]
Copied!
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

1
factom-cli buyec [-fqrT] FCTADDRESS ECADDRESS ECAMOUNT
Copied!
Buy ECAMOUNT number of entry credits. -f force. -q quiet. -r Netki DNS resolve. -T TxID.

composechain

1
$ factom-cli composechain [-f] [-n NAME1 -n NAME2 -h HEXNAME3 ] \
2
ECADDRESS <STDIN>
Copied!
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

1
$ factom-cli composeentry [-f] [-n NAME1 -h HEXNAME2 ...|-c CHAINID] \
2
[-e EXTID1 -e EXTID2 -x HEXEXTID ...] ECADDRESS <STDIN>
Copied!
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

1
$ factom-cli composetx TXNAME
Copied!
Compose a wallet transaction into a JSON RPC object

diagnostics

1
$ factom-cli diagnostics [server|network|sync|election|authset]
Copied!
Get diagnostic information about the Factom network

diagnostics authset

1
$ factom-cli diagnostics authset
Copied!
Get diagnostic information about the Factom authorized servers

diagnostics election

1
$ factom-cli diagnostics election {-PVFIR]
Copied!
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

1
$ factom-cli diagnostics network [-LMDPHTB]
Copied!
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

1
$ factom-cli diagnostics server [-NIKR]
Copied!
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

1
$ factom-cli diagnostics sync [-SRE]
Copied!
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

1
factom-cli ecrate
Copied!
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

1
factom-cli exportaddresses
Copied!
List the private addresses stored in the wallet

exportidentitykeys

1
factom-cli exportidentitykeys
Copied!
List the identity key pairs (public and private) stored in the wallet

get

1
factom-cli get allentries|authorities|chainhead|currentminute|ablock|dblock|eblock|ecblock|fblock|
2
entry|firstentry|head|heights|pendingentries|pendingtransactions|raw|tps|walletheight
Copied!
Get data about Factom Chains, Entries, and Blocks

get abheight

1
factom-cli get abheight HEIGHT -r (to suppress Raw Data)
Copied!
Get Admin Block by height

get ablock

1
factom-cli get ablock [-RDBPL] HEIGHT|KEYMR
Copied!
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

1
factom-cli get allentries [-n NAME1 -N HEXNAME2 ...] CHAINID
Copied!
Get all of the Entries in a Chain

get authorities

1
factom-cli get authorities
Copied!
Get information about the authority servers on the Factom network

get chainhead

1
factom-cli get chainhead [-n NAME1 -N HEXNAME2 ...] CHAINID
Copied!
Get ebhead by chainid

get currentminute

1
$ factom-cli get currentminute [-BDFLMNRSTX]
2
LeaderHeight: 8596
3
DirectoryBlockHeight: 8596
4
Minute: 9
5
CurrentBlockStartTime: 1572635328110996891
6
CurrentMinuteStartTime: 1572635382109911982
7
CurrentTime: 1572635387202893194
8
DirectoryBlockInSeconds: 60
9
StallDetected: false
10
FaultTimeout: 30
11
RoundTimeout: 30
12
13
$ factom-cli get currentminute -L
14
8596
15
16
$ factom-cli get currentminute -M
17
9
Copied!
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

1
factom-cli get dbheight HEIGHT -r (to suppress Raw Data)
Copied!
Get Directory Block by height

get dblock

1
factom-cli get dblock [-RHKAVNBPFTDC] HEIGHT|KEYMR
Copied!
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

1
factom-cli get eblock KEYMR
Copied!
Get eblock by Merkle root

get echeight

1
factom-cli get echeight HEIGHT -r (to suppress Raw Data)
Copied!
Get Entry Credit Block by height

get ecblock

1
factom-cli get ecblock [-RBPLDAHF] HEIGHT|KEYMR
Copied!
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

1
factom-cli get entry [-RC] HASH
Copied!
Get Entry by Hash. -R raw entry. -C ChainID

get fbheight

1
factom-cli get fbheight HEIGHT -r (to suppress Raw Data)
Copied!
Get Factoid Block by height

get fblock

1
factom-cli get fblock [-RBPLED] KEYMR|HEIGHT
Copied!
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

1
factom-cli get firstentry [-n NAME1 -N HEXNAME2 ...] CHAINID [-REC]
Copied!
Get the first Entry in a Chain. -R RawEntry. -E EntryHash. -C ChainID

get head

1
factom-cli get head [-RHKAVNBPFTDC]
Copied!
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

1
$ factom-cli get heights [-DLBE]
2
DirectoryBlockHeight: 10000
3
LeaderHeight: 10001
4
EntryBlockHeight: 10000
5
EntryHeight: 10000
6
7
$ factom-cli get heights -D
8
10000
Copied!
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

1
factom-cli get pendingentries [-E]
Copied!
Get all pending entries, which may not yet be written to blockchain. -E EntryHash.

get pendingtransactions

1
factom-cli get pendingtransactions [-T]
Copied!
Get all pending factoid transacitons, which may not yet be written to blockchain. -T TxID.

get raw

1
factom-cli get raw HASH
Copied!
Returns a raw hex representation of a block, transaction, entry, or commit

get tps

1
factom-cli get tps [-IT]
Copied!
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

1
factom-cli get walletheight
Copied!
Get the number of factoid blocks factom-walletd has cached

identity

1
factom-cli identity addchain|addkeyreplacement|addattribute| \
2
addattributeendorsement|composechain|composekeyreplacement| \
3
composeattribute|composeattributeendorsement|getactivekeys|getactivekeysatheight
Copied!
Used with subcommands to create/manage Factom Identity Chains, their currently valid keys, attributes, and attribute endorsements

identity addchain

1
factom-cli identity addchain [-fq] [-n NAME1 -n NAME2] \
2
[-k PUBKEY1 -k PUBKEY2] [-CET] ECADDRESS
Copied!
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

1
factom-cli identity addkeyreplacement [-fq] \
2
[-c CHAINID | -n NAME1 -n NAME2 ... -n NAMEN] \
3
--oldkey PUBKEY --newkey PUBKEY --signerkey PUBKEY ECADDRESS [-CET]
Copied!
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

1
factom-cli identity addattribute [-fq] -c CHAINID \
2
-creceiver CHAINID -csigner CHAINID -signerkey PUBKEY \
3
-attribute ATTRIBUTE_JSON_ARRAY ECADDRESS [-CET]
Copied!
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

1
factom-cli identity addattributeendorsement [-fq] -c CHAINID \
2
-csigner CHAINID -signerkey PUBKEY -entryhash ENTRYHASH ECADDRESS [-CET]
Copied!
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

1
factom-cli identity composechain [-f] [-n NAME1 -n NAME2] \
2
[-k PUBKEY1 -k PUBKEY2] ECADDRESS
Copied!
Create API calls to create a new Factom Identity Chain. Use the Entry Credits from the specified address.

identity composekeyreplacement

1
factom-cli identity composekeyreplacement [-f] \
2
[-c CHAINID | -n NAME1 -n NAME2 ... -n NAMEN] \
3
--oldkey PUBKEY --newkey PUBKEY --signerkey PUBKEY ECADDRESS
Copied!
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

1
factom-cli identity composeattribute [-f] -c CHAINID \
2
-creceiver CHAINID -csigner CHAINID -signerkey PUBKEY \
3
-attribute ATTRIBUTE_JSON_ARRAY ECADDRESS
Copied!
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

1
factom-cli identity composeattributeendorsement [-f] \
2
-c CHAINID -csigner CHAINID -signerkey PUBKEY -entryhash ENTRYHASH ECADDRESS
Copied!
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

1
factom-cli identity getactivekeys [-c CHAINID | -n NAME1 -n NAME2 ... -n NAMEN]
Copied!
Gets the set of identity public keys that are active for the given identity chain at the highest known block height.

identity getactivekeysatheight

1
factom-cli identity getactivekeysatheight [-c CHAINID | -n NAME1 -n NAME2 ... -n NAMEN] HEIGHT
Copied!
Gets the set of identity public keys that were active for the given identity chain at the specified block height.

importaddress

1
factom-cli importaddress ADDRESS [ADDRESS...]
Copied!
Import one or more secret keys into the wallet

importidentitykeys

1
factom-cli importidentitykeys SECKEY [SECKEY...]
Copied!
Import one or more identity keys into the wallet from the specified idsec keys

importwords

1
factom-cli importwords '12WORDS'
Copied!
Import 12 words from Koinify sale into the Wallet

listaddresses

1
factom-cli listaddresses
Copied!
List the addresses stored in the wallet

listidentitykeys

1
factom-cli listidentitykeys
Copied!
List the public identity keys stored in the wallet

listtxs

1
factom-cli listtxs [tmp|all|address|id|range]
Copied!
List transactions from the wallet or the Factoid Chain

listtxs address

1
factom-cli listtxs address [-T] ECADDRESS|FCTADDRESS
Copied!
List the transaction from the Factoid Chain with a specific address. This command will only list confirmed transactions.-T TxID.

listtxs [all]

1
factom-cli listtxs [all] [-T]
Copied!
List all transactions from the Factoid Chain. This command will only list confirmed transactions.-T TxID.

listtxs id

1
factom-cli listtxs id [-T] TXID
Copied!
List transaction from the Factoid Chain. This command will only list confirmed transactions.-T TxID.

listtxs name

1
factom-cli listtxs name [-T] TXID
Copied!
Show a current working transaction in the wallet. -T TxID.

listtxs range

1
factom-cli listtxs range [-T] START END
Copied!
List the transactions from the Factoid Chain within the specified range. This command will only list confirmed transactions.

listtxs tmp

1
factom-cli listtxs tmp
Copied!
List current working transactions in the wallet

newecaddress

1
factom-cli newecaddress
Copied!
Generate a new Entry Credit Address in the wallet

newfctaddress

1
factom-cli newfctaddress
Copied!
Generate a new Factoid Address in the wallet

newidentitykey

1
factom-cli newidentitykey
Copied!
Generates a new identity key in the wallet

newtx

1
factom-cli newtx [-q] TXNAME
Copied!
Create a new transaction in the wallet

properties

1
factom-cli properties [-CFAWL]
Copied!
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

1
factom-cli receipt ENTRYHASH
Copied!
Returns a Receipt for a given Entry

replaydbstates

1
factom-cli replaydbstates STARTHEIGHT ENDHEIGHT
Copied!
Emit DBStateMsgs over the LiveFeed API between two specifed block heights

rmaddress

1
factom-cli rmaddress ADDRESS
Copied!
Removes the public and private key from the wallet for the address specified.

rmidentitykey

1
factom-cli rmidentitykey PUBKEY
Copied!
Removes the identity key pair from the wallet for the specified idpub key.

rmtx

1
factom-cli rmtx TXNAME
Copied!
Remove a transaction in the wallet

sendfct

1
factom-cli sendfct [-fqrT] FROMADDRESS TOADDRESS AMOUNT
Copied!
Send Factoids between 2 addresses. -f force. -q quiet. -r Netki DNs resolve. -T TxID.

sendtx

1
factom-cli sendtx [-fqT] TXNAME
Copied!
Send a Transaction to Factom. -f force. -q quiet. -T TxID.

signtx

1
factom-cli signtx [-fqT] TXNAME
Copied!
Sign a transaction in the wallet. -f force. -q quiet. -T TxID.

status

1
factom-cli status [-TSUD] TxID|FullTx
Copied!
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

1
factom-cli subtxfee TXNAME ADDRESS
Copied!
Subtract the transaction fee from an output of a transaction in the wallet

unlockwallet

1
factom-cli unlockwallet [-v] "passphrase" <seconds-to-unlock>
Copied!
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.)
Last modified 1yr ago