Common workflows

There are lots of ways to use hledger; here is an overview. Of course you can mix and match these if you'd like.

GUI workflow

Download and run hledger-web, eg by double-clicking on it. It should open in your web browser. Use the add form to add transactions. It will store data in its default location. (So you'll see your transactions next time you run it.)

Tutorial: hledger-web describes this in more detail.

In all of these workflows, remember to back up your computer periodically to safeguard your hledger data.

Command line workflow

At a terminal prompt, run hledger add and follow the interactive prompts to enter transactions. It will store data in its default location. Run hledger to list commands to try. Eg, run hledger bs to see your account balances (a balance sheet), and hledger is to see your income and expenses (an income statement).

Tutorial: hledger add describes this process, and hledger's basic concepts and file format, step by step. You might want to skim through this one even if you don't plan to use hledger add.

Text editor workflow

Open your preferred text editor and create a journal file, .hledger.journal in your home directory. (Or elsewhere, and set its path in the LEDGER_FILE environment variable.) Create transactions by hand using journal file format. Once you have a few, you can copy/paste them to make more. When you want more assistance, set up an editor mode. Here's an example:

; $HOME/.hledger.journal

2020-01-01 opening balances
    assets:checking         $1234

2020-03-15 client payment
    assets:checking         $2000

2020-03-20 Sprouts
    expenses:food:groceries  $100
    assets:cash               $40

Run hledger in a terminal to see reports, as in the Command line workflow. Eg:

$ hledger bs
Balance Sheet 2020-03-20

             || 2020-03-20 
 Assets      ||            
 assets      ||      $3134 
   cash      ||        $40 
   checking  ||      $3094 
             ||      $3134 
 Liabilities ||            
 Net:        ||      $3134 

$ hledger is -M
Income Statement 2020-01-01-2020-03-20

                         || Jan  Feb    Mar 
 Revenues                ||                 
 income:consulting       ||   0    0  $2000 
                         ||   0    0  $2000 
 Expenses                ||                 
 expenses:food:groceries ||   0    0   $100 
                         ||   0    0   $100 
 Net:                    ||   0    0  $1900 

TUI workflow

Use hledger add once (see above) to create a journal file. Now run hledger-ui to view account balances. Use the onscreen help to get around. Eg, press a to add a transaction, and follow the prompts (it uses hledger add).

Tutorial: hledger-ui describes this setup in more detail.

CSV import workflow

Download CSV files from banks and financial institutions, manually or using tools/services that automate this (ledger_autosync, Plaid, plaid2qif, Tiller etc.) Use hledger's import command to convert and import the new transactions, and use any of the hledger UIs to see reports.

Importing CSV data is a quick tutorial on the importing from CSV part. Some downloading helpers can be found at (search for "download").

Some more advanced workflows