taler-wallet-cli.1.rst (13251B)
1 taler-wallet-cli(1) 2 ################### 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **taler-wallet-cli** - command-line interface for the GNU Taler wallet 10 11 Synopsis 12 ======== 13 14 **taler-wallet-cli** 15 [**--wallet-db=**\ *FILE*] 16 [**--wallet-connection=**\ *SOCKET*] 17 [**--timetravel=**\ *MICROSECONDS*] 18 [**-L**\ *LEVEL* | **--log=**\ *LEVEL*] 19 [**--inhibit=**\ *OPERATIONS*] 20 [**--non-interactive** | **--interactive**] 21 [**--no-http**] 22 [**-V** | **--verbose**] 23 *COMMAND* [*OPTIONS*] 24 25 Description 26 =========== 27 28 **taler-wallet-cli** manages a GNU Taler wallet. Unless 29 **--wallet-connection** is used, it starts a local wallet-core instance for 30 the command and uses the SQLite wallet database at 31 ``~/.talerwalletdb.sqlite3`` by default. Commands that list balances, 32 transactions, exchanges, or bank accounts print JSON when standard output is 33 not a terminal and a human-readable view at a terminal. **--json** and 34 **--pretty** select either form explicitly where available. 35 36 An *AMOUNT* has the usual Taler form ``CURRENCY:VALUE``, for example 37 ``EUR:5.00``. A *TRANSACTION_ID* may be a complete transaction identifier, 38 a local reference of the form ``#TYPE:ID``, or ``^N`` for the N-th most recent 39 transaction (``^`` means ``^1``). 40 41 Global options 42 -------------- 43 44 **-h** | **--help** 45 Print help for the selected command. 46 47 **-v** | **--version** 48 Print the CLI version and exit. 49 50 **--wallet-db=**\ *FILE* 51 Use *FILE* as the local wallet database. 52 53 **--wallet-connection=**\ *SOCKET* 54 Connect to the wallet-core API served on the Unix-domain *SOCKET* instead 55 of starting a local wallet-core instance. 56 57 **--timetravel=**\ *MICROSECONDS* 58 Offset the system time seen by the wallet by *MICROSECONDS*. This is 59 intended for debugging and testing. 60 61 **-L**\ *LEVEL* | **--log=**\ *LEVEL* 62 Set the logging level, for example ``NONE`` through ``TRACE``. 63 64 **--inhibit=**\ *OPERATIONS* 65 Inhibit selected wallet operations. This is intended for debugging and 66 testing. 67 68 **--non-interactive** 69 Never prompt for input; fail with exit status 6 if input is required. This 70 is implied when standard input is not a terminal. 71 72 **--interactive** 73 Permit prompts even if the environment indicates that interaction should 74 be disabled. Standard input must still be a terminal. 75 76 **--no-http** 77 Require TLS and reject unsafe HTTP connections. 78 79 **-V** | **--verbose** 80 Enable verbose output. For list commands this enables the corresponding 81 detailed human-readable output. 82 83 Commands 84 ======== 85 86 **balance** [**--json** | **--pretty**] [**-v** | **--verbose**] [**--oneline**] 87 Show wallet balances. **--pretty** prints a human-readable balance even 88 when output is not a terminal; **--json** forces JSON. **--oneline** uses 89 one compact line for each balance. **--verbose** includes scope and 90 capability details. 91 92 **bank-accounts** [**--json** | **--pretty**] [**-v** | **--verbose**] [**--oneline**] 93 List known bank accounts. **--oneline** prints one compact line per 94 account and **--verbose** includes account IDs and diagnostic information. 95 96 **bank-accounts add** *PAYTO_URI* *LABEL* 97 Add a bank account. *PAYTO_URI* is its payto URI and *LABEL* is the name 98 that may be used by other commands. 99 100 **bank-accounts delete** *ACCOUNT_ID_OR_LABEL* 101 Delete a known bank account. The argument may be its identifier or label. 102 103 **bank-accounts list** 104 List known bank accounts. The formatting options of **bank-accounts** 105 apply. 106 107 **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**] 108 Perform the next action for a pending transaction. It confirms payment 109 offers, resumes suspended transactions, and reports external steps such as 110 KYC or bank confirmation. An external step exits with status 6. 111 **--yes** confirms without prompting and **--accept-tos** accepts an 112 exchange's terms of service. **--dry-run** only reports the required 113 action. The choice, exchange, amount, and age options supply answers when 114 the transaction needs them. **--wait** waits until the transaction is 115 final; **--timeout** accepts durations such as ``30s`` or ``5m``. 116 **--json** writes the outcome as JSON, while **--quiet** only sets the exit 117 status. 118 119 **deposit** *AMOUNT* *PAYTO_OR_LABEL* [**--check**] [**--no-wait**] [**--timeout=**\ *DURATION*] 120 Deposit *AMOUNT* to a payto URI or to the label of a known bank account. 121 **--check** obtains deposit information without creating a deposit. 122 Normally the command waits until the deposit is complete, finalizing, or 123 needs user action; **--no-wait** returns after creating it. 124 125 **exchanges** [**--json** | **--pretty**] [**-v** | **--verbose**] [**--oneline**] 126 List known exchanges. **--pretty** and **--json** choose the output 127 format, **--oneline** produces one compact line per exchange, and 128 **--verbose** includes diagnostic details. 129 130 **exchanges trusted** 131 List the trusted exchanges for global currencies. 132 133 **exchanges update** *URL* [**-f** | **--force**] 134 Add or update the exchange at base *URL*. **--force** forces an update. 135 136 **exchanges show** *URL* 137 Show detailed information about the exchange at base *URL*. 138 139 **exchanges add** *URL* 140 Add the exchange at base *URL*. 141 142 **exchanges delete** *URL* [**--purge**] 143 Delete the exchange at base *URL*. **--purge** also removes its stored 144 information. 145 146 **exchanges accept-tos** *URL* 147 Accept the terms of service of the exchange at base *URL*. 148 149 **exchanges tos** *URL* [**--content-type=**\ *TYPES*] 150 Retrieve the exchange's terms of service. *TYPES* is a comma-separated 151 list of acceptable content types. 152 153 **handle-uri** [*URI*] [**--withdrawal-exchange=**\ *URL*] [**--no-wait**] [**--choice-index=**\ *INDEX*] [**--restrict-age=**\ *AGE*] [**-y** | **--yes**] 154 Handle a ``taler://`` URI. If *URI* is omitted, it is read interactively. 155 **--withdrawal-exchange** selects the exchange for a withdrawal, 156 **--choice-index** chooses a payment offer, and **--restrict-age** requests 157 an age-restricted withdrawal. **--no-wait** returns without waiting for a 158 payment or refund transaction to settle. **--yes** accepts confirmation 159 prompts. 160 161 **peer-send** *AMOUNT* [**--summary=**\ *TEXT*] [**--purse-expiration=**\ *DURATION*] 162 Initiate a peer-push payment for *AMOUNT* and print the URI to send to the 163 recipient. The summary defaults to ``Payment`` and the purse expires one 164 hour after creation unless **--purse-expiration** is given. 165 166 **peer-request** *AMOUNT* [**--summary=**\ *TEXT*] [**--purse-expiration=**\ *DURATION*] 167 Initiate a peer-pull payment request for *AMOUNT* and print the URI to send 168 to the payer. The summary defaults to ``Invoice`` and the purse expires 169 after one hour unless overridden. 170 171 **transactions** [**--currency=**\ *CURRENCY*] [**--state=**\ *STATE*] [**--include-refreshes**] [**--json** | **--pretty**] [**-v** | **--verbose**] [**--oneline**] 172 List transactions. **--currency** restricts the list to one currency. 173 **--state** is one of ``final``, ``nonfinal``, ``done``, 174 ``nonfinal-approved``, or ``nonfinal-dialog``. **--include-refreshes** 175 includes refresh transactions. **--oneline** selects compact 176 human-readable output; **--verbose** includes identifiers, times, and 177 diagnostic details. 178 179 **transactions show** *TRANSACTION_ID* [**--include-contract-terms**] 180 Show a single transaction. **--include-contract-terms** includes the 181 payment contract terms in the response. 182 183 **transactions abort** *TRANSACTION_ID* 184 Abort a transaction. 185 186 **transactions suspend** *TRANSACTION_ID* 187 Suspend a transaction. 188 189 **transactions resume** *TRANSACTION_ID* 190 Resume a suspended transaction. 191 192 **transactions retry** *TRANSACTION_ID* 193 Retry a transaction. 194 195 **transactions fail** *TRANSACTION_ID* 196 Mark a transaction as failed when it cannot be aborted. 197 198 **transactions delete** *TRANSACTION_ID* 199 Permanently remove a transaction from the transaction list. 200 201 **transactions continue** *TRANSACTION_ID* [*OPTIONS*] 202 Equivalent to **continue-tx**. See **continue-tx** for its options. 203 204 **wait-tx** *TRANSACTION_ID* [**-s** | **--state=**\ *STATE*] [**--stid=**\ *ID*] [**-t** | **--timeout=**\ *DURATION*] [**--fail-on=**\ *MODE*] [**--log-id=**\ *ID*] [**--require-error**] [**--json**] [**--follow**] [**-q** | **--quiet**] 205 Wait for a transaction to reach a state. **transactions wait** has the 206 same syntax and behaviour. The default state is ``final``. A state is 207 ``MAJOR[:MINOR][/working|/idle]``; alternatives are comma-separated, and 208 ``*`` or ``any`` may stand for a major or minor state. A missing minor 209 state means any minor state; ``-`` requires no minor state. The 210 ``nonpending`` and ``final`` shorthands select state categories. 211 212 **--stid** waits for a wallet-internal state identifier and cannot be used 213 with **--state**. **--fail-on** is ``unsuccessful`` (the default), 214 ``error``, ``both``, or ``none``. It determines whether failed, aborted, 215 expired, or error states stop the wait early. **--require-error** only 216 accepts a matching state that has an error. **--follow** emits transaction 217 state transitions as JSON on standard error. With no timeout the command 218 waits indefinitely. 219 220 **transactions wait** *TRANSACTION_ID* [*OPTIONS*] 221 Equivalent to **wait-tx**. See **wait-tx** for its options. 222 223 **version** 224 Print version information from wallet-core. 225 226 **withdraw** [**--uri=**\ *TALER_WITHDRAW_URI*] [**--exchange=**\ *URL*] [**--amount=**\ *AMOUNT*] [**--check**] [**--forced-reserve-priv=**\ *KEY*] [**--restrict-age=**\ *AGE*] [**--wait**] [**--timeout=**\ *DURATION*] 227 Withdraw via a bank-integrated withdrawal URI or directly from an 228 exchange. With **--uri**, **--exchange** optionally overrides the 229 exchange suggested by the URI and **--amount** supplies an editable amount. 230 Without **--uri**, both **--exchange** and **--amount** are required; the 231 command prints the exchange transfer accounts needed to fund the reserve. 232 **--check** shows withdrawal details and fees without creating a 233 transaction. **--forced-reserve-priv** is only valid for direct exchange 234 withdrawals. **--wait** waits for the new transaction to become final. 235 236 Advanced commands 237 ================= 238 239 The following commands are intended for wallet administration, diagnostics, 240 or integration with wallet-core. 241 242 **advanced api** *OPERATION* *REQUEST* [**--expect-success**] 243 Call the wallet-core API operation *OPERATION* with a JSON *REQUEST*. 244 Prefix *REQUEST* with ``@`` to read the JSON from a file. API errors are 245 printed as JSON by default; **--expect-success** instead makes an API error 246 produce a non-zero exit status. 247 248 **advanced clear-database** 249 Irrevocably delete all data in the wallet database. 250 251 **advanced db-migrate** 252 Migrate the selected wallet database to the native schema. 253 254 **advanced db-migration-info** *DBFILE* 255 Print the schema type of *DBFILE*. 256 257 **advanced db-migration-rollback** *DBFILE* 258 Roll *DBFILE* back from an in-place native-schema migration. Wallet 259 changes made after migration are not retained by this rollback. 260 261 **advanced diagnostics** 262 Print wallet diagnostic information. 263 264 **advanced init** 265 Initialize the wallet database and exit. 266 267 **advanced pay-prepare** *URL* 268 Claim a merchant order at *URL* without paying it, and display the 269 resulting transaction state and payment choices. 270 271 **advanced pay-confirm** *TRANSACTION_ID* [**--session-id=**\ *ID*] 272 Confirm a payment proposed by a merchant. **--session-id** overrides the 273 merchant session identifier. 274 275 **advanced query-refund** *TRANSACTION_ID* 276 Query refunds for a payment transaction. 277 278 **advanced performance-stats** [**--limit=**\ *N*] 279 Print performance statistics. **--limit** restricts every result table to 280 *N* entries. 281 282 **advanced reset-all-retries** 283 Reset all wallet retry counters. 284 285 **advanced serve** [**--unix-path=**\ *SOCKET*] [**--no-init**] 286 Serve the wallet-core API over a Unix-domain socket. The default socket is 287 ``~/.wallet-core.sock``. **--no-init** leaves initialization to the API 288 client. 289 290 **advanced tasks** 291 Print active wallet-core tasks. 292 293 Exit status 294 =========== 295 296 The command returns 0 on success. In particular, **wait-tx** returns 0 when 297 the requested state matches. A usage error returns 2, an unexpected wallet 298 exception 4, an API error 5, and input required in non-interactive operation 299 6. A timed-out wait returns 7 and a transaction that did not succeed returns 300 8. 301 302 Environment 303 =========== 304 305 **TALER_WALLET_CONNECTION** 306 Unix-domain wallet-core socket to use when **--wallet-connection** is not 307 supplied. 308 309 **TALER_WALLET_OFFLINE=1** 310 Prevent network requests made by a locally started wallet-core instance. 311 This cannot be used together with a remote wallet connection. 312 313 See Also 314 ======== 315 316 ``taler-wallet-core`` API documentation and ``taler-wallet-cli --help``. 317 318 Bugs 319 ==== 320 321 Report bugs by using https://bugs.taler.net or by sending electronic mail to 322 <taler@gnu.org>.