11.3. Using gnucash-cli for Testing and Automation.

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.63. 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:

create a transaction with the desired commodity in the book currency,
make a right click on it,
select Edit Exchange Rate in the context menu.
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

Run crontab -e.

Add the following line to your crontab:

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

Important

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

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

Select Start → System → Task Scheduler
Select Create Task….
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 Table A.1, “Currency source for Finance::Quote”.

^[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. `GnuCash` Tips and tidbits