11.3. Using gnucash-cli for Testing and Automation.
<<< Prev Chapter 11. Setting Up the Quote Retrieval Next >>>

11.3. Using gnucash-cli for Testing and Automation.

Abstract

GnuCash provides a commandline facility gnucash-cli that one can use in a terminal session to check the version and supported source modules, to display the quotes or exchange rates for selected securities or currencies, or to update all of the prices in a book without launching the GUI.

11.3.1. Displaying the Finance::Quote Version and Supported Sources

gnucash-cli --quotes info produces the following output:

  $ gnucash-cli --quotes info
  Found Finance::Quote version 1.52.
  Finance::Quote sources:
  aex          alphavantage              amfiindia    asegr        asx
  aufunds      australia    bamosz       bet          bloomberg    bourso
  bse          bseindia     canada       canadamutual              comdirect
  cse          deka         dutch        dwsfunds     europe
  fetch_live_currencies     fidelity     fidelity_direct
  finanzpartner             fondsweb     fool         ftfunds      fundata
  fundlibrary  goldmoney    greece       hu           hufund       hungary
  hustock      iexcloud     india        indiamutual  known_currencies
  morningstarau             morningstarch             morningstarjp
  mstaruk      nasdaq       nseindia     nyse         nzx          onvista
  oslobors     romania      seb_funds    six          tesouro_direto
  tiaacref     tmx          tradeville   troweprice   troweprice_direct
  tsp          ukfunds      unionfunds   usa          usfedbonds   yahoo_json
  za

If there's a problem with your installation it will tell you about it. For example in this case we're missing the Perl modules Finance::Quote and JSON::Parse:

  $ gnucash-cli --quotes info
  Failed to initialize Finance::Quote: missing_modules Finance::Quote JSON::Parse

11.3.2. Displaying Quotes in a Terminal Window

To display a quote for one or more stocks or the exchange rate for one or more currencies you can use gnucash-cli --quotes dump as follows. It offers two output forms for non-currency securities and one for currency exchange rates.

  • Currencies use the source currency and require at least two ISO-4217 currency codes; the exchange rates are denominated in the first code. For example: 

            $ gnucash-cli --quotes dump currency USD GBP EUR
        1 GBP = 1.11917349089527 USD

        1 EUR = 0.9717 USD

  • Stocks

    • A short form displaying only the fields that GnuCash uses along with comments indicating whether the fields are optional or required; you can use this to determine if GnuCash will be able to use the quote to update your book's price database. 

              $ gnucash-cli --quotes dump yahoo_json AAPL
        Finance::Quote fields GnuCash uses:
            symbol: AAPL            <=== required
              date: 10/14/2022      <=== recommended
          currency: USD             <=== required
              last: 138.38          <=\
               nav:                 <=== one of these
             price:                 <=/

    • With the -v option a possibly longer output showing all of the fields Finance::Quote returned. This can be useful to troubleshoot problems with a Finance::Quote source module. 

              $ ALPHAVANTAGE_API_KEY=123456789 bin/gnucash-cli -V --quotes dump alphavantage INTC
        INTC:
                     method => alphavantage
                   p_change => -1.9304
                       high => 26.6300
                       date => 10/14/2022
         currency_set_by_fq => 1
                      close => 26.4200
                   currency => USD
                    isodate => 2022-10-14
                        low => 25.7600
                    success => 1
                        net => -0.5100
                       open => 26.4600
                     symbol => INTC
                     volume => 48118005
                       last => 25.9100

      Notice that in this case we used alphavantage and provided the ALPHAVANTAGE_API_KEY on the command line. That's not necessary if the key is already stored in the shell environment or in GnuCash preferences.

11.3.3. Updating Prices Automatically with gnucash-cli

You have to register the gnucash-cli with a scheduler in order to get Online Quotes automatically and periodically. The method depends on your OS.

Example 11.1. Automated quote retrieval every Friday at 4:00 p.m.

Procedure 11.7. On Linux and macOS

Register gnucash-cli with cron.

  1. Run crontab -e.

  2. Add the following line to your crontab: 

    0 16 * * 5 gnucash-cli --quotes get ${HOME}/gnucash-filename > /dev/null 2>&1

    Important

    On Linux if there is no graphic session that has already started the dbus, running on your computer at the time of the quote request, you must do the entry as follows instead: 

    0 16 * * 5 env `dbus-launch` sh -c 'trap "kill $DBUS_SESSION_BUS_PID" EXIT;
gnucash-cli --quotes get ${HOME}/gnucash-filename > /dev/null 2>&1

    (Do not copy the line breaks into the crontab, they were inserted here only for the purpose of readability).

Procedure 11.8. On Windows

Register gnucash-cli with Task Scheduler.

  1. Select Start → Windows Administrative Tools → Task Scheduler .

  2. Select Create Task.

  3. Enter the appropirate items on Create Task Window.

Adjust the time to the close of the stock exchange and consider fund quotes, that the net asset value (NAV) is determined well after the markets closed. The types have their description in Section 8.6, “Price Editor”.


Some users have made additions to the wiki and shared their experiences on the Online Quotes Page on GnuCash Wiki.

<<< Prev Home Next >>>
11.2. Installing Finance::Quote Up Appendix A. GnuCash Tips and tidbits