commit ddbf8a397bfc21b62d4e150a99e3dcdaf6f85c6e
parent 73b137f4c87dd0fb71ee3bb273210fe6ad7b66f9
Author: Florian Dold <dold@taler.net>
Date: Mon, 10 Aug 2026 01:20:13 +0200
docs: update wallet CLI manpage
Diffstat:
1 file changed, 289 insertions(+), 30 deletions(-)
diff --git a/manpages/taler-wallet-cli.1.rst b/manpages/taler-wallet-cli.1.rst
@@ -6,58 +6,317 @@ taler-wallet-cli(1)
Name
====
- **taler-wallet-cli** - interact with taler-wallet
+ **taler-wallet-cli** - command-line interface for the GNU Taler wallet
Synopsis
========
-**taler-auditor**
-[**-h** | **--help**]
-[**-V** | **--version**]
-[**--verbose**]
-<command> [<args>]
-
+**taler-wallet-cli**
+[**--wallet-db=**\ *FILE*]
+[**--wallet-connection=**\ *SOCKET*]
+[**--timetravel=**\ *MICROSECONDS*]
+[**-L**\ *LEVEL* | **--log=**\ *LEVEL*]
+[**--inhibit=**\ *OPERATIONS*]
+[**--non-interactive** | **--interactive**]
+[**--no-http**]
+[**-V** | **--verbose**]
+*COMMAND* [*OPTIONS*]
Description
===========
-**taler-wallet-cli** is a command-line tool to be used by developers
-for testing.
+**taler-wallet-cli** manages a GNU Taler wallet. Unless
+**--wallet-connection** is used, it starts a local wallet-core instance for
+the command and uses the SQLite wallet database at
+``~/.talerwalletdb.sqlite3`` by default. Commands that list balances,
+transactions, exchanges, or bank accounts print JSON when standard output is
+not a terminal and a human-readable view at a terminal. **--json** and
+**--pretty** select either form explicitly where available.
+
+An *AMOUNT* has the usual Taler form ``CURRENCY:VALUE``, for example
+``EUR:5.00``. A *TRANSACTION_ID* may be a complete transaction identifier,
+a local reference of the form ``#TYPE:ID``, or ``^N`` for the N-th most recent
+transaction (``^`` means ``^1``).
+
+Global options
+--------------
**-h** | **--help**
- Print short help on options.
+ Print help for the selected command.
+
+**-v** | **--version**
+ Print the CLI version and exit.
+
+**--wallet-db=**\ *FILE*
+ Use *FILE* as the local wallet database.
+
+**--wallet-connection=**\ *SOCKET*
+ Connect to the wallet-core API served on the Unix-domain *SOCKET* instead
+ of starting a local wallet-core instance.
+
+**--timetravel=**\ *MICROSECONDS*
+ Offset the system time seen by the wallet by *MICROSECONDS*. This is
+ intended for debugging and testing.
+
+**-L**\ *LEVEL* | **--log=**\ *LEVEL*
+ Set the logging level, for example ``NONE`` through ``TRACE``.
+
+**--inhibit=**\ *OPERATIONS*
+ Inhibit selected wallet operations. This is intended for debugging and
+ testing.
+
+**--non-interactive**
+ Never prompt for input; fail with exit status 6 if input is required. This
+ is implied when standard input is not a terminal.
+
+**--interactive**
+ Permit prompts even if the environment indicates that interaction should
+ be disabled. Standard input must still be a terminal.
+
+**--no-http**
+ Require TLS and reject unsafe HTTP connections.
+
+**-V** | **--verbose**
+ Enable verbose output. For list commands this enables the corresponding
+ detailed human-readable output.
+
+Commands
+========
+
+**balance** [**--json** | **--pretty**] [**-v** | **--verbose**] [**--oneline**]
+ Show wallet balances. **--pretty** prints a human-readable balance even
+ when output is not a terminal; **--json** forces JSON. **--oneline** uses
+ one compact line for each balance. **--verbose** includes scope and
+ capability details.
+
+**bank-accounts** [**--json** | **--pretty**] [**-v** | **--verbose**] [**--oneline**]
+ List known bank accounts. **--oneline** prints one compact line per
+ account and **--verbose** includes account IDs and diagnostic information.
+
+**bank-accounts add** *PAYTO_URI* *LABEL*
+ Add a bank account. *PAYTO_URI* is its payto URI and *LABEL* is the name
+ that may be used by other commands.
+
+**bank-accounts delete** *ACCOUNT_ID_OR_LABEL*
+ Delete a known bank account. The argument may be its identifier or label.
+
+**bank-accounts list**
+ List known bank accounts. The formatting options of **bank-accounts**
+ apply.
+
+**continue-tx** *TRANSACTION_ID* [**-y** | **--yes**] [**--accept-tos**] [**-n** | **--dry-run**] [**--choice-index=**\ *INDEX*] [**--exchange=**\ *URL*] [**--amount=**\ *AMOUNT*] [**--restrict-age=**\ *AGE*] [**--wait**] [**-t** | **--timeout=**\ *DURATION*] [**--json**] [**-q** | **--quiet**]
+ Perform the next action for a pending transaction. It confirms payment
+ offers, resumes suspended transactions, and reports external steps such as
+ KYC or bank confirmation. An external step exits with status 6.
+ **--yes** confirms without prompting and **--accept-tos** accepts an
+ exchange's terms of service. **--dry-run** only reports the required
+ action. The choice, exchange, amount, and age options supply answers when
+ the transaction needs them. **--wait** waits until the transaction is
+ final; **--timeout** accepts durations such as ``30s`` or ``5m``.
+ **--json** writes the outcome as JSON, while **--quiet** only sets the exit
+ status.
+
+**deposit** *AMOUNT* *PAYTO_OR_LABEL* [**--check**] [**--no-wait**] [**--timeout=**\ *DURATION*]
+ Deposit *AMOUNT* to a payto URI or to the label of a known bank account.
+ **--check** obtains deposit information without creating a deposit.
+ Normally the command waits until the deposit is complete, finalizing, or
+ needs user action; **--no-wait** returns after creating it.
+
+**exchanges** [**--json** | **--pretty**] [**-v** | **--verbose**] [**--oneline**]
+ List known exchanges. **--pretty** and **--json** choose the output
+ format, **--oneline** produces one compact line per exchange, and
+ **--verbose** includes diagnostic details.
+
+**exchanges trusted**
+ List the trusted exchanges for global currencies.
+
+**exchanges update** *URL* [**-f** | **--force**]
+ Add or update the exchange at base *URL*. **--force** forces an update.
+
+**exchanges show** *URL*
+ Show detailed information about the exchange at base *URL*.
+
+**exchanges add** *URL*
+ Add the exchange at base *URL*.
+
+**exchanges delete** *URL* [**--purge**]
+ Delete the exchange at base *URL*. **--purge** also removes its stored
+ information.
+
+**exchanges accept-tos** *URL*
+ Accept the terms of service of the exchange at base *URL*.
+
+**exchanges tos** *URL* [**--content-type=**\ *TYPES*]
+ Retrieve the exchange's terms of service. *TYPES* is a comma-separated
+ list of acceptable content types.
+
+**handle-uri** [*URI*] [**--withdrawal-exchange=**\ *URL*] [**--no-wait**] [**--choice-index=**\ *INDEX*] [**--restrict-age=**\ *AGE*] [**-y** | **--yes**]
+ Handle a ``taler://`` URI. If *URI* is omitted, it is read interactively.
+ **--withdrawal-exchange** selects the exchange for a withdrawal,
+ **--choice-index** chooses a payment offer, and **--restrict-age** requests
+ an age-restricted withdrawal. **--no-wait** returns without waiting for a
+ payment or refund transaction to settle. **--yes** accepts confirmation
+ prompts.
-**-V** | **--version**
- Output the version number.
+**peer-send** *AMOUNT* [**--summary=**\ *TEXT*] [**--purse-expiration=**\ *DURATION*]
+ Initiate a peer-push payment for *AMOUNT* and print the URI to send to the
+ recipient. The summary defaults to ``Payment`` and the purse expires one
+ hour after creation unless **--purse-expiration** is given.
-**--verbose**
- Enable verbose output.
+**peer-request** *AMOUNT* [**--summary=**\ *TEXT*] [**--purse-expiration=**\ *DURATION*]
+ Initiate a peer-pull payment request for *AMOUNT* and print the URI to send
+ to the payer. The summary defaults to ``Invoice`` and the purse expires
+ after one hour unless overridden.
-**test-withdraw** [**-e** URL | **--exchange** URL] [**-a** AMOUNT | **--amount** AMOUNT][**-b** URL | **--bank** URL]
- withdraw test currency from the test bank
+**transactions** [**--currency=**\ *CURRENCY*] [**--state=**\ *STATE*] [**--include-refreshes**] [**--json** | **--pretty**] [**-v** | **--verbose**] [**--oneline**]
+ List transactions. **--currency** restricts the list to one currency.
+ **--state** is one of ``final``, ``nonfinal``, ``done``,
+ ``nonfinal-approved``, or ``nonfinal-dialog``. **--include-refreshes**
+ includes refresh transactions. **--oneline** selects compact
+ human-readable output; **--verbose** includes identifiers, times, and
+ diagnostic details.
-**balance**
- show wallet balance
+**transactions show** *TRANSACTION_ID* [**--include-contract-terms**]
+ Show a single transaction. **--include-contract-terms** includes the
+ payment contract terms in the response.
-**history**
- show wallet history
+**transactions abort** *TRANSACTION_ID*
+ Abort a transaction.
-**test-merchant-qrcode** [**-a** AMOUNT | **--amount** AMOUNT][**-s** SUMMARY | **--summary** SUMMARY]
+**transactions suspend** *TRANSACTION_ID*
+ Suspend a transaction.
-**withdraw-uri** URI
+**transactions resume** *TRANSACTION_ID*
+ Resume a suspended transaction.
-**refund-uri** URI
+**transactions retry** *TRANSACTION_ID*
+ Retry a transaction.
-**pay-uri** [**-y** | **--yes**] URI
+**transactions fail** *TRANSACTION_ID*
+ Mark a transaction as failed when it cannot be aborted.
-**integrationtest** [**-e** URL | **--exchange** URL][**-m** URL | **--merchant** URL][**-k** APIKEY | **--merchant-api-key** APIKEY][**-b** URL | **--bank** URL][**-w** AMOUNT | **--withdraw-amount** AMOUNT][**-s** AMOUNT | **--spend-amount** AMOUNT]
- Run integration test with bank, exchange and merchant.
+**transactions delete** *TRANSACTION_ID*
+ Permanently remove a transaction from the transaction list.
+
+**transactions continue** *TRANSACTION_ID* [*OPTIONS*]
+ Equivalent to **continue-tx**. See **continue-tx** for its options.
+
+**wait-tx** *TRANSACTION_ID* [**-s** | **--state=**\ *STATE*] [**--stid=**\ *ID*] [**-t** | **--timeout=**\ *DURATION*] [**--fail-on=**\ *MODE*] [**--log-id=**\ *ID*] [**--require-error**] [**--json**] [**--follow**] [**-q** | **--quiet**]
+ Wait for a transaction to reach a state. **transactions wait** has the
+ same syntax and behaviour. The default state is ``final``. A state is
+ ``MAJOR[:MINOR][/working|/idle]``; alternatives are comma-separated, and
+ ``*`` or ``any`` may stand for a major or minor state. A missing minor
+ state means any minor state; ``-`` requires no minor state. The
+ ``nonpending`` and ``final`` shorthands select state categories.
+
+ **--stid** waits for a wallet-internal state identifier and cannot be used
+ with **--state**. **--fail-on** is ``unsuccessful`` (the default),
+ ``error``, ``both``, or ``none``. It determines whether failed, aborted,
+ expired, or error states stop the wait early. **--require-error** only
+ accepts a matching state that has an error. **--follow** emits transaction
+ state transitions as JSON on standard error. With no timeout the command
+ waits indefinitely.
+
+**transactions wait** *TRANSACTION_ID* [*OPTIONS*]
+ Equivalent to **wait-tx**. See **wait-tx** for its options.
+
+**version**
+ Print version information from wallet-core.
+
+**withdraw** [**--uri=**\ *TALER_WITHDRAW_URI*] [**--exchange=**\ *URL*] [**--amount=**\ *AMOUNT*] [**--check**] [**--forced-reserve-priv=**\ *KEY*] [**--restrict-age=**\ *AGE*] [**--wait**] [**--timeout=**\ *DURATION*]
+ Withdraw via a bank-integrated withdrawal URI or directly from an
+ exchange. With **--uri**, **--exchange** optionally overrides the
+ exchange suggested by the URI and **--amount** supplies an editable amount.
+ Without **--uri**, both **--exchange** and **--amount** are required; the
+ command prints the exchange transfer accounts needed to fund the reserve.
+ **--check** shows withdrawal details and fees without creating a
+ transaction. **--forced-reserve-priv** is only valid for direct exchange
+ withdrawals. **--wait** waits for the new transaction to become final.
+
+Advanced commands
+=================
+
+The following commands are intended for wallet administration, diagnostics,
+or integration with wallet-core.
+
+**advanced api** *OPERATION* *REQUEST* [**--expect-success**]
+ Call the wallet-core API operation *OPERATION* with a JSON *REQUEST*.
+ Prefix *REQUEST* with ``@`` to read the JSON from a file. API errors are
+ printed as JSON by default; **--expect-success** instead makes an API error
+ produce a non-zero exit status.
+
+**advanced clear-database**
+ Irrevocably delete all data in the wallet database.
+
+**advanced db-migrate**
+ Migrate the selected wallet database to the native schema.
+
+**advanced db-migration-info** *DBFILE*
+ Print the schema type of *DBFILE*.
+
+**advanced db-migration-rollback** *DBFILE*
+ Roll *DBFILE* back from an in-place native-schema migration. Wallet
+ changes made after migration are not retained by this rollback.
+
+**advanced diagnostics**
+ Print wallet diagnostic information.
+
+**advanced init**
+ Initialize the wallet database and exit.
+
+**advanced pay-prepare** *URL*
+ Claim a merchant order at *URL* without paying it, and display the
+ resulting transaction state and payment choices.
+
+**advanced pay-confirm** *TRANSACTION_ID* [**--session-id=**\ *ID*]
+ Confirm a payment proposed by a merchant. **--session-id** overrides the
+ merchant session identifier.
+
+**advanced query-refund** *TRANSACTION_ID*
+ Query refunds for a payment transaction.
+
+**advanced performance-stats** [**--limit=**\ *N*]
+ Print performance statistics. **--limit** restricts every result table to
+ *N* entries.
+
+**advanced reset-all-retries**
+ Reset all wallet retry counters.
+
+**advanced serve** [**--unix-path=**\ *SOCKET*] [**--no-init**]
+ Serve the wallet-core API over a Unix-domain socket. The default socket is
+ ``~/.wallet-core.sock``. **--no-init** leaves initialization to the API
+ client.
+
+**advanced tasks**
+ Print active wallet-core tasks.
+
+Exit status
+===========
+
+The command returns 0 on success. In particular, **wait-tx** returns 0 when
+the requested state matches. A usage error returns 2, an unexpected wallet
+exception 4, an API error 5, and input required in non-interactive operation
+6. A timed-out wait returns 7 and a transaction that did not succeed returns
+8.
+
+Environment
+===========
+
+**TALER_WALLET_CONNECTION**
+ Unix-domain wallet-core socket to use when **--wallet-connection** is not
+ supplied.
+
+**TALER_WALLET_OFFLINE=1**
+ Prevent network requests made by a locally started wallet-core instance.
+ This cannot be used together with a remote wallet connection.
+
+See Also
+========
-.. See Also
- ========
+``taler-wallet-core`` API documentation and ``taler-wallet-cli --help``.
Bugs
====
-Report bugs by using https://bugs.taler.net or by sending electronic
-mail to <taler@gnu.org>.
+Report bugs by using https://bugs.taler.net or by sending electronic mail to
+<taler@gnu.org>.
