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, authenticate, and connect your project.
  • 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.

​
Inspect discovery before uploading

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.
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.

​
Sync your components

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 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.
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.

​
Storybook hosting controls

These flags override discovery.hostStorybook for the current run. A hosting failure does not roll back a successful component sync. See the hosting workflow 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

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.