Connect Project

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 deeepCLI
• Authenticated with your deeepSpace account
• A Git repository with a remote on GitHub, GitLab, or Bitbucket
• 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 from the current repository.

Initialize the project

Navigate to your project’s root directory and run:

✨ Git repository required

deeep init must be run from inside a Git repository with an origin remote pointing to GitHub, GitLab, or Bitbucket.

deeep init

The command runs through four steps:

1. Choose a workspace — select the deeepSpace workspace to use.
2. Choose or create a project — link an existing project or create a new one from this repository.
3. Configure component discovery — choose between CLI discovery and Storybook discovery.
4. Review and save — confirm the configuration before deeep.json is written.

Create a new project

To skip the prompt and create a new deeepSpace project from the current repository:

deeep init --create

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

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

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

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.
• The repository must have an origin remote pointing to GitHub, GitLab, or Bitbucket.

Git provider connection required

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

Configuration errors

• Delete the existing deeep.json file.
• Run deeep init again.
• If issues persist, contact support@deeepspace.com for help.

Next steps

Now that your project is connected:

1. Sync components with deeepSpace
2. Learn how to manage your project settings