README.md — tally

1# tally

3Personal finance management CLI and MCP server. Pulls transactions from Wise,

4categorizes them, writes to hledger journal files, and generates financial

5summaries.

7## Features

9- Pull transactions from Wise API across all currency balances

10- Map Wise transactions to hledger journal format with proper double-entry bookkeeping

11- Deduplicate imports — safe to run repeatedly without double-counting

12- Run hledger reports (balance, register, income statement)

13- List uncategorized transactions for review

14- Dual-mode: works as both a CLI tool and an MCP server for AI-assisted bookkeeping

16## CLI Usage

18```

19tally serve Start MCP server

20tally pull [--since DATE] [--until DATE] [--profile TYPE]

21 Pull transactions from Wise

22tally import [--journal FILE] [--since DATE] [--until DATE]

23 Pull and write to journal

24tally balance [--profile TYPE] Show Wise balances

25tally report [--journal FILE] [--type bal|reg|is] [QUERY]

26 Run hledger reports

27tally categorize [--journal FILE] List uncategorized transactions

28```

30### Examples

32```bash

33# Pull recent transactions

34tally pull --since 2026-03-01T00:00:00Z

36# Pull transactions within a date range

37tally pull --since 2026-01-01T00:00:00Z --until 2026-03-31T23:59:59Z

39# Import transactions to journal with deduplication

40tally import --journal finances.journal --since 2026-01-01T00:00:00Z

42# Check current Wise balances

43tally balance

45# Run a balance report

46tally report --type bal assets

48# Monthly income statement

49tally report --type is

51# List uncategorized transactions

52tally categorize --journal finances.journal

53```

55## MCP Server Tools

57When running as an MCP server (`tally serve`), the following tools are available:

59| Tool | Description |

60|------|-------------|

61| `tally/pull` | Pull recent transactions from Wise API |

62| `tally/import` | Pull and import new transactions into journal |

63| `tally/balance` | Show current Wise account balances |

64| `tally/report` | Run hledger reports (bal, reg, is) |

65| `tally/categorize` | List uncategorized transactions for review |

67## Configuration

69Environment variables:

71| Variable | Required | Description |

72|----------|----------|-------------|

73| `WISE_API_TOKEN` | Yes (for Wise operations) | Wise personal API token |

74| `TALLY_JOURNAL` | No | Default journal file path (default: `main.journal`) |

75| `TALLY_PROFILE` | No | Default Wise profile type: `personal` or `business` (default: `personal`) |

77## Account Mapping

79Wise transactions are mapped to hledger accounts as follows:

81- **Wise balances**: `assets:wise:{currency}` (e.g., `assets:wise:eur`, `assets:wise:usd`)

82- **Debit transactions**: `expenses:uncategorized` (re-categorize after import)

83- **Credit transactions**: `income:uncategorized` (re-categorize after import)

85Each imported transaction includes the Wise reference number as both a transaction

86code and a `ref` tag for deduplication.

88## Dependencies

90- [sigil-wise](https://codeberg.org/sigil/sigil-wise) — Wise API client library

91- [sigil-ledger](https://codeberg.org/sigil/sigil-ledger) — hledger journal read/write

92- [sigil-mcp](https://codeberg.org/sigil/sigil) — MCP server framework

93- [hledger](https://hledger.org/) — required on PATH for report commands

95## Building

97Requires a C toolchain. On Guix:

99```bash

100guix shell -m ../sigil/manifest.scm -- env CC=gcc sigil build --redirects dev-redirects.sgl

101```

102

103## Testing

104

105```bash

106guix shell -m ../sigil/manifest.scm -- env CC=gcc sigil test --redirects dev-redirects.sgl

107```

108

109Note: tests require a `lib` symlink to the build output for dependency resolution:

110

111```bash

112ln -s build/dev/lib lib

113```