Development Setup

January 12, 2026 · View on GitHub

Set up your development environment for IntellyWeave CLI.

Prerequisites

Requirement	Version	Notes
Node.js	>= 18	Required
npm	>= 9	Comes with Node.js
Git	Latest	For version control
Weaviate	Any	Local Docker or WCD
pre-commit	Latest	For git hooks
gitleaks	Latest	For secret detection

Initial Setup

1. Clone the Repository

git clone https://github.com/Intellyweave/intellyweave-cli.git
cd intellyweave-cli

2. Install Dependencies

npm install

3. Create Environment File

cp .env.example .env

4. Configure Environment

Edit .env:

# Weaviate Configuration
WEAVIATE_URL=http://localhost:8080

# For Weaviate Cloud (alternative)
# WCD_URL=https://your-cluster.weaviate.network
# WCD_API_KEY=your-api-key

# VoyageAI (optional, for embeddings)
VOYAGEAI_API_KEY=your-key

# AI Agent (for natural language queries in shell)
ANTHROPIC_API_KEY=sk-ant-...
AI_MODEL=claude-haiku-4-5

5. Configure MCP Servers (Optional)

Create intellyweave.config.json:

{
  "mcpServers": {
    "weaviate": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@smithery/cli", "run", "@weaviate/mcp-server-weaviate"]
    }
  }
}

6. Build the Project

npm run build

7. Install Pre-Commit Hooks

Install git hooks for secret detection:

pre-commit install

This prevents accidental commits of API keys and credentials. See Secret Detection for details.

8. Verify Installation

npm run intellyweave -- --version

Available Scripts

Development

npm run dev              # Run CLI in dev mode (tsx)
npm run intellyweave     # Alias for dev mode
npm start                # Run compiled CLI

Building

npm run build            # Compile TypeScript to dist/

Code Quality

npm run lint             # Check code with Biome
npm run lint:fix         # Auto-fix linting issues
npm run format           # Format code with Biome
npm run check            # Run linter + type checking

Testing

npm run test             # Run all tests
npm run test:unit        # Unit tests only
npm run test:commands    # Command tests only
npm run test:shell       # Shell tests only
npm run test:integration # Integration tests only
npm run test:watch       # Watch mode
npm run test:coverage    # Generate coverage report

Running Commands in Development

Use npm run intellyweave -- to run commands:

# Preview a data import (dry-run)
npm run intellyweave -- data import

# Execute a data import
npm run intellyweave -- --live data import

# Run with global flags
npm run intellyweave -- --verbose --json weaviate collections

# Test interactive shell
npm run intellyweave -- shell

Weaviate Setup for Development

Option 1: Docker Compose

Create docker-compose.yaml:

version: '3.8'
services:
  weaviate:
    image: semitechnologies/weaviate:latest
    ports:
      - "8080:8080"
      - "50051:50051"
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
    volumes:
      - weaviate_data:/var/lib/weaviate

volumes:
  weaviate_data:

Start:

docker compose up -d weaviate

Option 2: Weaviate Cloud

Use WCD for development:

# In .env
WCD_URL=https://your-dev-cluster.weaviate.network
WCD_API_KEY=your-api-key

IDE Setup

VS Code

Recommended extensions:

ESLint / Biome
TypeScript
Prettier (disable for this project - using Biome)

Settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "biomejs.biome",
  "typescript.preferences.importModuleSpecifier": "relative"
}

Troubleshooting

"Cannot find module" Errors

Rebuild the project:

npm run build

TypeScript Errors

Run type check:

npm run check

Weaviate Connection Issues

Check Docker is running:
```
docker ps | grep weaviate
```
Verify URL in .env:
```
grep WEAVIATE .env
```

Test connection:

npm run intellyweave -- weaviate status