From eceee6ec026460a5482409227532703465c6e6c1 Mon Sep 17 00:00:00 2001
From: ergosteur <ergosteur@1qaz.ca>
Date: Wed, 26 Aug 2026 20:45:46 -0400
Subject: [PATCH] docs: add worked --help examples to gdl-sync.py

One example per way of selecting what to fetch (urls-file, --profile,
--all, --post-url), plus the routine/stories/full-sweep pacing choices,
so the flags don't have to be reverse-engineered from the arg list.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011qAds5qr7nZRq5R4yAuxUk
---
 scripts/gdl-sync.py | 60 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 59 insertions(+), 1 deletion(-)

diff --git a/scripts/gdl-sync.py b/scripts/gdl-sync.py
index 38288a4..46d670f 100755
--- a/scripts/gdl-sync.py
+++ b/scripts/gdl-sync.py
@@ -23,10 +23,68 @@ the one that would touch the archive.
 
 Run it from the host whose public IP matches the browser the cookie came from;
 using the cookie from elsewhere is what session-hijack detection looks for.
+
+See `--help` for every flag, with worked examples for each way of selecting
+what to fetch.
 """
 
 from __future__ import annotations
 
+EXAMPLES = """\
+examples:
+
+  Routine incremental sync of the tracked profiles (what gdl-cron.sh runs) --
+  --abort 50 stops enumerating each profile once it reaches content already
+  held, so a run that has seeded once costs ~40-60 requests, not a full walk:
+
+    ./scripts/gdl-sync.py --index https://instaarchive.ergosteur.com \\
+        --staging /var/tmp/gdl --publish user@host:/path/to/archives \\
+        --urls-file artms_account_links.txt --archive-db /var/tmp/gdl.db \\
+        --abort 50 --dry-run
+    # ...then swap --dry-run for --execute once the plan looks right.
+
+  Cheapest possible run -- stories only, the one surface that expires in 24h
+  and cannot be backfilled, so it is worth doing often:
+
+    ./scripts/gdl-sync.py --index https://instaarchive.ergosteur.com \\
+        --staging /var/tmp/gdl --publish user@host:/path/to/archives \\
+        --urls-file artms_account_links.txt --only stories --execute
+
+  One profile, by name, without a urls-file:
+
+    ./scripts/gdl-sync.py --index /path/to/archives --staging /var/tmp/gdl \\
+        --publish /path/to/archives --profile some_account --execute
+
+  Every profile the archive already knows about (no urls-file, no --profile):
+
+    ./scripts/gdl-sync.py --index /path/to/archives --staging /var/tmp/gdl \\
+        --publish /path/to/archives --all --execute
+
+  An arbitrary single post or reel from an account NOT otherwise tracked --
+  e.g. a link someone shared. Filed under its owner like any other post; no
+  --index needed, since there is no profile list to plan against:
+
+    ./scripts/gdl-sync.py --staging /var/tmp/gdl --publish user@host:/path \\
+        --post-url https://www.instagram.com/p/SHORTCODE/ --execute
+
+  Full sweep -- no --abort, walks every profile to the end. The only run that
+  notices a carousel edited after it was archived, and by far the most
+  expensive thing here (~420 requests for six profiles). Read docs/gallery-dl.md
+  and TOOLING.md before running this one:
+
+    ./scripts/gdl-sync.py --index https://instaarchive.ergosteur.com \\
+        --staging /var/tmp/gdl --publish user@host:/path/to/archives \\
+        --urls-file artms_account_links.txt --execute
+
+  Hand-paced caution after a scraping warning (roughly double the defaults;
+  see docs/gallery-dl.md for where these numbers come from):
+
+    ./scripts/gdl-sync.py ... --sleep-request 12 20 --sleep 5 10 --rate 500K
+
+Always --dry-run first (the default): it prints the plan and the rsync
+command that would publish, without spending a single Instagram request.
+"""
+
 import argparse
 import datetime as dt
 import json
@@ -703,7 +761,7 @@ def main() -> int:
     sys.stdout.reconfigure(line_buffering=True)
     sys.stderr.reconfigure(line_buffering=True)
 
-    ap = argparse.ArgumentParser(description=__doc__,
+    ap = argparse.ArgumentParser(description=__doc__, epilog=EXAMPLES,
                                  formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("--index",
                     help="existing archive listing: a local root, or the "