Connect a Git Repository

After installing and authenticating the CLI, link your local Git repository to a deeepSpace project. This connection lets you sync your local components with your design system in deeepSpace.

Prerequisites

Before connecting, make sure you have:

Installed the deeep CLI
Authenticated with your deeepSpace account
A Git repository whose remote matches the repository connected to the selected project
A matching project in deeepSpace, or permission to create one

New to deeepSpace? If you haven’t created a project yet, visit app.deeepspace.com to create one, or use deeep init --create to create a project directly from the current repository.

Initialize the project

Navigate to your project’s root directory and run:

Run from the repository root: the CLI reads and writes deeep.json in the current directory. Creating a project requires an origin remote on GitHub, GitLab, or Bitbucket and the corresponding Git-provider connection in deeepSpace.

deeep init

The command runs through four steps:

Choose a workspace

Select the deeepSpace workspace to use.

Choose or create a project

Link an existing project or create a new one from this repository.

Configure component discovery

Choose between CLI discovery and Storybook discovery.

Review and save

Confirm the configuration before deeep.json is written.

After confirmation, init records your chosen discovery method on deeepSpace and attempts the first component sync. Prepare committed component sources and a named branch as described in Sync components. It then detects your tech stack and asks whether to update project settings. If indexing or syncing fails, the project configuration is saved so you can fix the issue and retry with deeep sync. Setup registration is separate from component sync: the Home tab can show the selected method even before a successful sync. If registration fails, local setup continues with a warning; use deeep init --force to retry setup for an initialized project.

Create a new project

To skip only the create/link selection prompt and create a new deeepSpace project from the current repository:

deeep init --create

--create still asks for the workspace, project name, optional description, discovery settings, and confirmation. A blank project name defaults to the repository directory name. Supported remote forms include https://github.com/owner/repo.git and git@github.com:owner/repo.git, with equivalent GitLab and Bitbucket URLs. Nested GitLab subgroup paths and ssh:// URLs are not supported by the current project-creation parser.

Reconnect to a different project

To change the linked project or update discovery settings:

deeep init --force

Component discovery

During initialization you choose how the CLI finds your components.

deeep CLI discovery

The CLI scans directories that contain component source files, for example:

src/components/**/*.{js,jsx,mjs,ts,tsx,vue}
packages/*/src/components/**/*.{js,jsx,mjs,ts,tsx,vue}

You can confirm, select, or manually enter the directories to scan.

Storybook discovery

If Storybook is detected, you can choose to use your Storybook stories and index.json instead. The CLI will ask for:

The .storybook configuration directory
The path to the generated Storybook index.json
The story file glob patterns
An optional deployed Storybook URL
Whether to host Storybook on deeep during sync

See Storybook discovery and hosting for monorepos, the required first build, and publishing behavior. Enabling hosting during init saves the preference; publishing runs on deeep sync.

Configuration file

After linking, the CLI creates a deeep.json file in your repository root. This file contains the project link, project settings, and discovery configuration.

{
  "project": {
    "name": "My Awesome Project",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "projectSettings": {
      "framework": "react",
      "language": "tsx",
      "styling": "tailwind",
      "styleMode": "external"
    },
    "gitRepoName": "my-org/my-awesome-project",
    "gitRepoUrl": "https://github.com/my-org/my-awesome-project",
    "version": 1
  },
  "discovery": {
    "type": "CLI",
    "componentIndexJsonPath": ".deeep.index.json",
    "components": [
      "src/components/**/*.{js,jsx,mjs,ts,tsx,vue}"
    ],
    "exclude": [
      "**/*.test.*",
      "**/*.spec.*",
      "**/*.stories.*",
      "**/node_modules/**",
      "**/dist/**",
      "**/build/**",
      "**/coverage/**"
    ]
  }
}

For a full reference of all available options, visit the Project Settings Reference page.

Check connection status

Verify your project connection:

deeep status

Example output:

Project Status
==================================================

Project Name: My Project
Workspace: Default Space

Project Settings
──────────────────────────────
Framework:   react
Styling:     tailwind
Language:    tsx
Style Mode:  external

Version Information
──────────────────────────────
Current Version: 1

==================================================

Remove the local link

To detach this repository from its deeepSpace project — for example before archiving or handing off a codebase — run:

deeep unlink

The command asks for confirmation, then deletes deeep.json and the generated component index (.deeep.index.json, or your configured componentIndexJsonPath) from the repository. Everything in deeepSpace stays intact: the project, its synced components, and the connected repository are untouched. Add --logout to also clear the stored credentials from the machine, and -y to skip the confirmation prompt.

To permanently delete the project or disconnect its repository, use the deeepspace web app. deeep unlink only cleans the local codebase — you can link the repository again at any time with deeep init.

Troubleshooting

Project not found

Verify you’re in the correct directory.
Check that you’re logged in with the correct account (deeep whoami).
Ensure the project exists in deeepSpace.

Git repository required

deeep init must be run from inside a Git repository.
Creating a project requires a supported origin remote. Syncing an existing project requires a local remote matching its connected repository name.

Git provider connection required

Connect your Git provider account in deeepSpace before linking a repository.

Configuration errors

For valid configuration that needs changes, run deeep init --force.
For malformed JSON, repair the file or back it up outside the repository before removing it and running deeep init again. Configuration is loaded before command handling, so --force cannot bypass invalid JSON. To remove the local link entirely, run deeep unlink instead of deleting the file by hand.
If issues persist, contact support@deeepspace.com for help.

Next steps

Now that your project is connected:

Sync components with deeepSpace
Learn how to manage your project settings

​Prerequisites

​Initialize the project

​Create a new project

​Reconnect to a different project

​Component discovery

​deeep CLI discovery

​Storybook discovery

​Configuration file

​Check connection status

​Remove the local link

​Troubleshooting

​Project not found

​Git repository required

​Git provider connection required

​Configuration errors

​Next steps

Prerequisites

Initialize the project

Create a new project

Reconnect to a different project

Component discovery

deeep CLI discovery

Storybook discovery

Configuration file

Check connection status

Remove the local link

Troubleshooting

Project not found

Git repository required

Git provider connection required

Configuration errors

Next steps