From f63f4cea078f26fd5a371762e7da960c1d6794a0 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Sun, 24 Jan 2021 14:12:00 +0100 Subject: reference developer manual correctly --- index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'index.rst') diff --git a/index.rst b/index.rst index 1a4d56c5..e6893db2 100644 --- a/index.rst +++ b/index.rst @@ -60,7 +60,7 @@ Documentation Overview taler-bank-manual taler-backoffice-manual taler-auditor-manual - developers-manual.rst + taler-developer-manual.rst design-documents/index anastasis libeufin/index -- cgit v1.2.3 From ce6f02324134436a5ddb5875ca1259a66168e135 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Sun, 24 Jan 2021 15:20:21 +0100 Subject: add wallet CLI manual --- index.rst | 3 +- taler-wallet-cli-manual.rst | 136 ++++++++++++++++++++++++++++++++++++++++++++ taler-wallet.rst | 4 +- 3 files changed, 140 insertions(+), 3 deletions(-) create mode 100644 taler-wallet-cli-manual.rst (limited to 'index.rst') diff --git a/index.rst b/index.rst index e6893db2..94862209 100644 --- a/index.rst +++ b/index.rst @@ -53,7 +53,7 @@ Documentation Overview core/index taler-exchange-manual taler-merchant-manual - taler-wallet + taler-wallet-cli-manual taler-nfc-guide.rst taler-merchant-api-tutorial taler-merchant-pos-terminal @@ -61,6 +61,7 @@ Documentation Overview taler-backoffice-manual taler-auditor-manual taler-developer-manual.rst + taler-wallet design-documents/index anastasis libeufin/index 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 diff --git a/taler-wallet.rst b/taler-wallet.rst index f5784a22..a87ee09c 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -1,5 +1,5 @@ -GNU Taler Wallet Manual -####################### +GNU Taler Wallet Developer Manual +################################# The GNU Taler wallet allows customers to withdraw and spend digital cash. -- cgit v1.2.3