gnucash-cli

Get quotes for currencies and stocks specified in a file and print them

$ gnucash-cli [[-Q|--quotes]] get [path/to/file.gnucash]

$ gnucash-cli --report run --name "[Balance Sheet]" [path/to/file.gnucash]

gnucash-cli [OPTIONS] COMMAND [ARGUMENTS...]
Example: gnucash-cli --file mydata.gnucash report IncomeStatement --output report.html

--file FILE
    Specifies the GnuCash data file (e.g., .gnucash) to operate on. This option is almost always required.

--output FILE
    Directs the output of commands (e.g., reports) to the specified FILE instead of standard output.

--report REPORT_NAME
    Generates the specified GnuCash report by REPORT_NAME. Often used with `--file` and `--output`.

--report-option KEY=VALUE
    Passes specific options to a generated report. Can be used multiple times for different options.

--import FILE
    Imports transactions from FILE. Supports formats like QIF, OFX, or CSV.

--export TYPE
    Exports data from the GnuCash file in the specified TYPE (e.g., QIF, CSV).

--no-gui
    Ensures no GnuCash graphical user interface is launched. This is the default behavior but can be explicitly set.

--log-to-stderr
    Sends log messages to the standard error stream.

--log-level LEVEL
    Sets the verbosity of log messages. LEVEL can be `error`, `warning`, `info`, `debug`, or `trace`.

--version
    Displays the gnucash-cli version information and exits.

--help
    Displays a summary of command-line options and exits.

COMMAND
    The specific action to perform. Common commands include `report`, `validate`, `check-prices`, `import`, `export`.

ARGUMENTS...
    Additional arguments specific to the chosen COMMAND. For example, `report` takes a REPORT_NAME as an argument.

The gnucash-cli command provides a non-graphical, command-line interface to GnuCash, the popular personal and small-business financial accounting software. It is designed for scripting and automating common tasks without launching the full GnuCash graphical user interface. This includes generating reports, importing and exporting data in various formats (like QIF, OFX, CSV), validating data integrity, and performing other batch operations on your GnuCash financial files. It's particularly useful for users who need to automate financial reporting, integrate GnuCash into other systems, or perform maintenance tasks on their data files via scripts or cron jobs. Unlike the main gnucash application, gnucash-cli is geared towards non-interactive processing, making it an essential tool for advanced users and system administrators.

gnucash-cli operates directly on your GnuCash data file. Always back up your file before performing write operations (e.g., `import` that modifies the file).
While powerful, not all GnuCash GUI functionalities are available via the CLI. Complex operations, such as reconciling accounts or setting up new accounts, typically require the graphical interface. Error messages can sometimes be verbose or cryptic, requiring familiarity with GnuCash's internal structure.

While the synopsis covers the general structure, gnucash-cli relies heavily on specific commands. Some frequently used ones are:
report <report-name>: Generates a specified GnuCash report (e.g., BalanceSheet, IncomeStatement).
validate: Checks the integrity of the GnuCash data file for potential errors.
check-prices: Updates security prices from configured online sources.
import <file>: Imports data from an external file into the GnuCash book.
export <type>: Exports data from the GnuCash book in a specified format.

The gnucash-cli utility was developed as part of the GnuCash project to address the growing need for batch processing and scripting capabilities. Prior to its introduction, automating tasks within GnuCash often required more complex workarounds or direct interaction with the GUI. Its development aimed to provide a stable and reliable command-line interface, making GnuCash more amenable to integration into larger financial management systems or automated reporting pipelines. It has evolved alongside the main GnuCash application, with new commands and options being added to support expanding functionalities and user requirements for non-interactive financial data management.

gnucash(1)