Transaction Commands

The tx command group handles bank transaction ingestion, categorization, and cleanup. It parses CSV exports from banking providers, deduplicates entries, and applies AI-powered categorization.

Workflow

A typical transaction workflow:

1. Export a CSV from your bank
2. tx ingest -- Parse and deduplicate into Supabase
3. tx stamp -- Categorize transactions
4. Review categorized data in the dashboard

Commands

tx ingest

Parse a bank CSV file, deduplicate entries, and insert new transactions into Supabase.

# Ingest a bank export
optimal tx ingest --file ./chase-march-2026.csv --user-id oracle

Flag	Description
--file	Path to the bank CSV file (required)
--user-id	User identifier for the imported transactions (required)

The ingestion process:

• Parses the CSV according to known bank formats
• Detects and skips duplicate transactions already in the database
• Inserts new, unique transactions
• Reports counts of inserted vs skipped rows

TIP

The deduplication logic uses a combination of date, amount, and description to identify duplicates. Importing the same CSV twice will not create duplicate records.

---

tx stamp

Categorize transactions using AI-powered classification. Assigns categories like "Payroll", "Software", "Utilities", etc.

# Categorize all uncategorized transactions
optimal tx stamp --user-id oracle

# Preview categorizations without writing
optimal tx stamp --user-id oracle --dry-run

Flag	Description
--user-id	User identifier (required)
--dry-run	Preview categorizations without saving

---

tx delete

Batch delete transactions from a specific table. Safe by default -- without --execute, only shows a preview of what would be deleted.

# Preview what would be deleted (dry-run by default)
optimal tx delete --table transactions --date-from 2026-01-01 --date-to 2026-01-31

# Filter by user and source
optimal tx delete --table transactions --user-id <uuid> --source chase

# Delete staging data by month and account code
optimal tx delete --table stg_financials_raw --month 2026-03 --account-code 4100

# Execute the deletion (requires confirmation prompt)
optimal tx delete --table transactions --date-from 2026-01-01 --date-to 2026-01-31 --execute

Flag	Description
--table	Target table: transactions or stg_financials_raw (required)
--user-id	User UUID filter
--date-from	Start date (YYYY-MM-DD)
--date-to	End date (YYYY-MM-DD)
--source	Source filter
--category	Category filter (transactions table)
--account-code	Account code filter (staging table)
--month	Month filter in YYYY-MM format (staging table)
--execute	Actually perform the deletion (prompts for confirmation)

WARNING

Without --execute, the command only previews what would be deleted -- showing the count, grouped breakdown, and a sample of matching rows. Always preview first. When using --execute, at least one filter is required and you must type "yes" to confirm.