npm package: @gitsense/gscb-cli
Description: GitSense Chat Bridge (GSCB) Command Line Tool
Latest version: 0.5.5

<!--
 * Component: README
 * Block-UUID: 3ecb6d3e-7b3f-4209-8d21-d339fcfa3133
 * Parent-UUID: 01a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c
 * Version: 0.2.3
 * Description: Documentation for the GitSense Chat Bridge (GSCB) Command Line Tool.
 * Language: Markdown
 * Created-at: 2025-08-14T04:09:05.203Z
 * Authors: Original Author (v0.2.0), Gemini 2.5 Flash Thinking (v0.2.1), Gemini 2.5 Flash Thinking (v0.2.2), Gemini 2.5 Flash Thinking (v0.2.3)
-->


# GitSense Chat Bridge (GSCB) CLI

The GitSense Chat Bridge (GSCB) Command Line Interface is a tool designed to import various data sources, primarily Git repositories, into a GitSense Chat SQLite database. This allows the GitSense Chat application to leverage your code repositories for enhanced conversational AI capabilities.

## Table of Contents

*   [Installation](#installation)
*   [Usage](#usage)
    *   [Import Git Repository](#import-git-repository)
*   [Development](#development)
*   [Contributing](#contributing)
*   [License](#license)

## Installation

To install the GSCB CLI, ensure you have Node.js and npm (or yarn/pnpm) installed.

**Install via npm (Recommended for users):**

To install the CLI globally, run:

```bash
npm install -g @gitsense/gscb-cli
```

This will make the `gscb` command available directly in your terminal.

**Install from source (For contributors/developers):**

If you intend to contribute or develop the CLI, you can clone the repository and build it:

```bash
# Clone the repository
git clone https://github.com/gitsense/gscb-cli.git
cd gscb-cli

# Install dependencies
npm install

# Build the project
npm run build
```

After building, the `gscb` executable will be available in `dist/bin/gscb.js`.

## Usage

The GSCB CLI's primary function is to import data.

### Import Git Repository

The `import git` command allows you to import a Git repository into your GitSense Chat database. The command now uses positional arguments for a more streamlined experience, with the database path specified as an option.

**Current Version:** `0.5.0`

**Syntax:**

```bash
gscb import git <repo directory> <repo owner> <repo name> <branch> [options]
```

**Arguments:**

*   `<repo directory>`: The local path to the Git repository (e.g., `./my-repo`, `.` for current directory).
*   `<repo owner>`: The owner or organization name of the repository (e.g., `gitsense`).
*   `<repo name>`: The name of the repository (e.g., `gscb-cli`).
*   `<branch>`: The Git branch to import (e.g., `main`, `develop`). The `ref-type` is automatically set to `branch`.

**Options:**

*   `--db-path <path>`: The path to the GitSense Chat SQLite database file (e.g., `./test.db`). Defaults to `./data/chats.sqlite3` relative to the CLI executable.
*   `-s, --max-size <size>`: Maximum file size in KB to include in the import (default: `256`).
*   `-i, --include <pattern>`: Regular expression pattern to include specific files.
*   `-x, --exclude <pattern>`: Regular expression pattern to exclude specific files.
*   `-p, --prompt <name>`: Name of the system prompt to use for processing.
*   `--include-binary`: Include binary files in the import (by default, binary files are skipped).
*   `-v, --verbose`: Enable verbose logging for detailed output.

**Examples:**

1.  **Import a repository from the current directory:**
```bash
    gscb import git . gitsense gscb-cli main --db-path ./test.db
```

2.  **Import a specific repository with a custom max file size and verbose logging:**
```bash
    gscb import git /path/to/your/repo my-company my-project develop --db-path ./data/chat.db -s 512 -v
```

3.  **Import a repository, including binary files and excluding certain patterns:**
```bash
    gscb import git ./another-repo your-org awesome-app main --db-path ./db/app.sqlite --include-binary -x "node_modules|dist"
```

### List Imported Data

The `list` command allows you to view imported data, specifically Git repositories.

**Syntax:**

```bash
gscb list [type] [owner] [repoName] [options]
```

**Arguments:**

*   `[type]`: (Optional) The type of data to list. Currently, only `git` is supported. If omitted, available types will be listed.
*   `[owner]`: (Optional) Filter by repository owner. Only applicable when `type` is `git`.
*   `[repoName]`: (Optional) Filter by repository name. Only applicable when `type` is `git`.

**Options:**

*   `--db-path <path>`: Path to the GitSense Chat SQLite database. Defaults to `./data/chats.sqlite3` relative to the CLI executable.

**Examples:**

1.  **List all available data types:**
```bash
    gscb list
```

2.  **List all imported Git repositories:**
```bash
    gscb list git
```

3.  **List all imported Git repositories from a specific database path:**
```bash
    gscb list git --db-path ./my-custom-db.sqlite
```