bitmark-cli Command Reference
Basic Command Structure
The basic structure of bitmark-cli
commands is:
bitmark-cli [global-options] command [command-options]
Global Options
Global options have both long-form and single character abbreviations:
--verbose|-v
An option to output additional information
for each command. Most commands will
output the JSON request and the response
sent to the bitmarkd.
--network|-n NETWORK
The network the
command will be sent to, from these
values:
* bitmark
, the live network, which uses live BTC or LTC to pay for transactions.
* testing
, a network for testing newly developed programs, which uses testnet coins to pay for transactions.
* local
, a special case for running a regression test network on the loopback interface.
--connection|-c NUMBER
A
connection listed in the
configuration file that should be used, instead
of defaulting to the first one.
--identity|-i NAME
An account to run commands as.
See “Options: identity” for more details.
--password|-p PASSWORD
A password, primarily used for regeression testing scripts. It is
not recommended for normal use, as the
password will be left in the command
history and be viewable by process
display commands such as top
and ps
.
--use-agent|-u EXECUTABLE
Access method for a password
stored in a password manager. See “Options: agent program” for more details.
--zero-agent-cache|-z
An option to prepend a --clear
to the argument list of
the --use-agent
command, to force
the password manager to re-prompt for
the password.
——————————- ———————————
Options: Identity
A short mnemonic identity string is used to represent each Bitmark account. These identities are stored in the configuration file and contain three parts:
- The password-protected private key, used for signing transactions.
- The public Account Number (a Base58 string), used as the recipient in transfers.
- A description that holds additional text, which is never sent to blockchain.
After initial setup that first identity is normally used to sign all
transactions. However, it can be overridden by the global --identity
option.
Options: Agent Programs
The CLI program can use an external program or an executable script to
request the password from a password manager. The CLI provides
a cache-id
parameter that allows this program to determine which password is
required. Other parameters are used for display
purposes and correspond to the data required by the GNU Privacy Guard
password dialog.
0: --clear = clears any cached password to force reprompt
[only if zero-agent-cache option is set]
1: --confirm=1 = for additional confirmation
2: cache-id = "bitmark-cli:password:<IDENTITY>"
3: error-message = ""
4: prompt = "<IDENTITY>"
5: description = shows create/transfer operation as a descriptive string
A sample ask-gpg-agent
script is provided in the bitmarkd
source
code repository; it can be used as a model to create a similar script for
other password managers.
CLI Command Synopsis
setup Initialize bitmark-cli configuration file add Add a new identity to configuration file create Create one or more new bitmarks transfer Transfer a bitmark to another account countersign Countersign a two-signature transaction blocktransfer Transfer a block to another account provenance List provenance of a bitmark owned List bitmarks owned share Convert a bitmark into a share grant Grant some shares of a bitmark to a receiver swap Swap some shares of a bitmark with a receiver balance Display balance of some shares status Display the status of a bitmark list List bitmark-cli identities bitmarkd Display bitmarkd information seed Decrypt and display identity’s recovery seed password Change identity’s password fingerprint Fingerprint a file (version 01 SHA3-512 algorithm) sign Sign file verify Verify file signature file version Display bitmark-cli version help Show a list of commands or help for one command ————- ———————————
CLI commands
setup
Creates the initial configuration file for a network and sets the default identity. There are separate files for each network.
Arguments. Both the --network
and --identity
global options must
be set.
Additional input. Before creating the file, the CLI will prompt for a password to encrypt the generated seed. Be sure to choose a good random password to secure the account’s private key.
Errors. If the configuration file already exists, this command will terminate with an error and not modify the file.
Bugs. Currently only adds one connection, with no way to update this other than manual editing of the configuration file.
Command options
--connect|-c HOST:PORT
The default bitmarkd connection. This
TCP connection will be used for all data
submitted to the blockchain.
--description|-d "STRING"
A description string for the initial
identity. This is only for the CLI
user; it is not used by any command and is not
sent over the network.
--new|-n
An option that specifies that a new account seed is to be generated.
--seed|-s SEED-STRING
Used in place of --new
. An
existing account seed to be placed into the CLI
configuration file. The CLI accepts
both V1 and V2 Base58-encoded seeds.
—————————— ———————————
Example
bitmark-cli --identity=fred --network=testing setup --connect=node-d1.test.bitmark.com:2130 --description="Bedrock Bowling Champion" --new
add
Updates the configuration file by adding a new identity on a network.
Arguments. Both the --identity
and --network
global options must
be specified.
Additional input. Before creating the file, the CLI will prompt for a
password to encrypt the generated seed. Choose a good random password
to secure the account’s private key. The password is not prompted
when using the --account
option since only the public key is
present.
Errors. The identity must not already exist or the command will terminate with an error and not modify the file.
Command options
--description|-d "STRING"
A description string for the initial identity.
This is only descriptive text for the CLI user; it
is not used by any command nor sent over the network.
--new|-n
An option that specifies that a new account seed is to be generated.
--seed|-s SEED-STRING
Used in place of --new
. An
existing account seed to be placed into the CLI
configuration file. The CLI accepts
both V1 and V2 Base58-encoded seeds.
--account|-a ACCOUNT-STRING
Used in place of --new
or --seed
. An existing
account to be imported into the CLI configuration file. Since only the
public key is contained within the Base58-encoded account, this
identity cannot be used for signing items. It is meant for use as
the recipient of a transfer.
—————————— ———————————
Example
bitmark-cli --identity=wilma --network=testing add --description="The real Ruler" --new
create
Creates a bitmark by sending both an asset record and one or more issue records.
Arguments. The --network
global option must be specified.
Additional input. Before creating the Bitmark, the CLI will prompt for a password to decrypt the identity’s private key to perform the signing operation.
Errors. The command will terminate with an error if the asset name
or metadata do not match exactly when creating additional Bitmarks.
In the “free issue (--zero
)”, case there will be an error if this issue
already exists.
Command options
--asset|-a "STRING"
A short name for the asset being issued.
--metadata|-m "METADATA"
A key-value map of data providing details
about the asset. Keys and values
are separated by a zero byte, which is
represented using JSON encoding as
"\u0000"
.
--fingerprint|-f "STRING"
A
globally unique identifier for an
asset, represented as any type of string. There is a fingerprint
command
that will give the same hex string that
Bitmark Inc. applications also use.
--zero|-z
An option that restricts the issue to the initial free one.
(See “Free issues” below)
--quantity|-q NUMBER
The number of Bitmarks to issue for a single payment, up to 100. If
the free issue has not been created,
then only a quantity of one is allowed,
and this issue must be confirmed
before a larger quantity is allowed.
—————————— ———————————
Example
bitmark-cli --identity=fred --network=testing create --asset='Fred Flintstone' --metadata='desc\u0000photo of Fred Flintstone\u0000src\u0000Wikipedia' --fingerprint=01ee0039791329016fc93e083ede6bd4266ed6f65812b483c05b5bf75252112178a4ffeeb4ede5949c6e4d9e26fba00f95fbc71b4fa7c5a9220bec49e6c18848fe
Note: Free issues
For any asset, there is a special issue that is free of cost. Even if the asset already exists, a different Bitmark account can create a free issue for it. Internally the issue record has a NONCE value of zero.
This leads to the following cases:
-
For a new asset, a free issue must be made and must be confirmed before any other issue can be made against this asset. Trying to issue quantity greater than one in this case will always fail as the confirmed asset does not yet exist.
-
For a confirmed existing asset, an account that never made an issue against this asset could choose to make its single free issue or simply issue a quantity of two or more and pay for them. In this case, the free issue does not have to be used, but the CLI will always attempt to make a free issue for a one-off issue and try a paid issue if it cannot.
transfer
Transfers a bitmark to another account.
The default case is to perform a two-signature transfer, which requires
the use of the countersign
command to produce the final record to
send to the blockchain.
If the unratified mode is used instead, then the transfer is sent immediately and the payment details are returned.
Arguments. The --network
global option must be specified.
Additional input. Before transferring a Bitmark, the CLI will prompt for a password to decrypt the identity’s private key to perform the signing operation.
Errors. The command will terminate with an error if the transfer cannot be validated by the blockchain.
Command options
--txid|-t HEX-ID
The transaction id from a previous issue or transfer.
--receiver|-r IDENTITY|ACCOUNT
The identity name for the account or else the
account itself (in Base58) as the
destination of the transfer. If an
identity is used it can be either a
full account or a public-key-only
item. It is not necessary to know
the password for this, and only the
sender (specified by global identity
option) needs to sign.
--unratified|-u
An option that specifies the single-signature transfer mode. In
this case, the transfer is sent
directly to the block chain and
payment information is shown.
——————————- ———————————
Example
bitmark-cli --identity=fred --network=testing transfer --txid=8981eb58c965e2360b3ffeedf47d8f770a2fff7f67e5c348302d839afbf83dee --receiver=barney
countersign
Completes a two-signature operation. This command takes the hex code from the operation and signs with the global identity.
Arguments. The --network
global option must be specified.
Additional input. Before creating the Bitmark, the CLI will prompt for a password to decrypt the identity’s private key to perform the signing operation.
Errors. The command will terminate with an error if this identity does not match the receiver in the transaction.
Command options
--transaction|-t HEX-DATA
The transaction hex data from a previous
transfer or other two-signature
operation. This data will only have a
single signature.
——————————- ———————————
Example
bitmark-cli --identity=barney --network=testing countersign --transaction=05208981eb58c965e2360b3ffeedf47d8f770a2fff7f67e5c348302d839afbf83dee0021138a0b5c7ed5ab0c80bfd3968749e824f599bbf05540c045d26f72cedbfdb49977403e421917b8c1fbaa385b023fb84f19660e1b6f85e0f09473d6f7143de2450fba99dd931d2d42c01133e9e749dcb1d8a729114c0fe007a1617304f255274a7108
blocktransfer
Transfers the ownership of a block to another account and/or changes the cryptocurrency addresses.
This can only be used if the account belonging to a miner is added to the CLI configuration.
Arguments. The --network
global option must be specified.
Additional input. Before creating the Bitmark, the CLI will prompt for a password to decrypt the identity’s private key to perform the signing operation.
Errors. The command will terminate with an error if the blockchain cannot validate the transaction.
Command options
--txid|-t HEX-ID
The transaction id from a previous issue or
transfer.
--receiver|-r IDENTITY|ACCOUNT
The identity name for the account or else the
actual account (in Base58) as the
destination of the transfer. If an
identity is used, it can be either a
full account or a public-key-only
item. It is not necessary to know
the password for this and only the
sender (specified by global identity
option) needs to sign.
--bitcoin|-b ADDRESS
A valid Bitcoin address for the corresponding
network. All future earnings from
the block will be sent to the new
address.
--litecoin|-l ADDRESS
A valid Litecoin address for the corresponding
network. All future earnings from
the block will be sent to the new
address.
——————————- ———————————
Example
bitmark-cli --identity=fred --network=testing blocktransfer --txid=
provenance
Displays the provenance of an asset starting from a particular transaction id and moving back
in time toward the issue record. Since the record count is limited,
it may be necessary to use the last transaction id with a new call to
provenance
to display more records, then repeat until the entire asset
record is output.
Arguments. The --network
global option must be specified.
Command options
--txid|-t HEX-ID
The transaction id from a previous issue or
transfer.
--count|-c NUMBER
Limit for the number of provenance records displayed.
This defaults to 20 records if omitted
and can be set from 1 to 100.
—————————— ———————————
Example
bitmark-cli --identity=fred --network=testing provenance --txid=8981eb58c965e2360b3ffeedf47d8f770a2fff7f67e5c348302d839afbf83dee --count=10
owned
Displays the ownership records for a given identity or account
Arguments. The --network
global option must be specified.
Command options
--owner|-o IDENTITY|ACCOUNT
A different account to list records for, specified either by
an identity or a Base58
account string. The default is to use
the global identity.
--start|-s NUMBER
An alternate start point rather the the default
of zero. The output JSON includes a
field next
, which if non-zero means
there are more records to display.
Just use the value of next
in
subsequent owned
commands to page
though all ownership records.
--count|-c NUMBER
Limit for the number of ownership records displayed.
This defaults to 20 records if omitted
and can be set from 1 to 100.
—————————— ———————————
Example
bitmark-cli --identity=fred --network=testing owned
bitmark-cli --identity=fred --network=testing owned --owner barney
bitmark-cli --identity=fred --network=testing owned --owner eywWbSGcYaYPkY4e2aerGWRs1fNoaSDxh3BgLVENgBZmhTsdLz
share
Converts a Bitmark into a fractions. Once this is done, the provenance
is ended and only grant
or swap
commands can operate on the
fractions created. The quantity of shares created must be some
meaningful value and once set can never be changed.
Arguments. The --network
global option must be specified.
Additional input. Before creating the Bitmark Share, the CLI will prompt for a password to decrypt the identity’s private key to perform the signing operation.
Errors. The command will terminate with an error if the transaction id is already converted to shares.
Command options
--txid|-t HEX-ID
The transaction id from a previous
issue or transfer.
--quantity|-d NUMBER
A quantity of
fractions to split the Bitmark into, up to the limit of an
unsigned 64-bit number. This sets the
total number of shares available and is a
permanent limit.
——————————- ———————————
Example
bitmark-cli --identity=fred --network=testing share --txid=8981eb58c965e2360b3ffeedf47d8f770a2fff7f67e5c348302d839afbf83dee --quantity=1000000
grant
Transfers a number of shares of a particular share-id to a receiver.
Arguments. The --network
global option must be specified.
Additional input. Before granting the Bitmark Share, the CLI will prompt for a password to decrypt the identity’s private key to perform the signing operation.
Errors. The command will terminate with an error if the share quantity is greater than the remaining balance.
Command options
--receiver|-r IDENTITY|ACCOUNT
The identity or Base58 account that
is to receive the shares.
--share-id|-s SHARE-ID
The transaction id of the share record,
which is used to identify the fractional item.
--quantity|-q NUMBER
The quantity of share to grant to the receiving
account. The default is one, but it can
be any value up to the current
balance of the owner.
--before-block|-b NUMBER
A time limit for
the operation: the transaction
must be submitted and confirmed
before this block is present on the
blockchain.
——————————- ———————————
Example
bitmark-cli --identity=fred --network=testing grant --receiver=barney --share-id=8981eb58c965e2360b3ffeedf47d8f770a2fff7f67e5c348302d839afbf83dee --quantity=1000 --before-block=234765
swap
Performs an atomic swap between two different shares.
The system ensures the swap occurs as a single operation and that there is no
possibility of partial completion. This is a two-signature command
and the recipient must use countersign
to submit and pay before the
expiry block is reached on the blockchain.
Arguments. The --network
global option must be specified.
Additional input. Before granting the Bitmark Share, the CLI will prompt for a password to decrypt the identity’s private key to perform the signing operation.
Errors. The command will terminate with an error if the share quantities are greater than the remaining balances.
Command options
--receiver|-r IDENTITY|ACCOUNT
The countersigner identity or Base58
account.
--share-id-one|-s SHARE-ID
The transaction id of the share record,
that the initiator is sending, used
to identify the first fractional item.
--quantity-one|-q NUMBER
The quantity of share-id-one
that the
initiator is granting to the countersigner.
The default is one, but it can be any value up to the
current balance of the initiator.
--share-id-two|-S SHARE-ID
The transaction id of the share record,
that the countersigner is sending, used
to identify the second fractional item.
--quantity-two|-Q NUMBER
The quantity of share-id-two
that the
countersigner is granting to the
initiator. The default is
one, but it can be any value up to the
current balance of the countersigner.
--before-block|-b NUMBER
A time limit for
the operation: the transaction
must be submitted and confirmed
before this block is present on the
blockchain.
——————————- ———————————
Example
bitmark-cli --identity=fred --network=testing swap --receiver=barney --share-id-one=8981eb58c965e2360b3ffeedf47d8f770a2fff7f67e5c348302d839afbf83dee --quantity-one=1000 --share-id-two=1bf75e25d7770ba6405500d39cac30f40249927fd3ee46beae42c9d9b85202f8 --quantity-otwo=79 --before-block=234765 --before-block=234765
balance
Displays the share balances for a particular owner.
The display starts at a particular id and outputs count
items. To
display more, take the last share id displayed and use that in another balance
command. (To avoid a repeat of that record, use the incremented id as
the command to search for the next used id.)
Arguments. The --network
global option must be specified.
Command options
--owner|-o IDENTITY|ACCOUNT
An account, specified
either by an identity or a Base58
account string. The default is to
list balances for the global identity.
--share-id|-s SHARE-ID
The transaction id of the share record, which
is used to identify the fractional
item to show the balance.
--count|-c NUMBER
A limit on the number of balance records displayed.
This defaults to 20 records if
omitted and can be set from 1 to 100.
——————————- ———————————
Example
bitmark-cli --identity=fred --network=testing balance --owner=barney --share-id=8981eb58c965e2360b3ffeedf47d8f770a2fff7f67e5c348302d839afbf83dee --count=10
status
Displays the status of a particular transaction id, to see whether it is:
Not found
: transaction not present on the blockchain or in that node’s memory.Pending
: transaction awaiting payment confirmation.Verified
: payment is confirmed, and the transaction is waiting to be incorporated into a block.Confirmed
: transaction stored on the blockchain.
Arguments. The --network
global option must be specified.
Command options
--txid|-t HEX-ID
The transaction id from a previous
issue or transfer.
——————————- ———————————
Example
bitmark-cli --network=testing status --txid=8981eb58c965e2360b3ffeedf47d8f770a2fff7f67e5c348302d839afbf83dee
list
Displays all the configuration file identities’ public data:
The returned information includes:
SK
flag to indicate the encrypted seed is present- The short identity name
- Base58 account string (the encoded public key)
- Descriptive text
Arguments. The --network
global option must be specified.
Example
bitmark-cli --network=testing list
bitmarkd
Displays basic blockchain status from the selected bitmark node program.
Arguments. The --network
global option must be specified.
Example
bitmark-cli --network=testing bitmarkd
bitmark-cli --network=testing --connection=2 bitmarkd
seed
Displays the decrypted seed. The output is a JSON block containing all account data both public and private.
Arguments. The --network
global option must be specified.
Additional input. Before displaying the seed, the CLI will prompt for a password to decrypt the identity’s private key to be able to display it.
Command options
--recovery|-r
Only display the words of the recovery
phrase in plain text.
——————————- ———————————
Examples
bitmark-cli --identity=fred --network=testing seed
bitmark-cli --identity=fred --network=testing seed --recovery
password
Changes the password of the selected identity.
Arguments. The --network
global option must be specified.
Additional input. The CLI will prompt for a password, then prompt for the new password. The new password will be prompted a second time to ensure that the password was entered accurately.
Example
bitmark-cli --identity=fred --network=testing password
fingerprint
Displays a fingerprint that is compatible with the method used by other Bitmark Inc applications. The result is shown as a hexadecimal string.
Arguments. The --network
global option must be specified.
Command options
--file|-f PATH-NAME
The file for the fingerprint.
——————————- ———————————
Example
bitmark-cli --network=testing fingerprint --file=Fred_Flintsone.png
sign
Displays a signature for a file. The result is shown as a hexadecimal string.
Arguments. The --network
global option must be specified.
Additional input. The CLI will prompt for a password to decrypt the private key to perform the signing operation.
Command options
--file|-f PATH-NAME
The file to sign
——————————- ———————————
Example
bitmark-cli --identity=fred --network=testing sign --file=Fred_Flintsone.png
verify
Verifies the signature of a file matches the expected owner. This is
the corresponding command to the sign
command.
Arguments. The --network
global option must be specified.
Errors. The command will indicate an error if the signature does not match.
Command options
--file|-f PATH-NAME
The file to verify
--signature|-s HEX
The signature hex string from the sign command
--owner|-o IDENTITY|ACCOUNT
The signer to check, specified by an identity
or a Base58 account string. The
default is to use the global identity.
——————————- ———————————
Example
bitmark-cli --network=testing verify --file=Fred_Flintsone.png --owner=fred
version
Displays the version of the CLI program.
Example
bitmark-cli --network=testing version