Skip to content

cli_commands_manual.md

Latest commit

 

History

History
700 lines (503 loc) · 15.5 KB

cli_commands_manual.md

File metadata and controls

700 lines (503 loc) · 15.5 KB

CodeSeeker CLI Commands Manual

Version: 2.0.0 Last Updated: December 2025

CodeSeeker is an intelligent CLI tool that enhances Claude Code with semantic search, knowledge graphs, and AI-powered code analysis.

Table of Contents

  1. Installation & Quick Start
  2. Command-Line Usage
  3. Infrastructure Setup
  4. Project Initialization
  5. Semantic Search
  6. Project Management
  7. Code Analysis
  8. Natural Language Queries
  9. Built-in Commands
  10. Environment Variables

Installation & Quick Start

# Install globally
npm install -g codeseeker

# Or link from source
cd CodeSeeker
npm run build && npm link

# Verify installation
codeseeker --help

Quick Start Workflow

# 1. Setup infrastructure (first time only)
codeseeker setup

# 2. Initialize your project
cd /path/to/your/project
codeseeker init

# 3. Ask questions about your code
codeseeker -c "what is this project about"

Command-Line Usage

Basic Syntax

codeseeker [options] [command]

Options

Option Description
-V, --version Output the version number
-p, --project <path> Specify project path
-c, --command <cmd> Execute single command and exit
-t, --transparent Skip interactive prompts, output context directly
--no-color Disable colored output
-h, --help Display help information

Usage Examples

# Start interactive REPL mode
codeseeker

# Start with specific project path
codeseeker -p /path/to/project

# Execute single command and exit
codeseeker -c "analyze main entry point"

# Execute in transparent mode (no prompts)
codeseeker -t -c "what files handle authentication"

# Direct command (same as -c)
codeseeker "what is this project about"

Infrastructure Setup (setup)

One-time infrastructure setup for Docker containers and databases.

Syntax

codeseeker setup [options]

Options

Option Description
--force Force setup even if already configured
--skip-docker Skip Docker container setup
--skip-db, --skip-databases Skip database initialization
--project-path <path> Setup from specific directory

What It Does

  1. Verifies Docker is installed and running
  2. Starts required containers (PostgreSQL, Neo4j, Redis)
  3. Initializes database schemas
  4. Creates required indexes and extensions (pgvector)

Examples

# Full infrastructure setup
codeseeker setup

# Force re-setup
codeseeker setup --force

# Setup without Docker (use existing databases)
codeseeker setup --skip-docker

# Setup with custom project path
codeseeker setup --project-path /path/to/project

Project Initialization (init)

Initialize a project for CodeSeeker analysis. Creates embeddings, knowledge graph, and configuration.

Syntax

codeseeker init [options] [path]

Options

Option Description
--reset Complete cleanup and reinitialization
--quick Initialize without indexing (faster)
--new-config Reset project configuration (for copied folders)

What It Does

  1. Registers project in database
  2. Creates .codeseeker/project.json configuration
  3. Indexes codebase for semantic search (unless --quick)
  4. Builds initial knowledge graph in Neo4j
  5. Creates CODESEEKER.md template if missing

Examples

# Initialize current directory
codeseeker init

# Quick initialization (no indexing)
codeseeker init --quick

# Complete reset (clears all data)
codeseeker init --reset

# Reset config for copied project folder
codeseeker init --new-config

Output

🚀 Initializing CodeSeeker project...
📁 Project path: /path/to/project
📊 Setting up database...
✅ Database connection established
📋 Registering project...
✅ Project registered: MyProject (uuid)
🔍 Indexing codebase for semantic search...
✅ Indexed 150 files, 450 code segments
🕸️ Building knowledge graph...
✅ Knowledge graph created with triads
📝 Setting up project instructions...
✅ CODESEEKER.md already exists
🎉 CodeSeeker project initialized successfully!

Semantic Search (search)

Index codebase and perform semantic searches using vector embeddings.

Syntax

codeseeker search [query] [options]

Options

Option Description
--index Index/reindex the codebase
--threshold=<value> Similarity threshold (default: 0.7)
--limit=<value> Maximum results (default: 10)
--verbose Show detailed content previews

Index Command

# Index codebase for semantic search
codeseeker search --index

Indexing features:

  • Incremental indexing (only changed files)
  • Content hashing for change detection
  • Automatic cleanup of deleted files
  • Uses Xenova/all-MiniLM-L6-v2 model (384 dimensions)

Search Command

# Basic search
codeseeker search "authentication middleware"

# Search with options
codeseeker search "database connection" --threshold=0.5 --limit=20 --verbose

Examples

# Index the codebase first
codeseeker search --index

# Search for specific functionality
codeseeker search "user validation"

# Search with lower threshold for more results
codeseeker search "error handling" --threshold=0.5

# Verbose search with content previews
codeseeker search "API endpoints" --verbose --limit=15

Output

🔍 Searching for: "authentication middleware"
🧠 Found 450 code segments to search

🔍 Search Results (5 found):

📄 Result 1:
   File: src/middleware/auth.ts
   Type: code
   Similarity: 89.2%

📄 Result 2:
   File: src/services/auth-service.ts
   Type: code
   Similarity: 76.5%

Project Management (project)

Manage project registration, identity, and duplicates.

Syntax

codeseeker project <subcommand> [args]

Subcommands

Subcommand Alias Description
list ls List all registered projects
info - Show detailed project information
id - Get deterministic ID for a path
cleanup clean Clean up duplicate project entries
duplicates dups Find all duplicate project entries
help - Show project command help

Examples

# List all projects
codeseeker project list
codeseeker project ls

# Show project info
codeseeker project info
codeseeker project info /path/to/project

# Get deterministic ID
codeseeker project id
codeseeker project id /path/to/project

# Find duplicates
codeseeker project duplicates
codeseeker project dups

# Clean up duplicates for current project
codeseeker project cleanup
codeseeker project clean /path/to/project

# Show help
codeseeker project help

List Output

=== Registered Projects ===

  ✓ MyProject
    ID: 2b9a2a85-b3e4-47cc-ade1-2da2724fe0f4
    Path: /workspace/myproject
    Status: active
    Embeddings: 450

  ✓ AnotherProject
    ID: df588867-a7f4-4964-b0e2-f732cb3438f2
    Path: /workspace/another
    Status: active
    Embeddings: 280

Project ID System

CodeSeeker uses deterministic project IDs based on SHA-256 hash of normalized path:

  • Ensures consistent IDs across reinitializations
  • Prevents duplicate entries for the same project
  • Handles path normalization (Windows/Unix differences)

Code Analysis (analyze)

Perform AI-enhanced code analysis using the 11-step workflow.

Syntax

codeseeker analyze <query>

What It Does (11-Step Workflow)

  1. Query Analysis - Detects assumptions and ambiguities
  2. Task Decomposition - Splits complex queries into focused sub-tasks
  3. User Clarification - Prompts for clarification when needed
  4. Hybrid Search - Semantic + text + path search with RRF fusion
  5. Knowledge Graph Query - Analyzes code relationships
  6. Sub-Task Context - Generates tailored context per sub-task
  7. Context Building - Combines all sources into enhanced context
  8. AI Analysis - Generates contextual recommendations
  9. File Approval - Confirms any file modifications
  10. Build/Test Verification - Validates code changes
  11. Database Sync - Updates embeddings and knowledge graph

Examples

# Analyze specific functionality
codeseeker analyze "how does user authentication work"

# Analyze code patterns
codeseeker analyze "where is validation logic implemented"

# Analyze architecture
codeseeker analyze "what design patterns are used"

Output

🔍 Analyzing: "how does user authentication work"

🚀 Starting enhanced AI workflow...

1️⃣ Detecting assumptions...
   📝 Detected 3 contextual assumptions
      • Project implements API/service architecture
      • Security and authorization is important
      • User seeks understanding of system behavior

2️⃣ Processing clarifications...
   🎯 Enhanced query: "how does user authentication work (Context: ...)"

3️⃣ Performing semantic search...
   🧠 Found 450 code segments to search
   🔍 Found 5 relevant code segments

4️⃣ Querying knowledge graph...
   🕸️ Found 12 relationships in knowledge graph

5️⃣ Building enhanced context...
   📊 Context enhancement quality: 8/10

6️⃣ Generating AI analysis...
   🤖 Generated contextual analysis with 4 recommendations

7️⃣ File modifications: Not implemented in MVP

8️⃣ Preparing summary...

📋 Analysis Summary:
   Query: how does user authentication work
   Code segments found: 5
   Relationships found: 12

🔍 Key Insights:
   1. Contains function/class definitions for auth
   2. Handles imports and dependencies
   3. Provides testing logic and validation scenarios

💡 Recommendations:
   1. Review 5 code segments found for "authentication"
   2. Check consistency across 3 files
   3. Analyze 12 architectural relationships

✅ Enhanced analysis completed!

Natural Language Queries

Ask questions directly without specific commands. CodeSeeker automatically detects natural language and triggers the enhanced workflow.

Search Toggle Feature

Before entering a prompt, you can toggle semantic search on/off. This is useful when:

  • You want to skip file discovery and send prompts directly to Claude
  • You know exactly what you want Claude to do without context gathering
  • You want faster responses for simple queries

Menu-Based Toggle

When using the menu-based prompt interface, you'll see:

  Search: ON

? Options:
  > Enter prompt (with search)
    Turn OFF search (skip file discovery)
    Cancel

Select "Turn OFF search" to disable semantic search, then enter your prompt.

Inline Toggle

When using the inline prompt interface:

  [s] to toggle search | Search: ON
>
  • Type s and press Enter to toggle search mode
  • Or type your prompt directly

Syntax

codeseeker -c "<natural language query>"
# or in interactive mode, just type your question

Examples

# Understanding the project
codeseeker -c "what is this project about"
codeseeker -c "explain the main architecture"

# Finding code
codeseeker -c "where are the API endpoints defined"
codeseeker -c "show me files related to user authentication"

# Code changes (triggers approval workflow)
codeseeker -c "add error handling to the database service"
codeseeker -c "create a new middleware for request logging"

# Analysis requests
codeseeker -c "check this codebase for SOLID violations"
codeseeker -c "find duplicate code patterns"

Interactive Mode

codeseeker> what is this project about
codeseeker> show me how authentication works
codeseeker> create a new API endpoint for users

Built-in Commands

Available in both slash-command (/command) and direct (command) formats.

Help

/help          # Show all available commands
help           # Same as above

Status

/status        # Show current project and service status
status         # Same as above

Shows:

  • Current project name, path, and ID
  • File count and embeddings count
  • Database connection status
  • Workflow service status

History

/history              # Show command history
/history show         # Same as above
/history clear        # Clear command history
/history help         # Show history help

Features:

  • Per-project command history
  • Stored in ~/.codeseeker/history/
  • Up to 100 commands preserved

Exit

/exit          # Exit CodeSeeker
/quit          # Same as above
exit           # Same as above
quit           # Same as above

Environment Variables

Configure CodeSeeker behavior via environment variables or .env file.

Database Configuration

Variable Default Description
DB_HOST localhost PostgreSQL host
DB_PORT 5432 PostgreSQL port
DB_NAME codeseeker Database name
DB_USER codeseeker Database user
DB_PASSWORD codeseeker123 Database password

Neo4j Configuration

Variable Default Description
NEO4J_URI bolt://localhost:7687 Neo4j connection URI
NEO4J_USER neo4j Neo4j user
NEO4J_PASSWORD codeseeker123 Neo4j password

Redis Configuration

Variable Default Description
REDIS_HOST localhost Redis host
REDIS_PORT 6379 Redis port
REDIS_PASSWORD (empty) Redis password

Example .env File

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=codeseeker
DB_USER=codeseeker
DB_PASSWORD=codeseeker123

# Neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=codeseeker123

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

Troubleshooting

Common Issues

Low semantic similarity scores:

# Regenerate embeddings with correct model
codeseeker search --index

Project not found:

# Initialize the project first
codeseeker init

Database connection failed:

# Check Docker containers
docker ps

# Restart infrastructure
codeseeker setup --force

Path mismatch (copied project folder):

# Reset configuration for new location
codeseeker init --new-config

Duplicate projects:

# Find duplicates
codeseeker project duplicates

# Clean up
codeseeker project cleanup

Keyboard Shortcuts (Interactive Mode)

Shortcut Action
Ctrl+C (once) Show warning, press again to exit
Ctrl+C (twice) Force exit
Escape Interrupt current operation
Ctrl+Z Interrupt current operation
Up/Down Navigate command history

Technical Notes

Embedding Model

CodeSeeker uses Xenova/all-MiniLM-L6-v2 for all embeddings:

  • 384-dimensional vectors
  • Consistent model across indexing and retrieval
  • pgvector extension in PostgreSQL for similarity search

Project Identity

  • Deterministic IDs using SHA-256 of normalized path
  • Prevents duplicates across reinitializations
  • Supports project migration and path changes

Database Schema

  • PostgreSQL: Projects, embeddings, analysis results
  • Neo4j: Knowledge graph (files, classes, relationships)
  • Redis: Caching and session management

Support