How to Use the diff Command Modes

Overview

supaforge diff is the unified drift-detection and resolution command. It replaces the old separate scan and promote commands. The mode is controlled by flags:

• No flags — summary: lists which checks drifted and how many issues each has.
• --detail — detail: shows the full SQL for every drift issue.
• --apply — apply: executes the SQL and API calls to fix drift in the target environment.

Mode 1 — Summary (Default)

Running supaforge diff without extra flags gives you a quick overview of what changed. It's fast and noise-free — ideal for a first look or a CI health check:

supaforge diff

Example output:

  Diff: staging → production

  ✓ schema          clean
  ✗ rls             3 issues  (2 critical, 1 warning)
  ✓ auth            clean
  ○ storage         skipped
  ✗ cron            1 issue   (warning)

  Score: 72 / 100  —  4 issues (2 critical, 2 warning)

  → Run with --detail to see SQL diffs
  → Run with --apply to fix drift

  tip: Add --detail to see the full SQL for each issue.

After the result, a dim tip: line shows the most useful next action based on what was found. These contextual tips rotate to show different suggestions over time.

Summary mode exits with code 1 if any critical drift is found, making it safe to use as a CI gate.

Mode 2 — Detail (--detail)

Add --detail to see the exact SQL statements that would be applied to the target environment. This is the review step before you decide to apply:

supaforge diff --detail

Example output for an RLS drift issue:

  [rls] ✗ CRITICAL: missing policy "Users can read own data" on table "profiles"

  UP:
    CREATE POLICY "Users can read own data"
      ON public.profiles
      FOR SELECT
      USING (auth.uid() = id);

  DOWN:
    DROP POLICY "Users can read own data" ON public.profiles;

  tip: Run supaforge diff --apply to execute all the SQL fixes above.

You can combine --detail with --check to focus on a single check layer:

supaforge diff --check=rls --detail

Mode 3 — Apply (--apply)

Add --apply to execute all the fixes. SupaForge will scan first, then apply each SQL statement and API call to the target environment:

supaforge diff --apply

Example output:

  Scanning for drift...

  ✓ Applied 3 fix(es):
    ✓ [rls] missing-policy:profiles:Users can read own data
    ✓ [rls] missing-policy:orders:Admins can update orders
    ✓ [cron] missing-job:nightly-cleanup

  tip: Re-run supaforge diff to verify everything is clean.

Apply mode is idempotent — running it twice is safe. The second run will find no drift and exit cleanly.

To apply only a specific check:

supaforge diff --check=rls --apply

supaforge sync — Shorthand for --apply

supaforge sync is an alias for supaforge diff --apply. It detects and fixes drift in a single step with a shorter command:

supaforge sync

sync accepts all the same flags as diff — you can pass--check, --skip, --source, --target, and --json:

supaforge sync --source=staging --target=production

supaforge hukam — Cultural Alias

supaforge hukam is a full alias for supaforge diff. It accepts all the same flags — --detail, --apply, --check, etc. — and produces identical output:

supaforge hukam

supaforge hukam --detail

hukam (ਹੁਕਮ) is a Punjabi word meaning "command" or "order" — a nod to the Sikh tradition of taking a daily hukamnama. It's hidden from--help but works exactly like diff.

Choosing the Right Mode

• CI check — use summary mode (supaforge diff). Exit code 1 on critical drift fails the pipeline.
• Before deploying — use detail mode (supaforge diff --detail) to review every SQL statement before applying.
• After reviewing — use apply mode (supaforge diff --apply) or the supaforge sync shorthand to execute.
• Focused change — combine --check with any mode to limit the scope to a single check layer.

The Tip System

After every command, a dim tip: line shows the most relevant next action. The tips are contextual — they change based on what was found:

• Drift in summary mode → suggests --detail or --apply.
• Drift in detail mode → suggests running --apply to fix it.
• After a successful apply → suggests running supaforge diff to verify, or supaforge snapshot to lock in the clean state.
• Clean environments → suggests snapshotting or wiring into CI.

The tip system rotates through a small pool of suggestions so you see different hints across runs, helping you discover features organically.

Install

npm i -g @akalforge/supaforge

Summary

supaforge diff replaces the old scan and promotecommands in a single unified surface. Use the default summary for CI and quick checks,--detail to review SQL before applying, and --apply (orsupaforge sync) to fix drift. After every run, a contextual tip points you to the most useful next step.