# Console Script: `chroma-client`

This document describes the usage of the `chroma-client` console script, which provides a command-line interface for interacting directly with a ChromaDB instance for automation tasks, primarily codebase indexing and querying.

## Installation

To use this script, you need to install the `chroma-mcp-server` package with the `client` extra dependencies:

```bash
pip install "chroma-mcp-server[client]"
```

Alternatively, if managing the project with `hatch`, ensure the `client` feature or necessary dependencies are included in your environment.

## Configuration

The `chroma-client` script relies on a `.env` file located in the root of your project directory (or the directory where you run the command) to configure the connection to ChromaDB. Key variables include:

- `CHROMA_CLIENT_TYPE`: (`persistent`, `http`, `cloud`)
- `CHROMA_DATA_DIR`: (Required for `persistent`)
- `CHROMA_HOST`, `CHROMA_PORT`, `CHROMA_SSL`, `CHROMA_HEADERS`: (Used for `http`)
- `CHROMA_TENANT`, `CHROMA_DATABASE`, `CHROMA_API_KEY`: (Used for `cloud`)
- `CHROMA_EMBEDDING_FUNCTION`: (Optional, defaults to `default`)

Refer to the main project documentation for detailed `.env` configuration options.

## Usage

```bash
chroma-client [OPTIONS] COMMAND [ARGS]...
```

### Global Options

- `-h`, `--help`: Show the help message and exit.
- `-v, --verbose`: Increase output verbosity. Use `-v` for INFO level, `-vv` for DEBUG level. Defaults to INFO.

### Commands

#### `index`

Index specific files, directories (recursively), or all git-tracked files into ChromaDB.

```bash
chroma-client index [OPTIONS] [PATHS...]
```

**Arguments:**

- `PATHS...`: Optional specific file or directory paths to index. If directories are provided, they will be indexed recursively.

**Options:**

- `--repo-root PATH`: Path to the Git repository root (default: current directory). Used to determine relative file paths for document IDs.
- `--all`: Index all files tracked by Git in the specified repository.
- `--collection-name NAME`: Specify the ChromaDB collection name (default: `codebase_v1`).

**Examples:**

```bash
# Index a specific file
chroma-client index ./src/my_module.py --repo-root .

# Index all files tracked by git in the current repo
chroma-client index --all

# Index files in a specific directory recursively, using a custom collection
chroma-client index ./docs --collection-name project_docs --repo-root .
```

#### `count`

Count documents in a ChromaDB collection.

```bash
chroma-client count [OPTIONS]
```

**Options:**

- `--collection-name NAME`: Name of the ChromaDB collection to count. Default: `codebase_v1`.

**Example:**

```bash
chroma-client count --collection-name codebase_v1
```

#### `query`

Query a ChromaDB collection using semantic search.

```bash
chroma-client query [OPTIONS] QUERY_TEXT
```

**Arguments:**

- `QUERY_TEXT`: The natural language text to query for.

**Options:**

- `--collection-name NAME`: Name of the ChromaDB collection to query. Default: `codebase_v1`.
- `-n, --n-results N`: Number of results to return. Default: `5`.

**Example:**

```bash
chroma-client query "how to handle database connection errors" -n 3
```

#### `analyze-chat-history`

Analyzes recent chat history entries (from a specified collection, typically `chat_history_v1`) to correlate recorded AI suggestions/responses with actual Git changes made to mentioned files within a specified repository.

```bash
chroma-client analyze-chat-history [OPTIONS]
```

**Options:**

- `--collection-name NAME`: Name of the ChromaDB chat history collection. Default: `chat_history_v1`.
- `--repo-path PATH`: Path to the Git repository to analyze for code changes. Default: Current working directory.
- `--status-filter STATUS`: Metadata status value to filter entries for analysis. Default: `captured`.
- `--new-status STATUS`: Metadata status value to set for entries after successful analysis. Default: `analyzed`.
- `--days-limit N`: How many days back to look for entries to analyze (0 for no limit). Default: `7`.

**Example:**

```bash
# Analyze entries from the last 30 days in the current repo
chroma-client analyze-chat-history --days-limit 30

# Analyze entries in a different repo using a custom status
chroma-client analyze-chat-history --repo-path /path/to/other/repo --status-filter pending --new-status correlated
```

#### `update-collection-ef`

Updates the embedding function name stored in a specific collection's metadata.

**When to Use:**

This command is necessary when you change the embedding function your client uses (e.g., by modifying the `CHROMA_EMBEDDING_FUNCTION` setting in your `.env` file or the equivalent configuration in `.cursor/mcp.json`) for a project with an **existing** ChromaDB collection.

If the new client embedding function doesn't match the function name stored in the collection's metadata (from when it was created or last updated), ChromaDB will raise an `Embedding function name mismatch` error when you try to access the collection (e.g., via `query` or `analyze-chat-history`). Running this command syncs the collection's metadata record with your new client-side setting.

```bash
chroma-client update-collection-ef --collection-name NAME --ef-name EF_NAME
```

**Options:**

- `--collection-name NAME`: (Required) Name of the ChromaDB collection to update.
- `--ef-name EF_NAME`: (Required) The new embedding function name string to store in the collection's metadata (e.g., `sentence_transformer`, `onnx_mini_lm_l6_v2`). This name should typically match the class name or identifier used by ChromaDB for the embedding function specified in your *current* client configuration (`.env` or `mcp.json`).

**Example:**

```bash
# You changed CHROMA_EMBEDDING_FUNCTION in .env to 'accurate' (which maps to sentence_transformer internally)
# Now update the existing 'chat_history_v1' collection metadata to match:
chroma-client update-collection-ef --collection-name chat_history_v1 --ef-name sentence_transformer
```

#### `promote-learning`

Manually promotes an insight or finding into the `derived_learnings_v1` collection. This is useful for adding learnings that didn't originate directly from an automatically analyzed chat entry, or if the interactive `review-and-promote` workflow is bypassed.

```bash
chroma-client promote-learning [OPTIONS]
```

**Options:**

- `--description TEXT`: **(Required)** Concise description of the learning.
- `--pattern TEXT`: **(Required)** Generalized pattern or rule derived.
- `--code-ref TEXT`: **(Required)** Relevant code snippet reference (`chunk_id`: `file:sha:index`).
- `--tags TEXT`: **(Required)** Comma-separated tags.
- `--confidence FLOAT`: **(Required)** Confidence score (0.0-1.0).
- `--source-chat-id TEXT`: (Optional) ID of the source entry in `chat_history_v1` to link and update status to `promoted_to_learning`.
- `--collection-name NAME`: Target collection for the new learning (default: `derived_learnings_v1`).
- `--chat-collection-name NAME`: Source chat history collection (default: `chat_history_v1`).

**Example:**

```bash
# Promote learning from chat entry 'xyz', linking to a code chunk
chroma-client promote-learning \
  --source-chat-id "xyz" \
  --description "Use BackgroundTasks for non-blocking FastAPI tasks." \
  --pattern "Defer long operations in FastAPI via BackgroundTasks." \
  --code-ref "src/api/tasks.py:abc123def456:1" \
  --tags "fastapi,background,async,python" \
  --confidence 0.9
```

**(Note:** For ease of use, a wrapper script `scripts/promote_learning.sh` and a corresponding hatch alias `promote-learn` are typically available. See [`docs/scripts/promote-learning.md`](promote-learning.md) for details.)**

#### `setup-collections`

Ensures that all standard ChromaDB collections required by the system (`codebase_v1`, `chat_history_v1`, `derived_learnings_v1`, `thinking_sessions_v1`) exist. It will create any missing collections using default settings.

```bash
hatch run chroma-client setup-collections
# or using alias:
hatch run setup-collections
```

### `review-and-promote`

Starts an interactive workflow to review chat entries marked with the status 'analyzed' (typically by the `analyze-chat-history` command). It allows the user to:

- View the summary of each analyzed chat entry.
- Search the codebase (`codebase_v1`) for potentially relevant code snippets (chunks) based on the chat summary.
- Choose to:
  - **Promote (p):** Create a new entry in the `derived_learnings_v1` collection. The user provides details like pattern, tags, and confidence, and selects a suggested code reference or enters one manually.
  - **Ignore (i):** Mark the chat entry with status 'ignored'.
  - **Skip (s):** Skip the current entry and move to the next.
  - **Quit (q):** Exit the review process.

This provides a more user-friendly way to curate derived learnings compared to manually using `promote-learning`.

**Arguments:**

- `--days-limit` (int, default: 7): How many days back to look for 'analyzed' entries.
- `--fetch-limit` (int, default: 50): Maximum number of entries to fetch for review in one go.
- `--chat-collection-name` (str, default: "chat_history_v1"): Name of the chat history collection.
- `--learnings-collection-name` (str, default: "derived_learnings_v1"): Name of the derived learnings collection.

**Example:**

```bash
# Start interactive review for entries from the last 3 days
hatch run chroma-client review-and-promote --days-limit 3

# or using alias:
hatch run review-promote --days-limit 3
```

### Note on Usage with Hatch

When running these commands within the `hatch` environment (e.g., `hatch run ...`), you might encounter issues where the `chroma-client` alias defined in `pyproject.toml` is not correctly resolved for subcommands like `analyze-chat-history`.

If commands like `hatch run chroma-client analyze-chat-history ...` fail with "command not found" or similar errors, use the direct module execution syntax instead:

```bash
hatch run python -m chroma_mcp_client.cli <command> [OPTIONS] [ARGS]...

# Example:
hatch run python -m chroma_mcp_client.cli analyze-chat-history --days-limit 30
```
