Add sync toggle (#47)

#### Problem
Some tools always refresh the sqlite-export-for-ynab database before
running. That makes it harder to intentionally operate against an
existing local export.

#### Solution
Add a default-on `--sync` boolean option to the sqlite-backed tools.
Passing `--no-sync` skips the refresh and uses the existing database
contents.

Author: mxr

manager_for_ynab/add_transaction/README.md

@@ -5,3 +5,5 @@
 It works interactively by autocompleting payees, categories etc already in your plan.
 
 Use `--for-real` to create the transaction. Without it, the command only previews the transaction that would be sent.
+
+By default, the command refreshes the local sqlite-export-for-ynab database before reading from it. Pass `--no-sync` to use the existing database contents without syncing.

manager_for_ynab/add_transaction/__init__.py

@@ -97,6 +97,12 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Whether to refresh the SQLite DB from scratch.",
     )
+    parser.add_argument(
+        "--sync",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Refresh the SQLite DB before using it.",
+    )
     return parser
 
 
@@ -120,6 +126,7 @@ async def run(
         quiet=args.quiet,
         db=args.sqlite_export_for_ynab_db,
         full_refresh=args.sqlite_export_for_ynab_full_refresh,
+        should_sync=args.sync,
         token_override=token_override,
     )
 
@@ -137,13 +144,15 @@ async def add_transaction(
     quiet: bool,
     db: Path,
     full_refresh: bool,
+    should_sync: bool = True,
     token_override: str | None,
 ) -> int:
     token = resolve_token(token_override)
 
-    _print("** Refreshing SQLite DB **", quiet=quiet)
-    await sync(token, db, full_refresh, quiet=quiet)
-    _print("** Done **", quiet=quiet)
+    if should_sync:
+        _print("** Refreshing SQLite DB **", quiet=quiet)
+        await sync(token, db, full_refresh, quiet=quiet)
+        _print("** Done **", quiet=quiet)
 
     try:
         async with aiosqlite.connect(db) as con:

manager_for_ynab/auto_approve/README.md

@@ -23,3 +23,5 @@ Apply the approval updates:
 ```console
 $ manager-for-ynab auto-approve --for-real
 ```
+
+By default, the command refreshes the local sqlite-export-for-ynab database before reading from it. Pass `--no-sync` to use the existing database contents without syncing.

manager_for_ynab/auto_approve/__init__.py

@@ -52,18 +52,21 @@ async def run(
         "--sqlite-export-for-ynab-db", type=Path, default=default_db_path()
     )
     parser.add_argument("--sqlite-export-for-ynab-full-refresh", action="store_true")
+    parser.add_argument("--sync", action=argparse.BooleanOptionalAction, default=True)
     parser.add_argument("--for-real", action="store_true")
     parser.add_argument("--quiet", action="store_true")
 
     args = parser.parse_args(argv)
     db: Path = args.sqlite_export_for_ynab_db
     full_refresh: bool = args.sqlite_export_for_ynab_full_refresh
+    should_sync: bool = args.sync
     for_real: bool = args.for_real
     quiet: bool = args.quiet
 
     result = await auto_approve(
         db=db,
         full_refresh=full_refresh,
+        should_sync=should_sync,
         for_real=for_real,
         token_override=token_override,
         quiet=quiet,
@@ -79,15 +82,17 @@ async def auto_approve(
     *,
     db: Path,
     full_refresh: bool,
+    should_sync: bool = True,
     for_real: bool,
     token_override: str | None,
     quiet: bool,
 ) -> AutoApproveResult:
     token = resolve_token(token_override)
 
-    _print("** Refreshing SQLite DB **", quiet=quiet)
-    await sync(token, db, full_refresh, quiet=quiet)
-    _print("** Done **", quiet=quiet)
+    if should_sync:
+        _print("** Refreshing SQLite DB **", quiet=quiet)
+        await sync(token, db, full_refresh, quiet=quiet)
+        _print("** Done **", quiet=quiet)
 
     async with aiosqlite.connect(db) as con:
         con.row_factory = aiosqlite.Row

manager_for_ynab/pending_income/README.md

@@ -29,3 +29,5 @@ Exclude already matched transactions (to avoid changing the date once YNAB picks
 ```console
 $ manager-for-ynab pending-income --skip-matched
 ```
+
+By default, the command refreshes the local sqlite-export-for-ynab database before reading from it. Pass `--no-sync` to use the existing database contents without syncing.

manager_for_ynab/pending_income/__init__.py

@@ -52,20 +52,23 @@ async def run(
         "--sqlite-export-for-ynab-db", type=Path, default=default_db_path()
     )
     parser.add_argument("--sqlite-export-for-ynab-full-refresh", action="store_true")
+    parser.add_argument("--sync", action=argparse.BooleanOptionalAction, default=True)
     parser.add_argument("--for-real", action="store_true")
     parser.add_argument("--skip-matched", action="store_true")
     parser.add_argument("--quiet", action="store_true")
 
     args = parser.parse_args(argv)
     db: Path = args.sqlite_export_for_ynab_db
     full_refresh: bool = args.sqlite_export_for_ynab_full_refresh
+    should_sync: bool = args.sync
     for_real: bool = args.for_real
     skip_matched: bool = args.skip_matched
     quiet: bool = args.quiet
 
     result = await pending_income(
         db=db,
         full_refresh=full_refresh,
+        should_sync=should_sync,
         for_real=for_real,
         skip_matched=skip_matched,
         token_override=token_override,
@@ -83,16 +86,18 @@ async def pending_income(
     *,
     db: Path,
     full_refresh: bool,
+    should_sync: bool = True,
     for_real: bool,
     skip_matched: bool,
     token_override: str | None,
     quiet: bool,
 ) -> PendingIncomeResult:
     token = resolve_token(token_override)
 
-    _print("** Refreshing SQLite DB **", quiet=quiet)
-    await sync(token, db, full_refresh, quiet=quiet)
-    _print("** Done **", quiet=quiet)
+    if should_sync:
+        _print("** Refreshing SQLite DB **", quiet=quiet)
+        await sync(token, db, full_refresh, quiet=quiet)
+        _print("** Done **", quiet=quiet)
 
     async with aiosqlite.connect(db) as con:
         con.row_factory = aiosqlite.Row

manager_for_ynab/reconciler/README.md

@@ -49,6 +49,8 @@ $ manager-for-ynab reconciler --mode interactive-batch --account-likes Checking
 Target balances in matching order, separated by spaces: 500 290
 ```
 
+By default, the command refreshes the local sqlite-export-for-ynab database before reading from it. Pass `--no-sync` to use the existing database contents without syncing.
+
 ### All Options
 
 ```console
@@ -59,6 +61,7 @@ usage: manager-for-ynab reconciler [-h] [--mode {single,batch,interactive-batch}
                                    [--for-real]
                                    [--sqlite-export-for-ynab-db SQLITE_EXPORT_FOR_YNAB_DB]
                                    [--sqlite-export-for-ynab-full-refresh]
+                                   [--sync | --no-sync]
 
 Find and automatically reconciles unreconciled transactions.
 
@@ -86,4 +89,5 @@ options:
   --sqlite-export-for-ynab-full-refresh
                         Whether to **DROP ALL TABLES** and fetch all plan data again. If unset, this
                         tool only does an incremental refresh
+  --sync, --no-sync     Refresh the SQLite DB before using it.
 ```

manager_for_ynab/reconciler/__init__.py

@@ -156,6 +156,12 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Whether to **DROP ALL TABLES** and fetch all plan data again. If unset, this tool only does an incremental refresh",
     )
+    parser.add_argument(
+        "--sync",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Refresh the SQLite DB before using it.",
+    )
     return parser
 
 
@@ -172,6 +178,7 @@ async def run(
         for_real=args.for_real,
         db=args.sqlite_export_for_ynab_db,
         full_refresh=args.sqlite_export_for_ynab_full_refresh,
+        should_sync=args.sync,
         token_override=token_override,
     )
 
@@ -186,6 +193,7 @@ async def reconciler(
     for_real: bool,
     db: Path,
     full_refresh: bool,
+    should_sync: bool = True,
     token_override: str | None,
 ) -> int:
     target_set = await _resolve_target_set(
@@ -202,9 +210,10 @@ async def reconciler(
 
     token = resolve_token(token_override)
 
-    print("** Refreshing SQLite DB **")
-    await sync(token, db, full_refresh)
-    print("** Done **")
+    if should_sync:
+        print("** Refreshing SQLite DB **")
+        await sync(token, db, full_refresh)
+        print("** Done **")
 
     async with aiosqlite.connect(db) as con:
         con.row_factory = aiosqlite.Row

tests/add_transaction/test.py

@@ -203,6 +203,7 @@ async def test_run_delegates_parsed_args(add_transaction_mock):
             "--sqlite-export-for-ynab-db",
             "/tmp/db.sqlite",
             "--sqlite-export-for-ynab-full-refresh",
+            "--no-sync",
         )
     )
 
@@ -220,6 +221,7 @@ async def test_run_delegates_parsed_args(add_transaction_mock):
     assert kwargs["quiet"] is True
     assert kwargs["db"] == Path("/tmp/db.sqlite")
     assert kwargs["full_refresh"] is True
+    assert kwargs["should_sync"] is False
 
 
 @pytest.mark.parametrize(
@@ -275,6 +277,34 @@ async def test_add_transaction_dry_run(
     transactions_api_cls.assert_not_called()
 
 
+@patch("manager_for_ynab.add_transaction.sync", new_callable=AsyncMock)
+@pytest.mark.asyncio
+async def test_add_transaction_no_sync_uses_existing_db(sync_mock, tmp_path, capsys):
+    db_path = tmp_path / "add-transaction.sqlite"
+    _create_add_transaction_db(db_path)
+
+    ret = await add_transaction(
+        plan_name=None,
+        account_name="Checking",
+        payee_name="Employer",
+        category_name="Inflow: Ready to Assign",
+        date=date(2026, 4, 26),
+        cleared=None,
+        amount=Decimal("12.34"),
+        for_real=False,
+        quiet=False,
+        db=db_path,
+        full_refresh=False,
+        should_sync=False,
+        token_override="token",
+    )
+
+    out, _ = capsys.readouterr()
+    assert ret == 0
+    sync_mock.assert_not_awaited()
+    assert "** Refreshing SQLite DB **" not in out
+
+
 @patch(
     "manager_for_ynab.add_transaction._apply_category_budget_delta",
     new_callable=AsyncMock,

tests/auto_approve/test.py

@@ -246,6 +246,20 @@ async def test_run_quiet_suppresses_all_output(sync, db, capsys):
     assert out == ""
 
 
+@patch.dict("os.environ", {_ENV_TOKEN: "token"})
+@patch.object(ynab, "TransactionsApi", unexpected_transactions_api)
+@patch("manager_for_ynab.auto_approve.sync")
+@pytest.mark.asyncio
+async def test_run_no_sync_uses_existing_db(sync, db, capsys):
+    ret = await run(("--sqlite-export-for-ynab-db", str(db), "--no-sync"))
+
+    out, _ = capsys.readouterr()
+    assert ret == 0
+    sync.assert_not_called()
+    assert "** Refreshing SQLite DB **" not in out
+    assert "Found 3 transaction(s) to approve." in out
+
+
 @patch.dict("os.environ", {_ENV_TOKEN: "token"})
 @patch("manager_for_ynab.auto_approve.sync")
 @pytest.mark.asyncio