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

# CLI Setup

> Install and configure the Sublay CLI

# Installing the Sublay CLI

The Sublay CLI copies fully customizable comment components directly into your project as editable source code. You can use it with `npx` (no installation required) or install it globally.

***

## Prerequisites

<Steps>
  <Step title="Node.js 20.5+">
    ```bash theme={null}
    node --version
    # Should output v20.5.0 or higher
    ```
  </Step>

  <Step title="A React, React Native, or Expo project">
    Supported platforms:

    * React (Web) ✅
    * React Native ✅
    * Expo ✅
  </Step>

  <Step title="A Sublay project">
    Create a project in the [Sublay Dashboard](https://dash.sublay.io) if you haven't already.
  </Step>
</Steps>

***

## Using npx (Recommended)

No installation required — `npx` always uses the latest version:

```bash theme={null}
npx @sublay/cli init
```

***

## Global Installation (Optional)

```bash theme={null}
npm install -g @sublay/cli
```

Then use without `npx`:

```bash theme={null}
sublay init
sublay add comments-threaded --ref v8
```

<Note>
  The rest of this documentation uses `npx @sublay/cli` to stay version-agnostic, but `sublay` works identically when installed globally.
</Note>

***

## Initializing Your Project

Run the init command from your project root:

```bash theme={null}
cd your-react-app
npx @sublay/cli init
```

### Interactive Prompts

<AccordionGroup>
  <Accordion title="Platform Selection" icon="layer-group">
    **Question:** "Which platform are you using?"

    **Options:** React (Web) · React Native · Expo

    Determines which component variants and dependencies are used.
  </Accordion>

  <Accordion title="Styling Preference" icon="palette">
    **Question:** "Which styling approach do you prefer?"

    **Options:**

    * **Tailwind CSS** — Uses utility classes (`bg-white dark:bg-gray-800`)
    * **Inline Styles** — Uses style objects (`style={{ backgroundColor: '...' }}`)

    Choose **Tailwind** if your project already uses Tailwind CSS. Otherwise choose **Inline Styles**.
  </Accordion>

  <Accordion title="Component Path" icon="folder">
    **Question:** "Where should components be installed?"

    **Default:** `src/components`

    The directory where CLI components will be copied. You can use any path.
  </Accordion>
</AccordionGroup>

***

## What Happens During Init

1. **Detects your project type** from `package.json`
2. **Creates `sublay.json`** in your project root
3. **Checks for required peer dependencies** and offers to install missing ones

***

## The sublay.json File

After initialization, a `sublay.json` file is created in your project root:

```json theme={null}
{
  "platform": "react",
  "style": "tailwind",
  "typescript": true,
  "paths": {
    "components": "src/components"
  },
  "aliases": {
    "@/components": "./src/components"
  }
}
```

See [Configuration](/v8/components/installation/configuration) for a full reference.

***

## Adding Components

```bash theme={null}
npx @sublay/cli add <component> --ref v8
```

| Option | Description |
| - | - |
| `--ref <branch>` | The branch of the component registry to read from. Without it, `add` reads the default branch. The v8 components are on the `v8` branch, so every `add` command in this documentation uses `--ref v8`. |
| `--lang <code>` | The language of the component's text. Without it, the component is installed in English. See [Languages & Right-to-Left](/v8/components/customization/languages-rtl) for the available codes. |

`add` reads `sublay.json`, then:

1. **Downloads the component** for your platform and style from the chosen branch.
2. **Downloads the shared pieces** the component is built from (the GIF picker, avatar, skeletons, icons and similar) into a `shared/` folder inside the component's own folder.
3. **Writes the files** to `{paths.components}/<component>/`, with imports adjusted to the installed layout. If any file fails to download, nothing is written.
4. **Checks your `package.json`** for the packages the component and its shared pieces need, and offers to install the missing ones.

A branch name may contain letters, digits, `.`, `_`, `-` and `/`. If the branch or the component does not exist on it, `add` stops with a message naming the one that is missing and writes nothing.

Every installed file is yours to edit, the files in `shared/` included. Each component gets its own `shared/` folder.

***

## Installing Dependencies

`add` checks for the packages a component needs and prompts to install them if missing. The Sublay SDK for your platform is always one of them:

**React (Web):**

```bash theme={null}
npm install @sublay/react-js
```

**React Native:**

```bash theme={null}
npm install @sublay/react-native
```

**Expo:**

```bash theme={null}
npm install @sublay/expo
```

<Warning>
  These packages are **required**. Components use them for data fetching, authentication, real-time updates, and core functionality.
</Warning>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Warning: No package.json found" icon="folder-xmark">
    ```
    ⚠️  No package.json found
    ```

    After installing a component's files, `add` reads your `package.json` to
    check which of the component's dependencies you already have. If there is
    no `package.json` in the current directory it prints this warning and skips
    that check — the component itself is still installed, and the command still
    succeeds.

    Run `add` from your project root (where `package.json` lives) to get the
    dependency check.
  </Accordion>

  <Accordion title="CLI hangs or doesn't respond" icon="hourglass">
    1. Press `Ctrl+C` to cancel
    2. Clear npx cache: `npx clear-npx-cache`
    3. Try again: `npx @sublay/cli init`
  </Accordion>

  <Accordion title="Want to change configuration" icon="gear">
    Delete `sublay.json` and run `npx @sublay/cli init` again, or manually edit the file and re-run `add` commands.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/v8/components/installation/quick-start">
    Add your first component in under 5 minutes
  </Card>

  <Card title="Configuration Reference" icon="file-code" href="/v8/components/installation/configuration">
    Understand every option in sublay.json
  </Card>

  <Card title="Threaded Comments" icon="comments" href="/v8/components/components/threaded/installation">
    Add Reddit-style threaded comments
  </Card>

  <Card title="Social Comments" icon="heart" href="/v8/components/components/social/installation">
    Add Instagram-style social comments
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.