Skip to main content
driftless sync is an optional team-wide digest. You almost never need it, and never to start. Drift already reaches you as a freshness badge when you driftless context get the area you’re working on. Reach for sync only when you want to scan everything that moved at once. It does not inspect your local diff and it does not retrieve file-specific context. It pulls the repo memory state from Driftless Cloud and answers one question:
What changed around this repo’s topics since I last looked?

​
Command

CommandFlagsDescriptionExample
sync--jsonShow stale topics, recent PR activity, and tracked branchesdriftless sync
driftless sync
Typical output: 
▌ acme/platform
  workspace: acme  (resolved via config)
  tracking:  main, staging

⚠  2 topics drifted, the team changed code these topics cover, context may be behind:
   auth-boundaries
     src/auth/session.ts changed
     → review the change; if it changed how this works: driftless context update auth-boundaries --what "..." --how "..."

​
What sync checks

SignalSourceWhat to do
Stale topicsGitHub push events on tracked branchesReview the changed code and update the topic if the behavior changed
Recent PR activityGitHub App observationsRead the touched topics before working in the same area
Tracked branchesRepo settings in Driftless CloudUse driftless branches to see or change drift scope

​
When to use sync

The everyday loop doesn’t need sync. Go straight to retrieval, which carries the freshness badge inline: 
driftless context get --files "src/auth/session.ts,src/auth/token.ts"
Reach for sync only when you want the whole team-wide picture at once: 
driftless sync
If you already have local changes and want matching topics for the diff: 
driftless context get --diff

​
JSON output

Use --json when an agent or script needs structured output: 
driftless sync --json
The JSON output includes:
FieldMeaning
repoGitHub org/repo resolved from the current remote
workspaceDriftless workspace slug
trackingDefault branch and extra tracked branches
stale_topicsTopics whose anchored code changed
pr_activityRecent PR observations and touched topics

​
Branches

Staleness is scoped to tracked branches. If a push happens on an untracked branch, Driftless records the activity but does not mark topics stale from that branch.
CommandFlagsDescriptionExample
branches--jsonView tracked branchesdriftless branches
branches add<branch>Track a branchdriftless branches add staging
branches rm<branch>Stop tracking branchdriftless branches rm staging