summaryrefslogtreecommitdiff
path: root/taler-wallet-cli-manual.rst
diff options
context:
space:
mode:
authorFlorian Dold <florian@dold.me>2021-01-24 15:20:21 +0100
committerFlorian Dold <florian@dold.me>2021-01-24 15:20:21 +0100
commitce6f02324134436a5ddb5875ca1259a66168e135 (patch)
tree0cfaed5c5205a2eb282e7b58a7fbeeff0957d317 /taler-wallet-cli-manual.rst
parente39a7196e91cfeac1b93c00d22161ffd6f07434a (diff)
downloaddocs-ce6f02324134436a5ddb5875ca1259a66168e135.tar.gz
docs-ce6f02324134436a5ddb5875ca1259a66168e135.tar.bz2
docs-ce6f02324134436a5ddb5875ca1259a66168e135.zip
add wallet CLI manual
Diffstat (limited to 'taler-wallet-cli-manual.rst')
-rw-r--r--taler-wallet-cli-manual.rst136
1 files changed, 136 insertions, 0 deletions
diff --git a/taler-wallet-cli-manual.rst b/taler-wallet-cli-manual.rst
new file mode 100644
index 00000000..8007f6b0
--- /dev/null
+++ b/taler-wallet-cli-manual.rst
@@ -0,0 +1,136 @@
+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
+
+
+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