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 with the --quotes option 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.

Note

In GnuCash version 4.x and earlier one used separate perl programs gnc-fq-check instead of gnucash-cli --quote info and gnc-fq-dump instead of gnucash-cli --quote dump.

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

Abstract

The --quotes info option returns the version number of the currently installed Finance::Quote module and a list of available sources. It informs you also if there is a problem with your installation and gives the reasons.

The latest Finance::Quote version is 1.64. The list of sources that follows depends on the Finance::Quote version.

The input of

gnucash-cli { -Q | --quotes } info

in the terminal produces the following output: 

$ gnucash-cli --quotes info
Found Finance::Quote version 1.57.
Finance::Quote sources:
aex          alphavantage              amfiindia    asegr        asx
aufunds      australia    bamosz       bet          bloomberg    bourso
bse          bseindia     bvb          canada       canadamutual
comdirect    cse          deka         dutch        dwsfunds     europe
fetch_live_currencies     fidelity     fidelity_direct
finanzpartner             fondsweb     fool         france       ftfunds
fundata      fundlibrary  goldmoney    googleweb    greece       hu
hufund       hungary      hustock      iexcloud     india        indiamutual
known_currencies          marketwatch  morningstarau
morningstarch             morningstarjp             morningstaruk
mstaruk      nasdaq       nseindia     nyse         nzx          onvista
oslobors     romania      seb_funds    sinvestor    six
tesouro_direto            tiaacref     tmx          tradegate    tradeville
treasurydirect            troweprice   troweprice_direct         tsp
tsx          twelvedata   ukfunds      unionfunds   usa          xetra
yahoo_json   yahooweb     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

In this case, Finance::Quote is not installed correctly and therefore cannot be used for quote retrieval with GnuCash. Please install Finance::Quote according to the instructions at Section 11.2, “Installing Finance::Quote”.

11.3.2. Displaying Quotes in a Terminal Window

Abstract

The --quotes dump option provides quotes for a source and a list of of symbols in a format that is easy for humans to read. This is useful to verify that a particular online quote source is accessible and provides data.

You can also check to see if the symbol you want to use for your online price retrieval is available at the desired quote source.

Tip

You may use gnucash-cli --quotes dump to test quote sources and symbols individually should GnuCash report an error during quote retrieval. The command will show the fields required by GnuCash; use gnucash-cli --verbose --quotes dump to see all of the information returned by Finance::Quote.

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:

gnucash-cli { -Q | --quotes } dump [ -V | --verbose ] Source Symbol ...

It offers two output forms for non-currency securities and one for currency exchange rates.

Currencies

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

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

1 EUR = 1.09837 USD

Stocks

To retrieve quotes of your securities, please enter the quote source and the desired symbol.

  • 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 yahooweb AAPL
Finance::Quote fields GnuCash uses:
    symbol: AAPL            <=== required
      date: 07/28/2023      <=== recommended
  currency: USD             <=== required
      last: 193.22          <=\
       nav:                 <=== one of these
     price:                 <=/

  • With the --verbose 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 gnucash-cli --verbose --quotes dump alphavantage INTC
INTC:
        open => 34.8200
     isodate => 2023-07-27
       close => 34.3600
        date => 07/27/2023
      symbol => INTC
    currency => USD
currency_set_by_fq => 1
         low => 34.1100
      volume => 58890821
     success => 1
        high => 35.0300
         net => 0.1900
        last => 34.5500
    p_change => 0.5530
      method => alphavantage

    Note

    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 Edit → Preferences Section 10.2.8, “Online Quotes”.

To test if Finance::Quote works for currencies inside GnuCash, do the following:

  1. create a transaction with the desired commodity in the book currency,

  2. make a right click on it,

  3. select Edit Exchange Rate in the context menu.

  4. In the Section 6.1, “Transfer Funds Dialog Box” window click the Get exchange rate button.

If the exchange rate source and the symbol are set, the current rate will be entered in the exchange rate field.

11.3.3. Updating Quotes Automatically with gnucash-cli

With the command gnucash-cli --quotes get ${HOME}/gnucash-filename [11] you can receive the current prices of your foreign exchange and securities and write them directly into your GnuCash-file without starting the user interface. This enables an automatic, regular updating of the prices.

Note

The command fails if exclusive access to the data file is not possible, for example, the data file is opened in another GnuCash instance, or the last session for the file crashed.

The specified file ${HOME}/gnucash-filename depends on the name and location of your data file. This can be determined from the name displayed in the top frame of the GnuCash window before the “-”.

Tip

The file name can also be found in the list of recently opened files in the File menu. If you hover the mouse pointer on the menu item numbered 1 in the list of recently opened files, the full file name is displayed in the statusbar.

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 → System → 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.


[10] Since Finance::Quote 1.41 the default source for currencies is “Alpha Vantage”. See also the notes on wiki:Online_Quotes#Finance::Quote_Sources_-_Currency_Source.

[11] This replaces the command GnuCash --add-price-quotes ${HOME}/gnucash-filename in GnuCash version 4.x and earlier.

<<< Prev Home Next >>>
11.2. Installing Finance::Quote Up Appendix A. GNU Free Documentation License