---
title: "Component & Token Sync"
sidebarTitle: "Sync Components"
description: "Scan local components, preview detected changes with dry runs, and sync component manifests and design tokens to deeepSpace with Git commit tracking."
keywords: "deeep sync, component discovery dry run, design token sync"
icon: "refresh-cw"
---

Run `deeep sync` from the root of your linked Git repository to rebuild the local component index and send a component manifest to deeepSpace.

## Before you begin

- [Install the CLI](/guides/installation), [authenticate](/guides/authentication), and [connect your project](/guides/connect).
- Check out a named branch with at least one commit. Detached HEAD is not supported for uploads.
- Make sure a local Git remote matches the linked project's repository name.
- Commit the component entry files, discovered local source dependencies, styles, and Storybook story files. Both staged and unstaged changes to these files block uploads; unrelated working-tree changes do not.
- Push that commit to your connected Git provider so deeepSpace can access the referenced revision. The CLI does not push Git commits or verify that HEAD has been pushed.
- For Storybook discovery, build an up-to-date local Storybook index first. See [Storybook discovery and hosting](/guides/storybook).

## Inspect discovery before uploading

```bash
deeep sync --dry-run
```

This writes the component index to `discovery.componentIndexJsonPath` (default `.deeep.index.json`). Inspect its `summary`, `entries`, and `diagnostics` to check what was found.

Dry-run still requires authentication, a linked project with `gitRepoName`, and a valid discovery mode. It does not upload components, update remote stack settings, or build or host Storybook, even with `--storybook-hosting`.

<Note>
Dry-run validates discovery, not upload readiness. It skips remote matching, branch/commit checks, committed-file checks, the 1,000-component upload limit, and the empty-manifest guard. A successful dry-run can still be followed by a failed upload.
</Note>

## Sync your components

```bash
deeep sync
```

The CLI:

1. Rebuilds the index using CLI directory discovery or the local Storybook index.
2. Checks the linked repository, branch, commit, component count, and committed source files.
3. Sends a manifest identifying the project, discovery method, branch, commit SHA, components, and content hashes.
4. Requires a `COMPLETED` response and prints created, updated, and unchanged counts.
5. Detects your tech stack and asks whether to update project settings if they differ.
6. Builds and publishes Storybook if hosting is enabled and no existing URL causes it to skip.
7. Builds your components for [design comparison](/guides/compare) and uploads the build privately.

The manifest contains file paths, exports, package declarations, hashes, and applicable Storybook metadata. It does not upload raw component source files. Storybook hosting separately uploads the static build. See [Component index and sync data](/reference/component-index).

<Warning>
Sync sends the complete discovered component set, not only newly added files. Narrowing discovery can omit previously synced components. An empty manifest is blocked to prevent deactivating all existing components accidentally; inspect dry-run results before changing discovery scope.
</Warning>

## Storybook hosting controls

```bash
# Build and publish, including when a Storybook URL is already saved
deeep sync --storybook-hosting

# Sync components without hosting this time
deeep sync --no-storybook-hosting
```

These flags override `discovery.hostStorybook` for the current run. A hosting failure does not roll back a successful component sync. See the [hosting workflow](/guides/storybook) for first-build requirements and republishing.

## Daily workflow

1. Develop your components and stories.
2. Run `deeep sync --dry-run` and review diagnostics.
3. Commit and push the relevant source files.
4. Rebuild Storybook if using Storybook discovery.
5. Run `deeep sync`, or `deeep sync --storybook-hosting` to refresh the hosted build.
6. Review the components in deeepSpace. The project's Home tab shows the registered discovery method and latest reported sync status.

## Troubleshooting

| Message or symptom | What to do |
| --- | --- |
| Authentication required | Run `deeep auth`. |
| No project linked / discovery configuration missing | Run `deeep init`, or `deeep init --force` for an existing setup. |
| Connected repository required | Connect the project to its Git repository in deeepSpace, then reinitialize locally. |
| No matching Git remote | Select the project connected to this repository or correct your local remote. |
| Detached HEAD / HEAD cannot resolve | Check out a named branch and create the repository's first commit if needed. |
| Untracked / changed component files | Commit the listed files, including dependencies, styles, and stories, then push and retry. |
| No components discovered | Review patterns and index diagnostics. For Storybook, build the local index before syncing. |
| More than 1,000 components | Review discovery scope and split the component set across appropriate projects. Consider previously synced components before changing scope. |
| Index contains warnings or errors | Inspect `.deeep.index.json`; these diagnostics do not always stop the command. |
| Storybook hosting failed | Component sync has already completed. Fix the build or upload issue and rerun with `--storybook-hosting`. |

The current CLI does not consistently return a nonzero process exit code for command-level failures. For automation, inspect command output and remote sync results; do not treat exit code zero alone as confirmation of sync or hosting success. Initialization and stack updates can also prompt interactively.