Wallet command line interface

Overview

The CLI is a proxy to the wallet server, which is required for most commands. Commands are turned into corresponding API calls, and submitted to an up-and-running server. Some commands do not require an active server and can be run "offline". (e.g. 'recovery-phrase generate')

The wallet command-line interface (abbrev. CLI) is a tool that provides a convenient way of using the cardano-wallet HTTP Application Programming Interface (abbrev. API). The wallet API is an HTTP service used to manage wallets, make payments, and update wallet data such as addresses and keys, for instance. The wallet CLI can start the wallet server, or run a number of commands on a running server, and supports most functions of the API itself.

The intended audience of the CLI are users who run a wallet API server outside of Daedalus and work with the cardano-wallet API directly - these include application developers, stake pool operators, and exchanges.

CLI commands allow you to make and track changes while maintaining the wallet API. The wallet CLI converts commands into corresponding API calls, submits them to a running server and display the server's responses in a readable way into the terminal.

Pre-Requisites

Install cardano-node by following instruction on the release notes.
Download the byronGenesis.json initial configuration file from Cardano configurations.

How to Run

You can explore the wallet CLI with:

$ cardano-wallet --help

Then, you can use a list of commands for various purposes, such as:

list, create, update, or delete wallets
create, submit, forget, or track fees in regards to transactions
list, create, and import wallet addresses
view network information and parameters
manage private and public keys

Each sub-command will also provide some additional help when passed --help. For example:

$ cardano-wallet transaction --help

Commands

Usage: cardano-wallet COMMAND
  Cardano Wallet Command-Line Interface (CLI)

Available OPTIONS:
  -h | --help

Available COMMANDS:
  serve                    Serve an HTTP API that listens for commands/actions.
  recovery-phrase
    generate               Generate an English recovery phrase
  wallet
    list                   List all known wallets
    create
      from-recovery-phrase Create a new wallet using a recovery-phrase
    get                    Fetch a particular wallet
    utxo                   Get a wallet's UTxO distribution
    update
      passphrase           Update a wallet's master passphrase
      name                 Update a wallet's name
    delete                 Forget a wallet and its metadata
  transaction
    create                 Create a transaction from a known wallet
    fees                   Estimate fees for a transaction
    list                   List the transactions associated with a wallet
    submit                 Submit an externally-signed transaction
    forget                 Forget a pending transaction with specified id
    get                    Get a transaction with specified id
  address
    list                   List all known addresses of a wallet
    create                 Create a new random address.
    import                 Import a random address generated elsewhere.
  network
    information            View network information
    parameters             View network parameters
    clock                  View NTP offset
  key
    from-recovery-phrase   Convert a recovery phrase to an extended private key
    child                  Derive child keys from a parent public or private key
    public                 Get the public counterpart of a private key
    inspect                Show information about a key
  stake-pool
    list                   List all known stake pools
  version                  Show the program's current version

ℹ️ The CLI commands for wallet, transaction and address only output valid JSON on stdout. So you may redirect the output to a file with > or pipe it into utility softwares like jq!

💝 For bash/zsh auto-completion, put the following script in your /etc/bash_completion.d:

cardano-wallet.sh

_cardano-wallet()
{
   local CMDLINE
   local IFS=$'\n'
   CMDLINE=(--bash-completion-index $COMP_CWORD)

   for arg in ${COMP_WORDS[@]}; do
       CMDLINE=(${CMDLINE[@]} --bash-completion-word $arg)
   done

   COMPREPLY=( $(cardano-wallet "${CMDLINE[@]}") )
}

complete -o filenames -F _cardano-wallet cardano-wallet

Commands

serve

Serve API that listens for commands/actions. Before launching user should start cardano-node.

cardano-wallet serve

  --help-tracing           Show help for tracing options
  --listen-address HOST    Specification of which host to the bind API server
                           to. Can be an IPv[46] address, hostname, or
                           '*'. (default: 127.0.0.1)
  --random-port            serve wallet API on any available port (conflicts
                           with --port)
  --port INT               port used for serving the wallet API. (default: 8090)
  --tls-ca-cert FILE       A x.509 Certificate Authority (CA) certificate.
  --tls-sv-cert FILE       A x.509 Server (SV) certificate.
  --tls-sv-key FILE        The RSA Server key which signed the x.509 server
                           certificate.
  --node-socket FILE       Path to the node's domain socket (POSIX)
                           or pipe name (Windows).
  --mainnet                Use Cardano mainnet protocol
  --testnet FILE           Path to the byron genesis data in JSON format.
  --staging FILE           Path to the byron genesis data in JSON format.
  --database DIR           use this directory for storing wallets. Run in-memory
                           otherwise.
  --sync-tolerance DURATION
                           time duration within which we consider being synced
                           with the network. Expressed in seconds with a
                           trailing 's'. (default: 300s)
  --shutdown-handler       Enable the clean shutdown handler (exits when stdin
                           is closed)
  --pool-metadata-fetching ( none | direct | SMASH-URL )
                           Sets the stake pool metadata fetching strategy.
                           Provide a URL to specify a SMASH metadata proxy
                           server, use "direct" to fetch directly from the
                           registered pool URLs, or "none" to completely disable
                           stake pool metadata. The initial setting is "none"
                           and changes by either this option or the API will
                           persist across restarts.
  --token-metadata-server URL
                           Sets the URL of the token metadata server. If unset,
                           metadata will not be fetched. By using this option,
                           you are fully trusting the operator of the metadata
                           server to provide authentic token metadata.
  --log-level SEVERITY     Global minimum severity for a message to be logged.
                           Individual tracers severities still need to be
                           configured independently. Defaults to "DEBUG".
  --trace-NAME SEVERITY    Individual component severity for 'NAME'. See
                               --help-tracing for details and available tracers.

Minimal Arguments

In order to start the wallet server, you'll need to provide at least the path to cardano-node's socket/pipe and a target network. That socket is automatically created when starting a cardano-node and it exists so long as the node remains running.

We also recommend to pass a --database option pointing to a directory on the file-system; without this option, the wallet will maintain a state in-memory which will vanish once stopped.

Runtime flags

By default, the wallet runs on a single core which is sufficient for most 'normal users'. Application running larger wallets like exchanges should configure the server to use multiple cores for some database blocking operations may have a visible negative effect on the overall server behavior. This can be achieved by providing specific runtime flags to the serve command delimited by +RTS <flags> -RTS. To configure the how much cores are available to the server, use the -N flag. For example, to configure 2 cores do:

cardano-wallet serve ... +RTS -N2 -RTS

Using +RTS -N4 -RTS will tell the server to use 4 cores. Note that there's little performance benefits between 2 and 4 cores for server running a single wallet, but there are visible performance improvements from 1 to 2.

Domain socket/named pipe

On POSIX systems (i.e. Linux and macOS), a UNIX domain socket is used for communication between the cardano-wallet and cardano-node processes.

On these systems, the --node-socket argument must be a path to a socket file. Note that there is a limitation on socket path lengths of about 100 characters or so.

On Windows systems, a Named Pipe is used instead.

Windows Named Pipes do not have filenames. So on Windows systems, the --node-socket argument must be a pipe name. Pipe names are a string of the form \\.\pipe\name. For example, \\.\pipe\cardano-wallet.

Examples

Mainnet

cardano-wallet serve \
  --mainnet \
  --node-socket CARDANO_NODE_SOCKET_PATH_OR_PIPE \
  --database ./wallets-mainnet

Testnet

Note that for testnets, a byron genesis file is required (see pre-requisites), even though the network is in the shelley era. This is because the chain is synced from the beginning of the first era.

cardano-wallet serve \
  --testnet testnet-byron-genesis.json \
  --node-socket CARDANO_NODE_SOCKET_PATH_OR_PIPE \
  --database ./wallets-testnet

Metadata

For the wallet to show stake pool metadata, you need to set --pool-metadata-fetching ( none | direct | SMASH-URL ). And for the wallet to show token metadata, you need to set --token-metadata-server URL.

Logging options for serve

serve accepts extra command-line arguments for logging (also called "tracing"). Use --help-tracing to show the options, the tracer names, and the possible log levels.

cardano-wallet serve --help-tracing

Additional tracing options:

  --log-level SEVERITY     Global minimum severity for a message to be logged.
                           Defaults to "DEBUG" unless otherwise configured.
  --trace-NAME=off         Disable logging on the given tracer.
  --trace-NAME=SEVERITY    Set the minimum logging severity for the given
                           tracer. Defaults to "INFO".

The possible log levels (lowest to highest) are:
  debug info notice warning error critical alert emergency

The possible tracers are:
  application    About start-up logic and the server's surroundings.
  api-server     About the HTTP API requests and responses.
  wallet-engine  About background wallet workers events and core wallet engine.
  wallet-db      About database operations of each wallet.
  pools-engine   About the background worker monitoring stake pools and stake pools engine.
  pools-db       About database operations on stake pools.
  ntp-client     About ntp-client.
  network        About network communication with the node.

example

Use these options to enable debug-level tracing for certain components of the wallet. For example, to log all database queries for the wallet databases, use:

$ cardano-wallet serve --trace-wallet-db=debug ...

Wallet command line interface

Overview

Pre-Requisites

How to Run

Commands

Commands

serve

Minimal Arguments

Runtime flags

Domain socket/named pipe

Examples

Mainnet

Testnet

Metadata

Logging options for serve

example

recovery-phrase generate

wallet list

wallet create from recovery-phrase

wallet get

wallet utxo

wallet update name

wallet update passphrase

wallet delete

transaction create

transaction fees

transaction list

transaction submit

transaction forget

transaction get

address list

address create

address import

network information

network parameters

network clock

key from-recovery-phrase

key child

key public

key inspect

stake-pool list

version

Clone this wiki locally