← back to Cli Printing Press

docs(cli): document sync --resources parent-keyed dependent cascade (#1417)

d4b173d6888aa671aca992fc7fc92244af6b8f3b · 2026-05-14 21:48:18 -0700 · Trevin Chow

* docs(cli): document sync --resources parent-keyed dependent cascade

The generated `sync --resources <list>` flag silently cascades from each
named parent to its parent-keyed dependent resources, but the flag's
short help only said "Comma-separated resource types to sync". Users
hitting parent-cascade for the first time on a rate-limited API saw
syncs run far longer than expected and reported it as a bug.

Document the contract on both surfaces of the generated `sync` command:

- The `--resources` flag's short description now warns that naming a
  parent also runs its parent-keyed dependents and points to the Long
  help for scoping.
- A new "Resource scoping:" section in the Long help explains the
  cascade rule, the "sync this parent and its children" use case it
  enables, and the current limitation (no flag suppresses cascade for
  a named parent; explicit dependent naming is the workaround).

Behavior is unchanged. The fix is template-only; the cascade logic in
syncDependentResources already implements what the new docs describe.

Closes #1141

* docs(cli): switch "flat resources" to "top-level resources" in sync help

Greptile flagged "flat resources" as undefined jargon for first-time
readers (the cascade-section's target audience). Use "top-level
resources" instead, matching common cobra-tree language and avoiding
the internal flat/dependent taxonomy.

Files touched

• M internal/generator/templates/sync.go.tmpl
• M testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/sync.go
• M testdata/golden/expected/generate-sync-walker-api/sync-walker-golden/internal/cli/sync.go
• M testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/sync.go

Diff

commit d4b173d6888aa671aca992fc7fc92244af6b8f3b
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Thu May 14 21:48:18 2026 -0700

    docs(cli): document sync --resources parent-keyed dependent cascade (#1417)
    
    * docs(cli): document sync --resources parent-keyed dependent cascade
    
    The generated `sync --resources <list>` flag silently cascades from each
    named parent to its parent-keyed dependent resources, but the flag's
    short help only said "Comma-separated resource types to sync". Users
    hitting parent-cascade for the first time on a rate-limited API saw
    syncs run far longer than expected and reported it as a bug.
    
    Document the contract on both surfaces of the generated `sync` command:
    
    - The `--resources` flag's short description now warns that naming a
      parent also runs its parent-keyed dependents and points to the Long
      help for scoping.
    - A new "Resource scoping:" section in the Long help explains the
      cascade rule, the "sync this parent and its children" use case it
      enables, and the current limitation (no flag suppresses cascade for
      a named parent; explicit dependent naming is the workaround).
    
    Behavior is unchanged. The fix is template-only; the cascade logic in
    syncDependentResources already implements what the new docs describe.
    
    Closes #1141
    
    * docs(cli): switch "flat resources" to "top-level resources" in sync help
    
    Greptile flagged "flat resources" as undefined jargon for first-time
    readers (the cascade-section's target audience). Use "top-level
    resources" instead, matching common cobra-tree language and avoiding
    the internal flat/dependent taxonomy.
---
 internal/generator/templates/sync.go.tmpl                  | 14 ++++++++++++--
 .../printing-press-golden/internal/cli/sync.go             | 14 ++++++++++++--
 .../sync-walker-golden/internal/cli/sync.go                | 14 ++++++++++++--
 .../tier-routing-golden/internal/cli/sync.go               | 14 ++++++++++++--
 4 files changed, 48 insertions(+), 8 deletions(-)

diff --git a/internal/generator/templates/sync.go.tmpl b/internal/generator/templates/sync.go.tmpl
index 5b07104a..2faf3001 100644
--- a/internal/generator/templates/sync.go.tmpl
+++ b/internal/generator/templates/sync.go.tmpl
@@ -90,7 +90,17 @@ Exit codes & warnings:
   emit {"event":"sync_warning","reason":"exit_policy_default_changed",
   ...} so callers can detect that a partial failure was tolerated. Pass
   --strict to exit non-zero on any per-resource failure. Exit is always
-  non-zero when every selected resource failed, regardless of --strict.`,
+  non-zero when every selected resource failed, regardless of --strict.
+
+Resource scoping:
+  --resources runs the named top-level resources, plus any parent-keyed
+  dependent whose own name is listed OR whose parent table is listed.
+  Naming a parent therefore cascades to its dependents (so "sync this
+  parent and its children" works without listing every nested resource
+  by hand). There is no flag today to suppress the cascade for a named
+  parent. To run a dependent without re-syncing its parent, list only
+  the dependent by name; the parent table must already be populated
+  from a prior sync.`,
 		Example: `  # Sync all resources
   {{.Name}}-pp-cli sync
 
@@ -345,7 +355,7 @@ Exit codes & warnings:
 		},
 	}
 
-	cmd.Flags().StringSliceVar(&resources, "resources", nil, "Comma-separated resource types to sync")
+	cmd.Flags().StringSliceVar(&resources, "resources", nil, "Comma-separated resource types to sync. Naming a parent also runs its parent-keyed dependents (see Long help for scoping).")
 	cmd.Flags().BoolVar(&full, "full", false, "Full resync (ignore previous checkpoint)")
 	cmd.Flags().StringVar(&since, "since", "", "Incremental sync duration (e.g. 7d, 24h, 1w, 30m)")
 	cmd.Flags().IntVar(&concurrency, "concurrency", 4, "Number of parallel sync workers")
diff --git a/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/sync.go b/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/sync.go
index dff2772c..ed2ab002 100644
--- a/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/sync.go
+++ b/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/sync.go
@@ -67,7 +67,17 @@ Exit codes & warnings:
   emit {"event":"sync_warning","reason":"exit_policy_default_changed",
   ...} so callers can detect that a partial failure was tolerated. Pass
   --strict to exit non-zero on any per-resource failure. Exit is always
-  non-zero when every selected resource failed, regardless of --strict.`,
+  non-zero when every selected resource failed, regardless of --strict.
+
+Resource scoping:
+  --resources runs the named top-level resources, plus any parent-keyed
+  dependent whose own name is listed OR whose parent table is listed.
+  Naming a parent therefore cascades to its dependents (so "sync this
+  parent and its children" works without listing every nested resource
+  by hand). There is no flag today to suppress the cascade for a named
+  parent. To run a dependent without re-syncing its parent, list only
+  the dependent by name; the parent table must already be populated
+  from a prior sync.`,
 		Example: `  # Sync all resources
   printing-press-golden-pp-cli sync
 
@@ -307,7 +317,7 @@ Exit codes & warnings:
 		},
 	}
 
-	cmd.Flags().StringSliceVar(&resources, "resources", nil, "Comma-separated resource types to sync")
+	cmd.Flags().StringSliceVar(&resources, "resources", nil, "Comma-separated resource types to sync. Naming a parent also runs its parent-keyed dependents (see Long help for scoping).")
 	cmd.Flags().BoolVar(&full, "full", false, "Full resync (ignore previous checkpoint)")
 	cmd.Flags().StringVar(&since, "since", "", "Incremental sync duration (e.g. 7d, 24h, 1w, 30m)")
 	cmd.Flags().IntVar(&concurrency, "concurrency", 4, "Number of parallel sync workers")
diff --git a/testdata/golden/expected/generate-sync-walker-api/sync-walker-golden/internal/cli/sync.go b/testdata/golden/expected/generate-sync-walker-api/sync-walker-golden/internal/cli/sync.go
index 19f0b86c..b2fff506 100644
--- a/testdata/golden/expected/generate-sync-walker-api/sync-walker-golden/internal/cli/sync.go
+++ b/testdata/golden/expected/generate-sync-walker-api/sync-walker-golden/internal/cli/sync.go
@@ -67,7 +67,17 @@ Exit codes & warnings:
   emit {"event":"sync_warning","reason":"exit_policy_default_changed",
   ...} so callers can detect that a partial failure was tolerated. Pass
   --strict to exit non-zero on any per-resource failure. Exit is always
-  non-zero when every selected resource failed, regardless of --strict.`,
+  non-zero when every selected resource failed, regardless of --strict.
+
+Resource scoping:
+  --resources runs the named top-level resources, plus any parent-keyed
+  dependent whose own name is listed OR whose parent table is listed.
+  Naming a parent therefore cascades to its dependents (so "sync this
+  parent and its children" works without listing every nested resource
+  by hand). There is no flag today to suppress the cascade for a named
+  parent. To run a dependent without re-syncing its parent, list only
+  the dependent by name; the parent table must already be populated
+  from a prior sync.`,
 		Example: `  # Sync all resources
   sync-walker-golden-pp-cli sync
 
@@ -307,7 +317,7 @@ Exit codes & warnings:
 		},
 	}
 
-	cmd.Flags().StringSliceVar(&resources, "resources", nil, "Comma-separated resource types to sync")
+	cmd.Flags().StringSliceVar(&resources, "resources", nil, "Comma-separated resource types to sync. Naming a parent also runs its parent-keyed dependents (see Long help for scoping).")
 	cmd.Flags().BoolVar(&full, "full", false, "Full resync (ignore previous checkpoint)")
 	cmd.Flags().StringVar(&since, "since", "", "Incremental sync duration (e.g. 7d, 24h, 1w, 30m)")
 	cmd.Flags().IntVar(&concurrency, "concurrency", 4, "Number of parallel sync workers")
diff --git a/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/sync.go b/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/sync.go
index d1ba5f4b..00ac7fa5 100644
--- a/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/sync.go
+++ b/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/sync.go
@@ -68,7 +68,17 @@ Exit codes & warnings:
   emit {"event":"sync_warning","reason":"exit_policy_default_changed",
   ...} so callers can detect that a partial failure was tolerated. Pass
   --strict to exit non-zero on any per-resource failure. Exit is always
-  non-zero when every selected resource failed, regardless of --strict.`,
+  non-zero when every selected resource failed, regardless of --strict.
+
+Resource scoping:
+  --resources runs the named top-level resources, plus any parent-keyed
+  dependent whose own name is listed OR whose parent table is listed.
+  Naming a parent therefore cascades to its dependents (so "sync this
+  parent and its children" works without listing every nested resource
+  by hand). There is no flag today to suppress the cascade for a named
+  parent. To run a dependent without re-syncing its parent, list only
+  the dependent by name; the parent table must already be populated
+  from a prior sync.`,
 		Example: `  # Sync all resources
   tier-routing-golden-pp-cli sync
 
@@ -281,7 +291,7 @@ Exit codes & warnings:
 		},
 	}
 
-	cmd.Flags().StringSliceVar(&resources, "resources", nil, "Comma-separated resource types to sync")
+	cmd.Flags().StringSliceVar(&resources, "resources", nil, "Comma-separated resource types to sync. Naming a parent also runs its parent-keyed dependents (see Long help for scoping).")
 	cmd.Flags().BoolVar(&full, "full", false, "Full resync (ignore previous checkpoint)")
 	cmd.Flags().StringVar(&since, "since", "", "Incremental sync duration (e.g. 7d, 24h, 1w, 30m)")
 	cmd.Flags().IntVar(&concurrency, "concurrency", 4, "Number of parallel sync workers")

← f32214ea feat(cli): surface per-endpoint evidence and confidence from  ·  back to Cli Printing Press  ·  fix(cli): handle single-quoted args in validate-narrative sh 33a6668b →