hport

Generate polished PDF financial reports from hledger journals.

hport turns plain-text hledger accounting data into board-ready PDF financial statements — complete with professional formatting, multi-report merging, compression, and optional password protection — all from a single CLI command.

The Problem

hledger is a powerful double-entry accounting tool, but its output lives in the terminal. When you need to share a balance sheet with stakeholders or archive quarterly financials, you're stuck copying tables into spreadsheets or manually building documents. There's no fast path from journal file to polished PDF.

The Solution

hport bridges that gap. Point it at an hledger journal and it produces publication-quality PDF reports by:

1. Extracting structured data from hledger via its JSON output
2. Building Word templates dynamically with Foxit DocGen tag syntax
3. Rendering PDFs through the Foxit Document Generation API
4. Merging, compressing, and protecting the final output via Foxit PDF Services

Reports

Report	Flag	Description
Balance Sheet	bs	Assets, Liabilities, Equity with section totals and grand total
Income Statement	is	Revenues and Expenses breakdown
Cash Flow Statement	cf	Cash inflows and outflows
Budget vs Actual	budget	5-column comparison: Account, Actual, Budget, Remaining, % Used

How It Uses Foxit APIs

hport is built on two Foxit cloud services:

Document Generation API

• Receives a .docx template (built at runtime with python-docx) containing DocGen tags like {{title}}, {{TableStart:rows}} / {{TableEnd:rows}}
• Merges the template with structured financial data
• Returns a rendered PDF

PDF Services API

• Combine — merges multiple report PDFs into a single document with bookmarks
• Compress — reduces file size for easy sharing
• Protect — adds password encryption when requested

The async task workflow (submit → poll → download) is handled transparently so the user just gets a single output file.

Architecture

hledger journal
       │
       ▼
   hledger.py ── runs hledger CLI, parses JSON → typed models
       │
       ▼
  templates.py ── generates .docx with Foxit DocGen tags
       │
       ▼
    docgen.py ── POST template + data → Foxit DocGen API → PDF
       │
       ▼
 pdfservices.py ── upload → combine → compress → protect
       │
       ▼
   report.pdf

Modules:

• cli.py — Click-based CLI entry point
• config.py — Loads credentials from .env, validates hledger is on $PATH
• models.py — Data classes (ReportRow, ReportSection, CompoundReport, BudgetReport)
• hledger.py — Subprocess runner + JSON parser
• templates.py — Dynamic .docx template builder
• docgen.py — Foxit Document Generation API client
• pdfservices.py — Foxit PDF Services API client
• reports.py — Orchestrator that ties everything together

Quick Start

Prerequisites

• Python 3.12+
• hledger on your $PATH
• Foxit API credentials (sign up here)

Install

# Clone and install
git clone https://github.com/<your-username>/hport.git
cd hport
uv sync

# Configure credentials
cp .env.example .env
# Edit .env with your Foxit API keys

Usage

# Generate all four reports from a journal file
hport sample/sample.journal -o financials.pdf

# Balance sheet + income statement only
hport sample/sample.journal --reports bs,is -o statements.pdf

# Filter by date range
hport sample/sample.journal -b 2024-01-01 -e 2024-06-30 -o h1.pdf

# Password-protect the output
hport sample/sample.journal --password secret123 -o secure.pdf

# Pipe hledger JSON directly via stdin
hledger -f sample/sample.journal balancesheet -O json | hport --stdin bs -o bs.pdf

Configuration

Set these in your .env file:

FOXIT_DOCGEN_CLIENT_ID=your_docgen_client_id
FOXIT_DOCGEN_CLIENT_SECRET=your_docgen_client_secret
FOXIT_DOCGEN_HOST=https://na1.fusion.foxit.com

FOXIT_PDF_CLIENT_ID=your_pdf_client_id
FOXIT_PDF_CLIENT_SECRET=your_pdf_client_secret
FOXIT_PDF_HOST=https://na1.fusion.foxit.com

Optional branding:

HPORT_LOGO_PATH=/path/to/logo.png    # Logo at top of each report
HPORT_COMPANY_NAME=Acme Corp          # Shown if no logo provided

Tech Stack

• Python 3.12 with type hints throughout
• Click — CLI framework
• python-docx — Programmatic Word document generation
• Requests — HTTP client for Foxit APIs
• Rich — Terminal UI with spinners and colored output
• uv — Fast Python package manager

Built at Foxit Hackathon 2025