Command Line

WyzBooks can be controlled from the Terminal for importing data, resetting state, debugging invoices, and running headless report comparisons. This is useful for automation, scripting, and power-user workflows.

Getting Started

Install the wyzbooks command from Settings > Advanced > Command Line Tool. Once installed, open Terminal and run:

wyzbooks <arguments>

If you prefer not to install the CLI tool, you can also use the macOS open command directly:

open -a WyzBooks --args <arguments>

Arguments can be combined freely. File paths can be absolute or relative to your current directory.

Data Reset

Three flags control what gets reset when the app launches. Reset happens before any import, so you can start fresh and import in a single command.

• --reset — Reset both data and preferences to factory defaults. Clears all accounts, invoices, payments, journals, contacts, bank transactions, and restores all settings.
• --reset-data — Reset data only. Clears all accounting data but keeps your preferences, sidebar order, business info, and other settings intact.
• --reset-prefs — Reset preferences only. Restores default settings while leaving all accounting data untouched.

# Full factory reset — data and settings
wyzbooks --reset

# Start fresh with data but keep your customized settings
wyzbooks --reset-data

# Restore default settings without losing any transactions
wyzbooks --reset-prefs

# Reset data only, then immediately import from QuickBooks
wyzbooks --reset-data --iif ~/Downloads/company.iif

Cloud Sync Flags

• --offline — Launch with multi-user mode and cloud sync disabled. Disables auto-reconnect. Useful for troubleshooting or working without a network.
• --push-first — When cloud sync auto-reconnects on launch, push local data to the server before accepting any server data. Use when this machine is the source of truth.
• --pull-first — When cloud sync auto-reconnects on launch, replace local data with server data. Use when the server is the source of truth.

Importing Data

Three arguments handle the import pipeline. When any import argument is present, the app opens directly to the Import page and processes the files automatically.

• --iif <path> — Import a QuickBooks Interchange Format (IIF) file. Creates accounts, contacts, items, payment terms, and optionally invoices with self-payments. This is typically the first step when migrating from QuickBooks.
• --csv <path> — Import a CSV file. Auto-detects the format: trial balance, transaction list, transaction detail, or aging report. Groups rows into balanced journal entries.
• --csvb <path> — Import a second CSV for invoice line-item enrichment. Adds Item, Quantity, Sales Price, Due Date, and Terms to invoice lines. Must be used together with --csv.

# Import just an IIF file (accounts, contacts, items)
wyzbooks --iif ~/Downloads/company-backup.iif

# Import a CSV transaction list
wyzbooks --csv ~/Accounting/2025-transactions.csv

# Full pipeline: IIF setup, then CSV transactions, then enrichment
wyzbooks --iif ~/Downloads/chart.iif --csv ~/Downloads/txns.csv --csvb ~/Downloads/detail.csv

# Fresh start: reset everything, then run full import
wyzbooks --reset --iif ~/QB-Export/accounts.iif --csv ~/QB-Export/transactions.csv --csvb ~/QB-Export/invoice-detail.csv

Debugging

Two arguments produce diagnostic output to the Terminal after import completes. Useful for verifying that invoices imported correctly and that A/R balances reconcile.

• --dump-invoice <num> — Print detailed information about a specific invoice by number, including customer, line items, amounts, matched payments, and balance remaining.
• --dump-ar — Print the full Accounts Receivable summary showing all customers, their invoices, payment applications, and outstanding balances.

# Inspect invoice 1042 after a fresh import
wyzbooks --iif data.iif --csv txns.csv --dump-invoice 1042

# Check a specific invoice
wyzbooks --dump-invoice 2001

# Dump all A/R balances after import
wyzbooks --reset --iif data.iif --csv txns.csv --dump-ar

# Combine both: inspect one invoice and see the full A/R picture
wyzbooks --csv ~/Downloads/transactions.csv --dump-invoice 1001 --dump-ar

Report Comparison

The --compare flag runs a headless comparison between a WyzBooks report and a QuickBooks CSV export. No app window is opened. The result is printed to the Terminal and saved as a JSON file in ~/.wyzbooks/.

• --compare <key> <csv-path> — Run a report comparison. The key identifies which report to compare. The CSV path points to the QuickBooks export file. The app prints a summary and exits.
• --date-from YYYY-MM-DD — Start date for the report period. Used with --compare to filter the comparison to a specific date range.
• --date-to YYYY-MM-DD — End date for the report period. Used with --compare to filter the comparison to a specific date range.

# Compare trial balance (full date range)
wyzbooks --compare trial ~/Downloads/qb-trial-balance.csv

# Compare trial balance for Q1 2025
wyzbooks --compare trial ~/Downloads/qb-trial.csv --date-from 2025-01-01 --date-to 2025-03-31

# Compare Profit & Loss for fiscal year
wyzbooks --compare pnl ~/Accounting/qb-pnl-2025.csv --date-from 2025-01-01 --date-to 2025-12-31

# Compare Balance Sheet as of end of March
wyzbooks --compare balance ~/Downloads/qb-balance.csv --date-to 2025-03-31

# Compare General Ledger for a specific month
wyzbooks --compare gl ~/Downloads/qb-gl-feb.csv --date-from 2025-02-01 --date-to 2025-02-28

# Compare A/R Aging (point-in-time report, no date range needed)
wyzbooks --compare ar_aging ~/Downloads/qb-ar-aging.csv

# Compare Customer Balance Detail
wyzbooks --compare cust_bal_detail ~/Downloads/qb-cust-detail.csv

Results are saved to ~/.wyzbooks/compare-{key}-{timestamp}.json with matched, mismatched, QB-only, and WB-only entries. See the Reports topic for more on the comparison dashboard.

Valid Report Keys

Common Workflows

Here are some typical multi-argument combinations for common tasks:

# Migration from QuickBooks: full reset, import everything, verify
wyzbooks --reset --iif ~/QB/export.iif --csv ~/QB/txns.csv --csvb ~/QB/detail.csv --dump-invoice 1001 --dump-ar

# Re-import after fixing a CSV: reset data (keep settings), re-import
wyzbooks --reset-data --iif ~/QB/export.iif --csv ~/QB/txns-fixed.csv

# Nightly comparison script: check trial balance
wyzbooks --compare trial ~/Reports/qb-trial-latest.csv --date-from 2025-01-01 --date-to 2025-12-31

# Quick data check: just dump A/R without importing anything
wyzbooks --dump-ar

# Import a single CSV trial balance to seed account balances
wyzbooks --reset-data --csv ~/Downloads/trial-balance.csv

Server Management (wbctl)

The wbctl command-line tool manages the WyzBooks API server. It is located at scripts/cloud-sync/wbctl and communicates with the server via HTTP API or SSH.

• wbctl backup — Create a server-side backup. Copies the data file to ~/wyzbooks/backups/ on the server with a date-stamped filename.
• wbctl restore <file> — Restore the server's data from a backup file. Creates a safety copy before replacing. Prompts for confirmation unless --yes is specified. After restore, restart the API server with wbctl restart.
• wbctl verify — Verify server data integrity by checking the data checksum via the API. Reports the checksum, event count, and per-collection record counts.
• wbctl health — Quick server health check (HTTP). Shows server version, uptime, and API status.
• wbctl clients — List connected SSE clients with connection time, IP, and user-agent.
• wbctl stats <tenant> — Show detailed tenant statistics: file size, sync version, checksum, per-collection record counts.
• wbctl deploy — Deploy the latest code to the server via rsync + npm install + pm2 restart.

# Check server health
wbctl health

# Create a server-side backup
wbctl backup

# Verify data integrity
wbctl verify

# Restore from a backup (with confirmation)
wbctl restore ~/wyzbooks/backups/server-2026-04-12.json

# List connected clients
wbctl clients

For related topics, see QuickBooks Import for step-by-step import guidance, Reports for the visual comparison dashboard, and Developer for running from source with npm.