feat: split CLI into lightweight falkordb-cgraph package

Co-authored-by: gkorland <753206+gkorland@users.noreply.github.com>
Agent-Logs-Url: https://github.com/FalkorDB/code-graph/sessions/b48ad8e3-c799-4522-9425-93bd5e5b2574

Author: Copilot

AGENTS.md

@@ -21,7 +21,7 @@ Knowledge graph visualization tool for codebases. Python FastAPI backend + React
 
 ```text
 api/                  # Python backend
-  cli.py              # cgraph CLI tool (typer)
+  cli.py              # cgraph CLI tool (typer) — full version used during dev
   index.py            # FastAPI app, routes, auth, SPA serving
   graph.py            # FalkorDB graph operations (sync + async)
   llm.py              # GraphRAG + LiteLLM chat
@@ -32,6 +32,10 @@ api/                  # Python backend
   analyzers/          # Language-specific code analyzers
   entities/           # Graph entity models
   git_utils/          # Git history graph construction
+cli/                  # Lightweight CLI package (falkordb-cgraph)
+  pyproject.toml      # Minimal deps: falkordb + typer only
+  cgraph/
+    main.py           # Standalone CLI commands (list, search, neighbors, paths, info, ensure-db)
 app/                  # React frontend (Vite)
   src/components/     # React components (ForceGraph, chat, code-graph, etc.)
   src/lib/            # Utilities
@@ -136,16 +140,26 @@ Key variables (see `.env.template` for full list):
 
 ## CLI (`cgraph`)
 
-Typer-based CLI wrapping the sync `Graph` and `Project` classes. Outputs JSON to stdout, status to stderr. Entry point: `api/cli.py`.
+Two packages provide the `cgraph` command:
 
-Install: `pipx install falkordb-code-graph` or `pip install falkordb-code-graph`
+**Lightweight CLI** (`falkordb-cgraph` — the recommended install for end users):
 
-For development: `make install-cli` or `uv pip install -e .`
+Install: `pipx install falkordb-cgraph`
+
+For development: `make install-cli` (installs from `cli/`)
+
+Provides query commands only (`list`, `search`, `neighbors`, `paths`, `info`, `ensure-db`). The `index` and `index-repo` commands print a helpful message directing users to install `falkordb-code-graph`.
+
+**Full server package** (`falkordb-code-graph` — for development/Docker):
+
+Install: `pip install falkordb-code-graph` or `uv sync`
+
+Also provides `cgraph` via `api/cli.py` and includes all indexing commands.
 
 ```bash
 cgraph ensure-db                          # Start FalkorDB if not running
-cgraph index . --ignore node_modules      # Index local folder
-cgraph index-repo <url>                   # Clone + index a repo
+cgraph index . --ignore node_modules      # Index local folder (full package only)
+cgraph index-repo <url>                   # Clone + index a repo (full package only)
 cgraph list                               # List indexed repos
 cgraph search <prefix> [--repo <name>]    # Full-text prefix search
 cgraph neighbors <id>... [--repo <name>] [--rel <type>] [--label <label>]  # Connected entities

Makefile

@@ -10,8 +10,8 @@ install: ## Install all dependencies (backend + frontend)
 	uv sync --all-extras
 	npm install --prefix ./app
 
-install-cli: ## Install cgraph CLI entry point
-	uv pip install -e .
+install-cli: ## Install lightweight cgraph CLI (falkordb-cgraph) entry point
+	pip install -e ./cli
 
 build-dev: ## Build frontend for development
 	npm --prefix ./app run build:dev

README.md

@@ -26,12 +26,16 @@ code-graph/
 │   ├── project.py        # Repository cloning and analysis orchestration
 │   ├── info.py           # Repository metadata stored in Redis/FalkorDB
 │   ├── prompts.py        # LLM system and prompt templates
-│   ├── cli.py            # cgraph CLI tool (typer)
+│   ├── cli.py            # cgraph CLI tool (full version, dev use)
 │   ├── auto_complete.py  # Prefix search helper
 │   ├── analyzers/        # Source analyzers (Python, Java, C#)
 │   ├── entities/         # Graph/entity models
 │   ├── git_utils/        # Git history graph utilities
 │   └── code_coverage/    # Coverage utilities
+├── cli/                  # Lightweight CLI package (falkordb-cgraph)
+│   ├── pyproject.toml    # Minimal deps: falkordb + typer only
+│   └── cgraph/
+│       └── main.py       # Standalone CLI (list, search, neighbors, paths, info, ensure-db)
 ├── app/                  # React frontend (Vite)
 │   ├── src/              # Frontend source code
 │   ├── public/           # Static assets
@@ -45,7 +49,7 @@ code-graph/
 ├── docker-compose.yml    # Local FalkorDB + app stack
 ├── Makefile              # Common dev/build/test commands
 ├── start.sh              # Container entrypoint
-├── pyproject.toml        # Python package and dependency config
+├── pyproject.toml        # Python server package (falkordb-code-graph) with all deps
 └── .env.template         # Example environment variables
 ```
 
@@ -162,23 +166,31 @@ make clean         # Remove build/test artifacts
 
 ## CLI Tool (`cgraph`)
 
-CodeGraph includes a CLI tool for indexing codebases and querying the knowledge graph directly from the terminal. All output is JSON (to stdout), with status messages on stderr.
+CodeGraph includes a CLI tool for querying the knowledge graph directly from the terminal. All output is JSON (to stdout), with status messages on stderr.
 
 ### Install
 
+**Lightweight CLI** (recommended for end users — fast install, only `falkordb` + `typer`):
+
 ```bash
-# Install from PyPI (recommended for end users)
-pipx install falkordb-code-graph
+# Install from PyPI (recommended)
+pipx install falkordb-cgraph
 
 # Or with pip
+pip install falkordb-cgraph
+```
+
+**Full server package** (includes indexing commands, web server, all heavy deps):
+
+```bash
 pip install falkordb-code-graph
 ```
 
 For development (from a local clone):
 
 ```bash
-make install-cli
-# or
+make install-cli   # installs falkordb-cgraph from cli/
+# or for full server package:
 uv pip install -e .
 ```
 
@@ -188,10 +200,10 @@ uv pip install -e .
 # Ensure FalkorDB is running (auto-starts a Docker container if needed)
 cgraph ensure-db
 
-# Index the current project
+# Index the current project (requires falkordb-code-graph)
 cgraph index . --ignore node_modules --ignore .git --ignore venv --ignore __pycache__
 
-# Index a remote repository
+# Index a remote repository (requires falkordb-code-graph)
 cgraph index-repo https://github.com/user/repo --ignore node_modules
 
 # List indexed repos

cli/README.md

@@ -0,0 +1,54 @@
+# falkordb-cgraph
+
+Lightweight CLI for querying [FalkorDB](https://falkordb.com) code-graph knowledge graphs.
+
+## Installation
+
+```bash
+pipx install falkordb-cgraph
+```
+
+This installs only `falkordb` and `typer` — no heavy server-side dependencies.
+
+## Usage
+
+```bash
+cgraph --help
+
+# Ensure FalkorDB is running (starts a Docker container if needed)
+cgraph ensure-db
+
+# List all indexed repositories
+cgraph list
+
+# Search for entities by prefix
+cgraph search <prefix> [--repo <name>]
+
+# Get neighboring entities
+cgraph neighbors <id>... [--repo <name>] [--rel <type>] [--label <label>]
+
+# Find call-chain paths between two nodes
+cgraph paths <src-id> <dest-id> [--repo <name>]
+
+# Show repository statistics and metadata
+cgraph info [--repo <name>]
+```
+
+`--repo` defaults to the current directory name.
+
+## Indexing
+
+The `index` and `index-repo` commands require the full server package:
+
+```bash
+pip install falkordb-code-graph
+```
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `FALKORDB_HOST` | `localhost` | FalkorDB host |
+| `FALKORDB_PORT` | `6379` | FalkorDB port |
+| `FALKORDB_USERNAME` | — | FalkorDB username (optional) |
+| `FALKORDB_PASSWORD` | — | FalkorDB password (optional) |