4. GNU Taler Wallet CLI Manual

This manual describes how to use the GNU Taler wallet command line interface (CLI).

The the wallet CLI is targeted at developers and operators, but not meant to be used by customers. It exposes all functionality that the more user-friendly interfaces (Android app, browser extension) offer. However, it provides more diagnostics and advanced features as well.

4.1. Installation

The easiest way to install the wallet is via NPM. Note that a recent version of Node.JS (>=12.20.1) is required.

We recommend to install the wallet package on a per-user basis. To do so, configure node and adjust your $PATH:

$ npm set prefix $HOME/.npm-global
$ export PATH=$HOME/.npm-global:$PATH

Now the wallet CLI can be installed without requiring elevated permissions:

$ npm set prefix $HOME/.npm-global
$ npm install -g @gnu-taler/taler-wallet-cli
$ taler-wallet-cli --version

4.2. Getting Help

The wallet CLI comes with built-in help. Invoke the wallet CLI (or any subcommand) with the --help flag to get help:

$ taler-wallet-cli --help
Usage: taler-wallet-cli COMMAND

Command line interface for the GNU Taler wallet.

  -h, --help             Show this message and exit.
  --wallet-db=VALUE      location of the wallet database file
  --timetravel=VALUE     modify system time by given offset in microseconds
  --inhibit=VALUE        Inhibit running certain operations, useful for debugging and testing.
  --no-throttle          Don't do any request throttling.
  -v, --version
  -V, --verbose          Enable verbose output.

  advanced               Subcommands for advanced operations (only use if you know what you're doing!).
  api                    Call the wallet-core API directly.
  backup                 Subcommands for backups
  balance                Show wallet balance.
  deposit                Subcommands for depositing money to payto:// accounts
  exchanges              Manage exchanges.
  handle-uri             Handle a taler:// URI.
  pending                Show pending operations.
  run-pending            Run pending operations.
  run-until-done         Run until no more work is left.
  testing                Subcommands for testing GNU Taler deployments.
  transactions           Show transactions.

4.3. Completing operations

Note that the CLI does not run as a background daemon. When starting operations that don’t immediately finish, the wallet needs to be run explicitly to finish any pending tasks:

# Do one attempt to finish all pending operations
$ taler-wallet-cli run-pending

# Run until all work is done
$ taler-wallet-cli run-until-done

4.4. Resetting the wallet

The wallet can be reset by deleting its database file. By default, the database file is $HOME/.talerwalletdb.json.

4.5. Handling taler:// URIs

Many interactions with the Taler wallet happen by scanning QR codes or special headers on Websites. To emulate this with the command line interface, run the following command:

$ taler-wallet-cli handle-uri $URI

4.6. Testing an exchange deployment

The following series of commands can be used to check that an exchange deployment is functional:

# This will now output a payto URI that money needs to be sent to in order to allow withdrawal
# of taler coins
$ taler-wallet-cli advanced withdraw-manually --exchange $EXCHANGE_URL --amount EUR:10.50

# Show the status of the manual withdrawal operation
$ taler-wallet-cli transactions

# Once the transfer has been made, try completing the withdrawal
$ taler-wallet-cli run-pending

# Check status of transactions and show balance
$ taler-wallet-cli transactions
$ taler-wallet-cli balance

# Now, directly deposit coins with the exchange into a target account
# (Usually, a payment is made via a merchant.  The wallet provides
# this functionality for testing.)
$ taler-wallet-cli deposit create EUR:5 payto://sepa/$IBAN

# Check if transaction was successful.
# (If not, fix issue with exchange and run "run-pending" command again)
$ taler-wallet-cli transactions

# The wallet can also track if the exchange wired the money to the merchant account.
# The "deposit group id" can be found in the output of the transactions list.
$ taler-wallet-cli deposit track $DEPOSIT_GROUP_ID