Finance Commands

The finance command group drives the ReturnPro financial pipeline — from generating NetSuite templates and uploading raw data through auditing, KPI analysis, and budget projections. All finance commands operate against the ReturnPro Supabase instance.

TIP

Ensure RETURNPRO_SUPABASE_URL and RETURNPRO_SUPABASE_SERVICE_KEY are set in your .env before running any finance command.

Data Flow

The typical monthly workflow follows this sequence:

1. finance template -- Generate the NetSuite Excel template
2. Fill in the template using NetSuite's Solution7 add-in
3. finance upload -- Upload the completed XLSM to staging
4. finance upload-confirmed -- Upload confirmed income statement data
5. finance audit -- Compare staging vs confirmed figures
6. finance diagnose -- Check for data gaps and FK resolution issues

Commands

finance audit

Compare staged financials against confirmed income statement data for a given month.

# Audit a single month
optimal finance audit --months 2026-03

# Audit with a custom tolerance (default checks exact match)
optimal finance audit --months 2026-01,2026-02,2026-03 --tolerance 0.01

Flag	Description
--months	Comma-separated list of months in YYYY-MM format (required)
--tolerance	Acceptable variance threshold (decimal)

---

finance kpis

Export KPI data for specified months and programs.

# Table output for the current quarter
optimal finance kpis --months 2026-01,2026-02,2026-03

# Filter by programs and export as CSV
optimal finance kpis --months 2026-03 --programs "Program A,Program B" --format csv

Flag	Description
--months	Comma-separated months in YYYY-MM format
--programs	Filter by program names (comma-separated)
--format	Output format: table (default) or csv

---

finance anomalies

Detect rate anomalies across a date range.

# Scan for anomalies in Q1
optimal finance anomalies --from 2026-01 --to 2026-03

# Use a stricter threshold
optimal finance anomalies --from 2026-01 --to 2026-03 --threshold 0.05

Flag	Description
--from	Start month (YYYY-MM)
--to	End month (YYYY-MM)
--threshold	Sensitivity threshold (lower = stricter)

---

finance diagnose

Check for data gaps and foreign key resolution issues in staging data.

optimal finance diagnose --months 2026-03
optimal finance diagnose --months 2026-01,2026-02,2026-03

Flag	Description
--months	Comma-separated months to diagnose (required)

---

finance upload

Upload a NetSuite CSV/XLSX/XLSM file to the stg_financials_raw staging table. The parser extracts cached formula results from Solution7 XLSM files.

optimal finance upload --file ./netsuite-march.xlsm --user-id <uuid>

Flag	Description
--file	Path to the NetSuite file (CSV, XLSX, or XLSM) (required)
--user-id	Supabase user UUID (required)

WARNING

upload inserts rows without upserting. Re-uploading the same file will create duplicates. Delete existing rows for the month first if you need to re-run.

---

finance upload-confirmed

Upload confirmed income statement data. Upserts on (account_code, period), so it is safe to re-run.

optimal finance upload-confirmed --file ./income-stmt-march.csv --user-id oracle

Flag	Description
--file	Path to the income statement file (required)
--user-id	Uploading user identifier

---

finance upload-r1

Upload R1 volume data from XLSX files. Uses a streaming parser to handle large files (549K+ rows). Each file produces 3 insert sets per program group: Unit (TRGID count), Pallet (LocationID count), Qty (allocation-based).

optimal finance upload-r1 --file ./check-in-march.xlsx --user-id <uuid> --month 2026-03 --volume-type checked_in
optimal finance upload-r1 --file ./orders-closed.xlsx --user-id <uuid> --month 2026-03 --volume-type order_closed
optimal finance upload-r1 --file ./ops-complete.xlsx --user-id <uuid> --month 2026-03 --volume-type ops_complete

Flag	Description
--file	Path to the R1 XLSX file (required)
--user-id	Supabase user UUID (required)
--month	Month in YYYY-MM format (required)
--volume-type	Volume type: checked_in, order_closed, or ops_complete (default: checked_in)

WARNING

upload-r1 is INSERT-only. Re-uploading creates duplicates. Delete the old batch first if you need to re-run.

---

finance sync-dims

Sync dimension tables (accounts, program IDs) from a file.

# Preview changes
optimal finance sync-dims --file ./dim-accounts.csv

# Apply the sync
optimal finance sync-dims --file ./dim-accounts.csv --execute

Flag	Description
--file	Path to the dimension data file (required)
--execute	Apply changes (without this flag, changes are previewed only)

---

finance preflight

Run pre-template validation to catch issues before generating a template.

optimal finance preflight --month 2026-03
optimal finance preflight --month 2026-03 --income-statement ./income-stmt.csv

Flag	Description
--month	Target month to validate
--income-statement	Path to income statement for cross-validation

---

finance template

Generate a NetSuite Excel template pre-filled with dimension data (accounts and program IDs).

optimal finance template --output ./netsuite-template-march.xlsx

Flag	Description
--output	Output file path for the generated template

---

finance month-close

Run the full monthly close workflow. Steps can be skipped if parts have already been completed.

# Close March
optimal finance month-close --month 2026-03

# Resume from a specific step
optimal finance month-close --month 2026-03 --from audit

# Skip certain steps
optimal finance month-close --month 2026-03 --skip upload,template

Flag	Description
--month	Target month (required)
--from	Start from a specific step
--skip	Comma-separated list of steps to skip

---

finance pipeline

Trigger the n8n financial pipeline for a given month.

# Trigger all steps
optimal finance pipeline --month 2026-03

# Trigger specific steps and poll for completion
optimal finance pipeline --month 2026-03 --steps upload,audit --poll

Flag	Description
--month	Target month (required)
--steps	Comma-separated pipeline steps to run
--poll	Poll for pipeline completion status

---

Scenario projections

Budget projections moved to the dedicated scenario command group. See Scenarios for optimal scenario save, list, compare, and delete.