24.119. taler-wallet-cli(1)

24.119.1. Name

taler-wallet-cli - command-line interface for the GNU Taler wallet

24.119.2. Synopsis

taler-wallet-cli [–wallet-db=FILE] [–wallet-connection=SOCKET] [–timetravel=MICROSECONDS] [-LLEVEL | –log=LEVEL] [–inhibit=OPERATIONS] [–non-interactive | –interactive] [–no-http] [-V | –verbose] COMMAND [OPTIONS]

24.119.3. Description

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).

24.119.3.1. Global options

-h | –help

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.

-LLEVEL | –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.

24.119.4. 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.

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.

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.

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.

transactions show TRANSACTION_ID [–include-contract-terms]

Show a single transaction. –include-contract-terms includes the payment contract terms in the response.

transactions abort TRANSACTION_ID

Abort a transaction.

transactions suspend TRANSACTION_ID

Suspend a transaction.

transactions resume TRANSACTION_ID

Resume a suspended transaction.

transactions retry TRANSACTION_ID

Retry a transaction.

transactions fail TRANSACTION_ID

Mark a transaction as failed when it cannot be aborted.

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.

24.119.5. 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.

24.119.6. 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.

24.119.7. 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.

24.119.8. See Also

taler-wallet-core API documentation and taler-wallet-cli --help.

24.119.9. Bugs

Report bugs by using https://bugs.taler.net or by sending electronic mail to <taler@gnu.org>.