`hledger add`: non-interactive mode for automation and AI agents

[machulav]

The hledger add command is interactive-only — it prompts for input and requires confirmation, which makes it great for humans but unusable for automation, scripts, and AI agents that need to add transactions programmatically via CLI.

Current workaround

Directly appending formatted journal text to the file + validating with hledger check. This works, but bypassing hledger add means losing its built-in validation, duplicate detection, and account-name checking in favor of reimplementing them externally.

Proposal

A non-interactive mode accepting a JSON transaction on stdin:

echo '{
  "date": "2024-03-25",
  "description": "Grocery Store",
  "postings": [
    { "account": "expenses:food", "amount": "$42.50" },
    { "account": "assets:checking" }
  ]
}' | hledger add --json

Or via argument:

hledger add --json '{"date":"2024-03-25","description":"Grocery Store","postings":[{"account":"expenses:food","amount":"$42.50"},{"account":"assets:checking"}]}'

Draft CLI help changes:

Flags:
     --no-new-accounts      don't allow creating new accounts
     --json                 read transaction as JSON from stdin or argument
                            (non-interactive mode, for automation/scripting)

Draft manual addition (under add):

Non-interactive mode

With --json, hledger add accepts a JSON-formatted transaction instead of
prompting interactively. The transaction is validated, checked for duplicates,
and appended to the journal — same as interactive mode, but suitable for
scripts and automation tools. If validation fails, hledger exits with a
non-zero status and prints the error to stderr.

Context

AI agents and automation tools are increasingly integrating with hledger (see #2547, #2510, hledger-mcp). A non-interactive add would make programmatic integration much simpler — no need to reimplement validation logic.

Related: #1026, #1322, #259, #844

[simonmichael]

Thanks for the proposal. I agree that there should be a non-interactive mode for add. I always intended it but never got around to it.

Currently you can provide answers as command line arguments, and if you send some more keypresses on stdin you can make it run non-interactively:

$ printf "\n\n\n\n\n\n.\n\n" | hledger add today desc assets 1 equity
$

I think that doesn't do a full validation though; you'd have to do hledger check ... afterward. And it might fail, but the entry has already been written to the file. I guess that's what you mean by

bypassing hledger add means losing its built-in validation, duplicate detection, and account-name checking in favor of reimplementing them externally.

I don't remember what validation add does before writing - I thought not as much as check, but maybe it's equivalent if you run both with -s ?