summaryrefslogtreecommitdiff
path: root/taler-wallet-cli-manual.rst
blob: 0758f9ef6348ee914535dbee33ba267b384202d8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
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.

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``:

.. code-block:: console

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

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

.. code-block:: console

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


Getting Help
------------

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

.. code-block:: console

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

  Command line interface for the GNU Taler wallet.

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

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

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:


.. code-block:: console

  # 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

Resetting the wallet
--------------------

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


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:

.. code-block:: console

  $ taler-wallet-cli handle-uri $URI


Testing an exchange deployment
------------------------------

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

.. code-block:: console

  # 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