cashutil --  Querying GnuCash data as objects using QOF.


cashutil [--version] | [-?|--help] | [--usage] | [-x|--xml-file filename] | [-l|--list] | [--explain] | [ [-d|--database string] | [-e|--exclude string] ] [-t|--date string] [ [-s|--sql string] | [-f|--sql-file filename] ] [-w|--write filename] [--compress integer [0]] [--debug]

cashutil --shell [-w|--write filename] [--debug] [--compress integer [0]]


CashUtil provides access to GnuCash data as queriable objects. Cashutil can write selected GnuCash data to QSF XML and runs SQL-type queries on the XML file.


Use exactly one of -x, -l, --shell or --explain.

-x, --xml-file filename

Query the offline storage in filename

-l, --list

Lists all databases supported by the current QOF framework. Any options are ignored.


List the fields within the specified database and exit, requires -d.


Display version of cashutil.


Start the QOF interactive shell.

Shell commands

The shell provides interactive data input and export using a top level shell and sub shells. The top level shell provides book-level interaction - load, write, merge - as well as access to the sub shells. Editing an existing instance uses a sub shell to select the instance to edit and supports editing parameter values, printing the instance data and deleting the instance. Adding an instance simply loads an editing shell with the new instance pre-selected. All shell commands, including help, are context-sensitive. e.g. in the top shell, explain requires an object type argument, in a sub shell where the object type is already set, explain does not require an argument.

The shell prompt indicates the current shell type:

Top level shell:


Select / Edit shell for an Account:


Top level shell commands

add [object]

Add a new instance of the object and load a sub-shell with this instance pre-selected to edit the parameter values.

edit [object]

Select one instance and edit the parameter values.

delete [object]

Select one instance for deletion.


Synonym for the --list command outside the shell.

print [object]

Select one instance and print the parameter values.


Like the --explain command outside the shell. In the top level shell, explains the specified object. In a sub-shell, explains the object in use.

load [filename]

Replace the current book with data from the file. Prompt to save the current book, if any.

write [filename]

Write out the current book. If no filename is given, write to the original file. (uses STDOUT if STDIN is used.)

merge [filename]

Merge data from the file into the current book.


Run a SQL statement.

help | ?

The help for the top level shell.

quit | q | exit

Quit the shell.

Sub shell commands

edit [parameter] [value]

Edit/set the value in the specified parameter of the current object.


Like the --explain command outside the shell. In a sub-shell, explain parameter names and types of the object in use.


Print the parameter values of the current instance. Useful to check the values before and after an edit.

help | ?

The context-sensitive help for the sub-shell.

quit | q | exit

Quit the sub-shell.


cashutil options

Use -dte, optionally with either -s or -f, followed by -w.

-d, --database string

Shorthand to only query objects within one specific supported database.

-t, --date string

Shorthand to only query objects that contain the specified date. Specify dates using YY-MM-DD, YY-MM or just YY. Single digits can omit the leading zero, e.g. 04-12-1, 1st December 2004 - years less than 100 are assumed to be in the 21st century. Years prior to 2000 can be specified as YYYY-MM-DD etc. This value is taken as a range, 05-03-01 includes all times between Tue Mar 1 00:00:00 UTC 2005 and Tue Mar 1 23:59:59 UTC 2005. 05-03 includes all dates and times between Tue Mar 1 00:00:00 UTC 2005 and Thu Mar 31 23:59:59 UTC 2005. 05 includes all dates and times in 2005.

-e, --exclude string

Shorthand to exclude a supported database from the query.

-s, --sql string

Specify a SQL query on the command line.

-f, --sql-file filename

Specify one or more SQL queries contained in a file.

-w, --write filename

Write the results of any query to the file.

--compress integer [0]

The level of compression to use on the output file. Use zero for no compression, a number from 1 to 9 increases the level of compression. Unless the file is very large, values over 4 produce little or no extra compression. The default is zero, no compression.

Compression is not available when using STDOUT.

The use of file extensions is entirely up to the user. CashUtil does not require files to have any particular extension, compression is automatically detected if used.

CashUtil does NOT, therefore, add a .gz extension for you. (Neither does it add or require a .xml or .xml.gz extension.)


Enable debug output using /tmp/cashutil.trace which will be created if it does not exist or overwritten it if it does. If this fails, creates a temporary trace file in /tmp or uses stderr.

help options

-?, --help

Display the help synopsis for cashutil and exit.


Display a brief usage message and exit.

Return values

CashUtil returns zero on success or negative one on error.


Show the list of supported objects.

cashutil -l

Explain the names and types of parameters for an object.

cashutil --explain -d Account

Load a gnucash data file and select one specific account. Print details of that account to STDOUT as QSF XML.

cashutil -x src/books/gnucash.xml -s "SELECT * from Account where name = 'Checking Account';"


cashutil was written by Neil Williams .

This manual page was written by Neil Williams

Reporting Bugs

Please do NOT report bugs in cashutil to GnuCash. Report bugs via the QOF-devel mailing list.


This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA