libeufin-cli(1) ############### .. only:: html Name ==== **libeufin-cli** - Interact with LibEuFin Sandbox and Nexus Synopsis ======== **libeufin-cli** [**-h** | **--help**] [**--version**] COMMAND [ARGS...] Commands: accounts, connections, facades, permissions, sandbox, users Description =========== **libeufin-cli** is the user interface program to interact with **libeufin-sandbox** and **libeufin-nexus** when they are operating as HTTP servers, listening on localhost ports. Normally, you invoke them with their respective ``serve`` commands, and in a separate shell, use **libeufin-cli** to send requests and receive responses from them. The interaction model is as follows: - (Optionally) Start the sandbox. - Start the nexus. - Use **libeufin-cli** to interact with them. You can manage users and permissions, bank accounts, "facades", transactions, and connections between the various systems. For **libeufin-cli** to be able to communicate with **libeufin-sandbox**, the following environment variables need to be set: ``LIBEUFIN_SANDBOX_USERNAME`` This should normally be ``admin``. ``LIBEUFIN_SANDBOX_PASSWORD`` This is the same password chosen when the sandbox was started. ``LIBEUFIN_SANDBOX_URL`` This is ``http://localhost:PORT/``, where ``PORT`` is the same port chosen when the sandbox was started. This URL can also be specified with the ``--sandbox-url URL`` option to the ``sandbox`` command (see below). If both are given, the ``--sandbox-url`` option takes precedence. For **libeufin-cli** to be able to communicate with **libeufin-nexus**, the following environment variables need to be set: ``LIBEUFIN_NEXUS_USERNAME`` For some operations (such as ``users create``), this must be the same username chosen by the ``libeufin-nexus superuser`` command. ``LIBEUFIN_NEXUS_PASSWORD`` This is the password associated with the username. ``LIBEUFIN_NEXUS_URL`` This is ``http://localhost:PORT/``, where ``PORT`` is the same port chosen when the nexus was started. Of the six commands, the ``sandbox`` command talks to the sandbox, while the other five commands talk to the nexus. The following sections describe each command and their subcommands in detail. sandbox ------- The ``libeufin-cli sandbox`` command is for managing the sandbox process started by ``libeufin-sandbox serve``. It takes one option, ``--sandbox-url URL``, to be specified before the subcommands and their arguments. This URL can also be specified with the ``LIBEUFIN_SANDBOX_URL`` environment variable (see above). If both are given, the ``--sandbox-url`` option takes precedence. The following subcommands are available: bankaccount, check, demobank, ebicsbankaccount, ebicshost, ebicssubscriber. The first command to use is ``check``, followed by ``ebicshost``, ``ebicssubscriber``, and ``ebicsbankaccount``, to configure the basic system. You can then use the ``bankaccount`` command to generate (simulated) transaction traffic. After that, the ``demobank`` command and its subcommands provide the same access to the API that Nexus itself uses. You normally do not need to use those commands directly. sandbox check ------------- The ``check`` command attempts a simple aliveness check by contacting the sandbox and displaying its returned message. If all goes well, you should see something like: .. code-block:: console $ libeufin-cli sandbox check Hello, this is the Sandbox sandbox ebicshost ----------------- The ``ebicshost`` command manages EBICS hosts. It has two subcommands: create and list. sandbox ebicshost create ^^^^^^^^^^^^^^^^^^^^^^^^ The ``ebicshost create`` command creates a EBICS host. It takes one option, ``--host-id ID``, where ``ID`` is used to identify that host for all future commands. sandbox ebicshost list ^^^^^^^^^^^^^^^^^^^^^^ The ``ebicshost list`` command lists the hosts in the system. For example: .. code-block:: console $ libeufin-cli sandbox ebicshost create --host-id testhost $ libeufin-cli sandbox ebicshost list { "ebicsHosts" : [ "testhost" ] } Here, the ``ID`` is ``testhost``. sandbox ebicssubscriber ----------------------- The ``ebicssubscriber`` command manages EBICS subscribers. It has two subcommands: create and list. sandbox ebicssubscriber create ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ NB: This command is deprecated and will be removed at some point. See ``sandbox demobank new-ebicssubscriber`` (below) for its replacement. The ``ebicssubscriber create`` command creates a EBICS subscriber. It takes three options, all of which are required: :: --host-id TEXT Ebics host ID --partner-id TEXT Ebics partner ID --user-id TEXT Ebics user ID The host ID should be the same one specified in ``ebicshost create`` (see above). For example: .. code-block:: console $ libeufin-cli sandbox ebicssubscriber create \ --host-id testhost \ --partner-id partner01 \ --user-id user01 Note that ``testhost`` is the same as in the ``ebicshost create`` example (see above). sandbox ebicssubscriber list ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``ebicssubscriber list`` command lists the EBICS subscribers in the system. For example: .. code-block:: console $ libeufin-cli sandbox ebicssubscriber list { "subscribers" : [ { "hostID" : "testhost", "partnerID" : "partner01", "userID" : "user01", "systemID" : null, "demobankAccountLabel" : "not associated yet" } ] } Note that the output reflects the subscriber created in the ``ebicssubscriber create`` example (see above). sandbox ebicsbankaccount ------------------------ The ``ebicsbankaccount`` command manages EBICS bank accounts. It has one subcommand: create. (To list accounts, see ``sandbox bankaccount`` below.) sandbox ebicsbankaccount ^^^^^^^^^^^^^^^^^^^^^^^^ The ``ebicsbankaccount create`` command takes several options, all required: :: --iban TEXT IBAN --bic TEXT BIC --person-name TEXT bank account owner name --account-name TEXT label of this bank account --ebics-user-id TEXT user ID of the Ebics subscriber --ebics-host-id TEXT host ID of the Ebics subscriber --ebics-partner-id TEXT partner ID of the Ebics subscriber At this time, although the ``--person-name`` option is required, the sandbox does not remember the option value. (When queried, it displays "Bank account owner's name" instead. See ``sandbox bankaccount`` below.) For the sandbox, the important value is the ``--account-name`` option. For example: .. code-block:: console $ libeufin-cli sandbox ebicsbankaccount create \ --iban DE18500105172929531888 \ --bic INGDDEFFXXX \ --person-name "Jane Normal" \ --account-name testacct01 \ --ebics-host-id testhost \ --ebics-user-id user01 \ --ebics-partner-id partner01 Note that ``testhost`` is the same as in the ``ebicshost create`` example, and that ``user01`` and ``partner01`` are the same as in the ``ebicssubscriber create`` example (see above). sandbox bankaccount ------------------- The ``bankaccount`` command manages bank accounts. It has several subcommands: list, generate-transactions, simulate-incoming-transaction, transactions. sandbox bankaccount list ^^^^^^^^^^^^^^^^^^^^^^^^ The ``bankaccount list`` command lists the bank accounts in the system. For example: .. code-block:: console $ libeufin-cli sandbox bankaccount list [ { "label" : "bank", "name" : "Bank account owner's name", "iban" : "DE370758", "bic" : "SANDBOXX" }, { "label" : "testacct01", "name" : "Bank account owner's name", "iban" : "DE18500105172929531888", "bic" : "INGDDEFFXXX" } ] Note that ``testacct01``, ``DE18500105172929531888``, and ``INGDDEFFXXX`` are the same as specified in the ``ebicsbankaccount create`` example (see above). sandbox bankaccount generate-transactions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The remaining ``bankaccount`` commands deal with transactions to and from the bank accounts. The ``bankaccount generate-transactions`` command generates test transactions. It takes one arg, the account label. For example: .. code-block:: console $ libeufin-cli sandbox bankaccount generate-transactions testacct01 Note that ``testacct01`` is the account label shown in the ``bankaccount list`` example (see above). sandbox bankaccount simulate-incoming-transaction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``bankaccount simulate-incoming-transaction`` books an incoming payment in the sandbox. It takes one arg, the account label, and several options. :: --debtor-iban TEXT IBAN sending the payment --debtor-bic TEXT BIC sending the payment --debtor-name TEXT name of the person who is sending the payment --amount TEXT amount, no currency --subject TEXT payment subject For example: .. code-block:: console $ libeufin-cli sandbox bankaccount simulate-incoming-transaction testacct01 \ --debtor-iban DE06500105174526623718 \ --debtor-bic INGDDEFFXXX \ --debtor-name "Joe Foo" \ --subject "Hello World" \ --amount 10.50 Note that ``testacct01`` is the same as in previous examples (see above), and that ``10.50`` is in ``X.Y`` format. sandbox bankaccount transactions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``bankaccount transactions`` command lists transactions. It takes one arg, the account label. For example: .. code-block:: console $ libeufin-cli sandbox bankaccount transactions testacct01 { "payments" : [ { "accountLabel" : "testacct01", "creditorIban" : "DE18500105172929531888", "creditorBic" : "INGDDEFFXXX", "creditorName" : "Creditor Name", "debtorIban" : "DE64500105178797276788", "debtorBic" : "DEUTDEBB101", "debtorName" : "Max Mustermann", "amount" : "5", "currency" : "EUR", "subject" : "sample transaction DILWBJHL", "date" : "Wed, 26 Jan 2022 09:03:44 GMT", "creditDebitIndicator" : "credit", "accountServicerReference" : "DILWBJHL", "paymentInformationId" : null }, { "accountLabel" : "testacct01", "creditorIban" : "DE64500105178797276788", "creditorBic" : "DEUTDEBB101", "creditorName" : "Max Mustermann", "debtorIban" : "DE18500105172929531888", "debtorBic" : "INGDDEFFXXX", "debtorName" : "Debitor Name", "amount" : "12", "currency" : "EUR", "subject" : "sample transaction N7JSY17B", "date" : "Wed, 26 Jan 2022 09:03:44 GMT", "creditDebitIndicator" : "debit", "accountServicerReference" : "N7JSY17B", "paymentInformationId" : null }, { "accountLabel" : "testacct01", "creditorIban" : "DE18500105172929531888", "creditorBic" : "INGDDEFFXXX", "creditorName" : "Creditor Name", "debtorIban" : "DE06500105174526623718", "debtorBic" : "INGDDEFFXXX", "debtorName" : "Joe Foo", "amount" : "10.50", "currency" : "EUR", "subject" : "Hello World", "date" : "Wed, 26 Jan 2022 09:04:31 GMT", "creditDebitIndicator" : "credit", "accountServicerReference" : "sandbox-6UI2J3636J9EESXO", "paymentInformationId" : null } ] } Note that ``testacct01`` is the same as in previous examples (see above), and that the generated transactions from previous examples are listed, as well. sandbox demobank ---------------- The ``demobank`` command provides an interface to the Access API, which includes three commands: register, info, new-transaction. There is also a fourth ``demobank`` command, new-ebicssubscriber, that does not use the Access API. For all ``demobank`` commands, the sandbox URL *must* specify which *one* bank the command applies to in the base URL. Note that this URL cannot be used with other sandbox commands. In other words: ``--sandbox-url http://localhost:5016/demobanks/default`` This base URL can be used for commands: - sandbox demobank register - sandbox demobank info - sandbox demobank new-ebicssubscriber - sandbox demobank new-transaction It specifies the ``default`` demobank. ``--sandbox-url http://localhost:5016`` This base URL can be used for all other sandbox commands. In the following examples, the base URL will be explicitly shown with the ``--sandbox-url`` option for the ``demobank`` commands. sandbox demobank register ^^^^^^^^^^^^^^^^^^^^^^^^^ The ``demobank register`` command registers a new bank account. Note that the username will be both the username to login at the bank and the bank account label. It takes the username and password from the ``LIBEUFIN_SANDBOX_USERNAME`` and ``LIBEUFIN_SANDBOX_PASSWORD`` environment variables. The username *need not be* ``admin``. For example: .. code-block:: console $ export LIBEUFIN_SANDBOX_USERNAME=jrluser $ export LIBEUFIN_SANDBOX_PASSWORD=easy $ libeufin-cli sandbox \ --sandbox-url http://localhost:5016/demobanks/default \ demobank register sandbox demobank info ^^^^^^^^^^^^^^^^^^^^^ The ``demobank info`` command returns basic information on a bank account. It takes option ``--bank-account NAME``. For example: .. code-block:: console $ libeufin-cli sandbox \ --sandbox-url http://localhost:5016/demobanks/default \ demobank info --bank-account jrluser { "balance" : { "amount" : "EUR:100", "credit_debit_indicator" : "credit" }, "paytoUri" : "payto://iban/SANDBOXX/DE948559?receiver-name=admin" } Note that ``jrluser`` is the same username / bank account name as in the ``register`` example (see above). sandbox demobank new-ebicssubscriber ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``demobank new-ebicssubscriber`` command associates a new Ebics subscriber to an existing bank account. It takes several options, all required: :: --host-id TEXT Ebics host ID --partner-id TEXT Ebics partner ID --user-id TEXT Ebics user ID --bank-account TEXT Label of the bank account to associate with this Ebics subscriber For example: .. code-block: console $ libeufin-cli sandbox \ --sandbox-url http://localhost:5016/demobanks/default \ demobank new-ebicssubscriber \ --host-id testhost \ --partner-id partner01 \ --user-id user02 \ --bank-account jrluser Note that ``testhost`` is the same as in the ``ebicshost create`` example, and that ``partner01`` is the same as in the ``ebicssubscriber create`` example (see above). The ``user02`` is new. The ``--bank-account jrluser`` is the same as in the ``info`` example (see above). You can see the effect of the ``new-ebicssubscriber`` command with the ``bankaccount list`` command. sandbox demobank new-transaction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``demobank new-transaction`` command initiates a new transaction. It takes several options, all required: :: --bank-account TEXT Label of the bank account to be debited for the transaction --payto-with-subject TEXT Payto address including the subject as a query parameter --amount CUR:X.Y Amount to transfer For example: .. code-block:: console $ libeufin-cli sandbox \ --sandbox-url http://localhost:5016/demobanks/default \ demobank new-transaction \ --bank-account jrluser \ --payto-with-subject 'payto://FIXME/?message=1kg+coffee' \ --amount EUR:10.50 FIXME: Any output? Note that ``--bank-account jrluser`` is the same as in the ``info`` and ``new-ebicssubscriber`` command examples (see above). connections ----------- WRITEME connections download-bank-accounts ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ WRITEME connections delete-connection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ WRITEME connections connect ^^^^^^^^^^^^^^^^^^^ WRITEME connections export-backup ^^^^^^^^^^^^^^^^^^^^^^^^^ WRITEME connections get-key-letter ^^^^^^^^^^^^^^^^^^^^^^^^^^ WRITEME connections import-bank-account ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ WRITEME connections list-connections ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ WRITEME connections list-offered-bank-accounts ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ WRITEME connections new-ebics-connection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ WRITEME connections restore-backup ^^^^^^^^^^^^^^^^^^^^^^^^^^ WRITEME connections show-connection ^^^^^^^^^^^^^^^^^^^^^^^^^^^ WRITEME users ----- The ``libeufin-cli users`` command manages users authorized to operate Nexus. It has several subcommands: self, list, create, change-password. The ``create`` and ``change-password`` commands can only be issued by the superuser (as configured by the ``libeufin-nexus superuser`` command), while the ``self`` and ``list`` commands can be issued by any user. In the following ``users`` examples, we assume that previously the command ``libeufin-nexus superuser foo`` was issued, and that the current username and password are for that user (via environment variables ``LIBEUFIN_NEXUS_USERNAME`` and ``LIBEUFIN_NEXUS_PASSWORD``, see above). users self ^^^^^^^^^^ The ``users self`` command displays information for the current user. For example: .. code-block:: console $ libeufin-cli users self { "username" : "foo", "superuser" : true } users list ^^^^^^^^^^ The ``users list`` command displays information for all the users authorized to operate Nexus. For example: .. code-block:: console $ libeufin-cli users list { "users" : [ { "username" : "foo", "superuser" : true } ] } In this example, there is only one user, the superuser ``foo``. users create ^^^^^^^^^^^^ The ``users create`` command creates a normal (non-superuser) user. It takes one argument, the ``USERNAME`` and one option, ``--password TEXT``. If you omit the option, **libeufin-cli** will prompt you for the password. For example: .. code-block:: console $ libeufin-cli users create --password easy jrluser { "message" : "New user 'jrluser' registered" } $ libeufin-cli users list { "users" : [ { "username" : "foo", "superuser" : true }, { "username" : "jrluser", "superuser" : false } ] } In this example, we create the same user as for the sandbox examples (see above). Note that the system now includes two users. users change-password ^^^^^^^^^^^^^^^^^^^^^ The ``users change-password`` command changes the password for a user. It takes one argument, the ``USERNAME`` and one option, ``--new-password TEXT``. If you omit the option, **libeufin-cli** will prompt you for the password. For example: .. code-block:: console $ libeufin-cli users change-password --new-password hard jrluser { "message" : "Password successfully changed" } permissions ----------- The ``libeufin-cli permissions`` command manages permissions for operations on Nexus. It has three subcommands: list, grant, revoke. All three commands can only be issued by the superuser. permissions list ^^^^^^^^^^^^^^^^ The ``permissions list`` command lists the granted permissions. At the beginning of a session, there are none: .. code-block:: console $ libeufin-cli permissions list { "permissions" : [ ] } permissions grant ^^^^^^^^^^^^^^^^^ The ``permissions grant`` command adds a permission to the list of granted permissions. It takes five arguments: ``SUBJECT_TYPE``, ``SUBJECT_ID``, ``RESOURCE_TYPE``, ``RESOURCE_ID``, ``PERMISSION_NAME``. FIXME: The subject type and id, resource type and id, are ... The ``PERMISSION_NAME`` is one of the following: - ``facade.talerwiregateway.history`` - ``facade.talerwiregateway.transfer`` - ``facade.anastasis.history`` For example: .. code-block:: console $ libeufin-cli permissions grant \ some-subject-type some-subject-id \ some-resource-type some-resource-id \ facade.anastasis.history { } $ libeufin-cli permissions list { "permissions" : [ { "subjectType" : "some-subject-type", "subjectId" : "some-subject-id", "resourceType" : "some-resource-type", "resourceId" : "some-resource-id", "permissionName" : "facade.anastasis.history" } ] } permissions revoke ^^^^^^^^^^^^^^^^^^ The ``permissions revoke`` command does the opposite of the ``permissions grant`` command. It takes the same arguments as the ``permissions grant`` command: ``SUBJECT_TYPE``, ``SUBJECT_ID``, ``RESOURCE_TYPE``, ``RESOURCE_ID``, ``PERMISSION_NAME``. For example: .. code-block:: console $ libeufin-cli permissions revoke \ some-subject-type some-subject-id \ some-resource-type some-resource-id \ facade.anastasis.history { } $ libeufin-cli permissions list { "permissions" : [ ] } This example undoes the effect of the previous (``permissions grant``) example. accounts -------- WRITEME accounts transactions ^^^^^^^^^^^^^^^^^^^^^ WRITEME accounts task-status ^^^^^^^^^^^^^^^^^^^^ WRITEME accounts task-schedule ^^^^^^^^^^^^^^^^^^^^^^ WRITEME accounts task-delete ^^^^^^^^^^^^^^^^^^^^ WRITEME accounts submit-payment ^^^^^^^^^^^^^^^^^^^^^^^ WRITEME accounts show-payment ^^^^^^^^^^^^^^^^^^^^^ WRITEME accounts show ^^^^^^^^^^^^^ WRITEME accounts prepare-payment ^^^^^^^^^^^^^^^^^^^^^^^^ WRITEME accounts list-tasks ^^^^^^^^^^^^^^^^^^^ WRITEME accounts list-payments ^^^^^^^^^^^^^^^^^^^^^^ WRITEME accounts fetch-transactions ^^^^^^^^^^^^^^^^^^^^^^^^^^^ WRITEME accounts delete-payment ^^^^^^^^^^^^^^^^^^^^^^^ WRITEME facades ------- WRITEME facades new-taler-wire-gateway-facade ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ WRITEME facades new-anastasis-facade ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ WRITEME facades list ^^^^^^^^^^^^ WRITEME See Also ======== .. TODO: libeufin-sandbox(1), libeufin-cli(1). Bugs ==== Report bugs by using https://bugs.taler.net or by sending electronic mail to .