Command-Line Interface

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

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

> cardano-wallet --help

Warning

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 software like jq!

serve

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

Usage: cardano-wallet serve [--listen-address HOST]
                            (--node-socket FILE [--sync-tolerance DURATION])
                            [--random-port | --port INT]
                            [--tls-ca-cert FILE --tls-sv-cert FILE
                              --tls-sv-key FILE]
                            (--mainnet | --testnet FILE )
                            [--database DIR] [--shutdown-handler]
                            [--pool-metadata-fetching ( none | direct | SMASH-URL )]
                            [--token-metadata-server URL]
                            [--trace-NAME SEVERITY]

  Serve API that listens for commands/actions.

Available options:
  -h,--help                Show this help text
  --help-tracing           Show help for tracing options
  --listen-address HOST    Specification of which host to bind the API server
                           to. Can be an IPv[46] address, hostname, or '*'.
                           (default: 127.0.0.1)
  --node-socket FILE       Path to the node's domain socket file (POSIX) or pipe
                           name (Windows). Note: Maximum length for POSIX socket
                           files is approx. 100 bytes. Note: Windows named pipes
                           are of the form \\.\pipe\cardano-node
  --sync-tolerance DURATION
                           time duration within which we consider being synced
                           with the network. Expressed in seconds with a
                           trailing 's'. (default: 300s)
  --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.
  --mainnet                Use Cardano mainnet protocol
  --testnet FILE           Path to the byron genesis data in JSON format.
  --database DIR           use this directory for storing wallets. Run in-memory
                           otherwise.
  --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

Info

More information on starting the wallet server can be found in Start a server.

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 ...

recovery-phrase generate

> cardano-wallet recovery-phrase generate [--size=INT]

Generates an English recovery phrase.

> cardano-wallet recovery-phrase generate

These words will be used to create a wallet later. You may also ask for a specific number of words using the --size option:

> cardano-wallet recovery-phrase generate --size 21

wallet list

> cardano-wallet wallet list [--port=INT]

Lists all your wallets:

> cardano-wallet wallet list

wallet create from recovery-phrase

> cardano-wallet wallet create from-recovery-phrase [--port=INT] <name> [--address-pool-gap=INT]

Create a new wallet using a sequential address scheme. This is an interactive command that will prompt you for recovery-phrase words and password.

> cardano-wallet wallet create "My Wallet"
Please enter a 15–24 word recovery-phrase sentence: <enter generated recovery-phrase here>
(Enter a blank line if you do not wish to use a second factor.)
Please enter a 9–12 word recovery-phrase second factor: <skip or enter new recovery-phrase here>
Please enter a passphrase: ****************
Enter the passphrase a second time: ****************

after this your new wallet will be created

wallet get

> cardano-wallet wallet get [--port=INT] WALLET_ID

Fetches the wallet with specified wallet id:

> cardano-wallet wallet get 2512a00e9653fe49a44a5886202e24d77eeb998f

wallet utxo

> cardano-wallet wallet utxo [--port=INT] WALLET_ID

Visualize a wallet's UTxO distribution in the form of an histrogram with a logarithmic scale. The distribution's data is returned by the API in a JSON format, e.g.:

{
  "distribution": {
      "10": 1,
      "100": 0,
      "1000": 8,
      "10000": 14,
      "100000": 32,
      "1000000": 3,
      "10000000": 0,
      "100000000": 12,
      "1000000000": 0,
      "10000000000": 0,
      "100000000000": 0,
      "1000000000000": 0,
      "10000000000000": 0,
      "100000000000000": 0,
      "1000000000000000": 0,
      "10000000000000000": 0,
      "45000000000000000": 0
  }
}

which could be plotted as:

    │
100 ─
    │
    │                                 ┌───┐
 10 ─                         ┌───┐   │   │                   ┌───┐
    │                 ┌───┐   │   │   │   │                   │   │
    │                 │   │   │   │   │   │   ┌───┐           │   │
  1 ─ ┌───┐           │   │   │   │   │   │   │   │           │   │
    │ │   │           │   │   │   │   │   │   │   │           │   │
    │ │   │ │       │ │   │ │ │   │ ╷ │   │ ╷ │   │ ╷       ╷ │   │      ╷
    └─┘   └─│───────│─┘   └─│─┘   └─│─┘   └─│─┘   └─│───────│─┘   └──────│────────────
          10μ₳    100μ₳   1000μ₳   0.1₳    1₳      10₳     100₳        1000₳

wallet utxo-snapshot

> cardano-wallet wallet utxo-snapshot [--port INT] WALLET_ID

Gets a snapshot of the wallet's entire UTxO set, in JSON format.

Each entry in the list contains the following fields:

FieldDescription
adathe actual ada quantity of this UTxO entry
ada_minimumthe minimum ada quantity permitted by the protocol
assetsquantities of all other assets included in this UTxO entry
{
    "entries": [
        {
            "ada_minimum": {
                "quantity": 1666665,
                "unit": "lovelace"
            },
            "ada": {
                "quantity": 15582575,
                "unit": "lovelace"
            },
            "assets": [
                {
                    "asset_name": "",
                    "quantity": 1503,
                    "policy_id": "789ef8ae89617f34c07f7f6a12e4d65146f958c0bc15a97b4ff169f1"
                },
                {
                    "asset_name": "4861707079436f696e",
                    "quantity": 4958,
                    "policy_id": "919e8a1922aaa764b1d66407c6f62244e77081215f385b60a6209149"
                }
            ]
        },
        ...
    ]
}

⚠ This endpoint was intended to be used for debugging purposes. The output format is subject to change at any time.

wallet update name

> cardano-wallet wallet update name [--port=INT] WALLET_ID STRING

Updates name of a wallet given wallet id:

> cardano-wallet wallet update name 2512a00e9653fe49a44a5886202e24d77eeb998f NewName

wallet update passphrase

> cardano-wallet wallet update passphrase [--port=INT] WALLET_ID

Interactive prompt to update the wallet master's passphrase (old passphrase required).

> cardano-wallet wallet update passphrase 2512a00e9653fe49a44a5886202e24d77eeb998f
Please enter your current passphrase: **********
Please enter a new passphrase: **********
Enter the passphrase a second time: **********

wallet delete

> cardano-wallet wallet delete [--port=INT] WALLET_ID

Deletes wallet with specified wallet id:

> cardano-wallet wallet delete 2512a00e9653fe49a44a5886202e24d77eeb998f

transaction create

> cardano-wallet transaction create [--port=INT] WALLET_ID [--metadata=JSON] [--ttl=SECONDS] --payment=PAYMENT...

Creates and submits a new transaction:

> cardano-wallet transaction create 2512a00e9653fe49a44a5886202e24d77eeb998f \
    --payment 22@Ae2tdPwUPEZ...nRtbfw6EHRv1D \
    --payment 5@Ae2tdPwUPEZ7...pVwEPhKwseVvf \
    --metadata '{ "0":{ "string":"cardano" } }'

This creates a transaction that sends 22 lovelace to Ae2tdPwUPEZ...nRtbfw6EHRv1D and 5 lovelace to Ae2tdPwUPEZ7...pVwEPhKwseVvf from wallet with id 2512a00e9653fe49a44a5886202e24d77eeb998f.

For more information about the --metadata option, see TxMetadata.

transaction fees

> cardano-wallet transaction fees [--port=INT] WALLET_ID [--metadata=JSON] [--ttl=SECONDS] --payment=PAYMENT...

Estimates fee for a given transaction:

> cardano-wallet transaction fees 2512a00e9653fe49a44a5886202e24d77eeb998f \
    --payment 22@Ae2tdPwUPEZ...nRtbfw6EHRv1D \
    --payment 5@Ae2tdPwUPEZ7...pVwEPhKwseVvf \
    --metadata '{ "0":{ "string":"cardano" } }'

This estimates fees for a transaction that sends 22 lovelace to Ae2tdPwUPEZ...nRtbfw6EHRv1D and 5 lovelace to Ae2tdPwUPEZ7...pVwEPhKwseVvf from wallet with id 2512a00e9653fe49a44a5886202e24d77eeb998f.

transaction list

> cardano-wallet transaction list [--port INT] WALLET_ID [--start TIME] [--end TIME] [--order ORDER] [--simple-metadata] [--max_count MAX_COUNT]

List the transactions associated with a wallet.

> cardano-wallet transaction list 2512a00e9653fe49a44a5886202e24d77eeb998f \
    --start 2018-09-25T10:15:00Z \
    --end 2019-11-21T10:15:00Z \
    --order ascending \
    --max_count 10

This lists max 10 transactions between 2018-09-25T10:15:00Z and 2019-11-21T10:15:00Z in ascending order.

transaction submit

> cardano-wallet transaction submit [--port INT] BINARY_BLOB

Submit transaction prepared and signed outside of the wallet:

> cardano-wallet transaction submit 00bf02010200000...d21942304

Sends transaction identified by a hex-encoded BINARY_BLOB of externally-signed transaction.

transaction forget

> cardano-wallet transaction forget [--port INT] WALLET_ID TRANSACTION_ID

Forget pending transaction for a given wallet:

> cardano-wallet transaction forget 2512a00e9653fe49a44a5886202e24d77eeb998f 3e6ec12da4414aa0781ff8afa9717ae53ee8cb4aa55d622f65bc62619a4f7b12

transaction get

> cardano-wallet transaction get [--port INT] WALLET_ID TRANSACTION_ID

Get a transaction with the specified id:

> cardano-wallet transaction get 2512a00e9653fe49a44a5886202e24d77eeb998f 3e6ec12da4414aa0781ff8afa9717ae53ee8cb4aa55d622f65bc62619a4f7b12

address list

> cardano-wallet address list [--port=INT] WALLET_ID [--state=STRING]

List all known (used or not) addresses and their corresponding status.

> cardano-wallet list addresses 2512a00e9653fe49a44a5886202e24d77eeb998f

address create

> cardano-wallet address create [--port INT] [--address-index INDEX] WALLET_ID

Create new address for random wallet.

> cardano-wallet address create 03f4c150aa4626e28d02be95f31d3c79df344877
Please enter your passphrase: *****************
Ok.
{
    "state": "unused",
    "id": "2w1sdSJu3GVgr1ic6aP3CEwZo9GAhLzigdBvCGY4JzEDRbWV4HUNpZdHf2n5fV41dGjPpisDX77BztujAJ1Xs38zS8aXvN7Qxoe"
}

address import

> cardano-wallet address import [--port INT] WALLET_ID ADDRESS

Import address belonging to random wallet.

network information

> cardano-wallet network information [--port=INT]

View network information and syncing progress between the node and the blockchain.

> cardano-wallet network information

network parameters

> cardano-wallet network parameters [--port=INT] EPOCH_NUMBER

View network parameters. EPOCH_NUMBER can be latest or valid epoch number (not later than the current one), ie., 0, 1, .. .

> cardano-wallet network parameters latest

network clock

> cardano-wallet network clock

View NTP offset for cardano-wallet server in microseconds.

> cardano-wallet network clock
Ok.
{
    "status": "available",
    "offset": {
        "quantity": -30882,
        "unit": "microsecond"
    }
}

Warning

At this stage the command is not supported on Windows platform. Invoked on Windows will return status: unavailable in the response message.

key from-recovery-phrase

Extract the root extended private key from a recovery phrase. New recovery phrases can be generated using recovery-phrase generate.

Usage: cardano-wallet key from-recovery-phrase ([--base16] | [--base58] | [--bech32]) STYLE
  Convert a recovery phrase to an extended private key

Available options:
  -h,--help                Show this help text
  STYLE                    Byron | Icarus | Jormungandr | Shelley

The recovery phrase is read from stdin.

Example:

> cardano-wallet recovery-phrase generate | cardano-wallet key from-recovery-phrase Icarus
xprv12qaxje8hr7fc0t99q94jfnnfexvma22m0urhxgenafqmvw4qda0c8v9rtmk3fpxy9f2g004xj76v4jpd69a40un7sszdnw58qv527zlegvapwaee47uu724q4us4eurh52m027kk0602judjjw58gffvcqzkv2hs

key child

Derive child key from root private key. The parent key is read from standard input.

Usage: cardano-wallet key child ([--base16] | [--base58] | [--bech32]) [--legacy] DERIVATION-PATH
  Derive child keys from a parent public/private key

Available options:
  -h,--help                Show this help text
  DERIVATION-PATH          Slash-separated derivation path.
                           Hardened indexes are marked with a 'H' (e.g. 1852H/1815H/0H/0).

The parent key is read from stdin.

Example:

> cardano-wallet recovery-phrase generate | cardano-wallet key from-recovery-phrase Icarus > root.xprv
cat root.xprv | cardano-wallet key child 44H/1815H/0H/0
xprv13parrg5g83utetrwsp563w7hps2chu8mwcwqcrzehql67w9k73fq8utx6m8kgjlhle8claexrtcu068jgwl9zj5jyce6wn2k340ahpmglnq6x8zkt7plaqjgads0nvmj5ahav35m0ss8q95djl0dcee59vvwkaya

key public

Extract the public key of an extended private key. Keys can be obtained using key from-recovery-phrase and key child.

Usage: cardano-wallet-jormungandr key public ([--base16] | [--base58] | [--bech32])
  Get the public counterpart of a private key

Available options:
  -h,--help                Show this help text

The private key is read from stdin.

Example:

> cardano-wallet recovery-phrase generate | cardano-wallet key from-recovery-phrase Icarus > root.xprv
cat root.xprv | cardano-wallet key public
xpub1le8gm0m5cesjzzjqlza4476yncp0yk2jve7cce8ejk9cxjjdama24hudzqkrxy4daxwmlfq6ynczj338r7f5kzs43xs2fkmktekd4fgnc8q98

key inspect

Usage: cardano-wallet-jormungandr key inspect
  Show information about a key

Available options:
  -h,--help                Show this help text

The parent key is read from stdin.

stake-pool list

Usage: cardano-wallet stake-pool list [--port INT] [--stake STAKE]
  List all known stake pools.

Available options:
  -h,--help                Show this help text
  --port INT               port used for serving the wallet API. (default: 8090)
  --stake STAKE            The stake you intend to delegate, which affects the
                           rewards and the ranking of pools.

version

> cardano-wallet version

Show the software version.

Bash Shell Command Completion

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

# /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