add-transaction

Adds a transaction to the user's Actual Budget instance using the official `@actual-app/cli` CLI. Parses natural language descriptions to extract amount, payee, account, date, category, and notes.

<quick_start> Natural language examples:

• spent $45 at Walmart on groceries
• paid $120 for electricity bill
• received $500 freelance income to checking
• coffee $4.50 today </quick_start>

Parse `env=` from `$ARGUMENTS` before any other processing. Strip it from remaining arguments. Default to `""` (empty string). Credential file: `~/.claude/channels/actual-budget/${ENV}.env`. Omit `env=` from suggested commands when ENV is empty.

Check that ~/.claude/channels/actual-budget/${ENV}.env exists. If not, tell the user to run /actual-budget:configure-actual first.

Read `/../../references/cli-setup.md` and follow the CLI setup instructions to obtain `$ACTUAL`.

<argument_parsing> $ARGUMENTS (after stripping env=) is a natural language transaction description. Extract:

• amount — numeric value in dollars (expenses are negative, income is positive)
• payee — merchant or description
• account — account name if mentioned, otherwise use the first checking account
• date — if mentioned (e.g. "yesterday", "last Friday"); default to today (YYYY-MM-DD)
• category — if mentioned or confidently inferable (e.g. "groceries" → Groceries)
• notes — any remaining context </argument_parsing>

**Resolve account and category IDs:**

$ACTUAL server get-id --type accounts --name "<account name>" --format json

If a category was mentioned:

$ACTUAL server get-id --type categories --name "<category name>" --format json

Match names case-insensitively. If ambiguous, ask the user before proceeding.

Add the transaction:

Amounts use integer cents (e.g. -$45.00 → -4500, $500 income → 50000).

$ACTUAL transactions add \
  --account <accountId> \
  --data '[{"date":"<YYYY-MM-DD>","amount":<cents>,"payee_name":"<payee>","category":"<categoryId>","notes":"<notes>"}]'

Omit category and notes fields if not provided.

<success_criteria> After a successful response, summarize what was added:

Added: $45.00 at Walmart → Groceries · Checking · 2026-03-21 </success_criteria>