> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trybrein.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync

> An optional team-wide digest of what drifted around your topics.

`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

| Command | Flags    | Description                                      | Example          |
| ------- | -------- | ------------------------------------------------ | ---------------- |
| `sync`  | `--json` | Show persisted stale topics and suggested topics | `driftless sync` |

```bash theme={"theme":"github-light"}
driftless sync
```

Typical output:

```text theme={"theme":"github-light"}
▌ acme/platform
  workspace: acme  (resolved via config)
⚠  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

| Signal               | Source                                     | What to do                                                           |
| -------------------- | ------------------------------------------ | -------------------------------------------------------------------- |
| **Stale topics**     | Explicit local `context get --diff --mark` | Review the changed code and update the topic if the behavior changed |
| **Suggested topics** | Pending suggestions                        | Review and confirm useful context                                    |

## When to use sync

The everyday loop doesn't need `sync`. Go straight to retrieval, which carries the freshness badge inline:

```bash theme={"theme":"github-light"}
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:

```bash theme={"theme":"github-light"}
driftless sync
```

If you already have local changes and want matching topics for the diff:

```bash theme={"theme":"github-light"}
driftless context get --diff
```

## JSON output

Use `--json` when an agent or script needs structured output:

```bash theme={"theme":"github-light"}
driftless sync --json
```

The JSON output includes:

| Field               | Meaning                                              |
| ------------------- | ---------------------------------------------------- |
| `repo`              | Repository identity resolved from the current remote |
| `workspace`         | Driftless workspace slug                             |
| `stale_topics`      | Topics whose anchored code changed                   |
| `suggested_pending` | Number of suggested topics awaiting review           |