diff --git a/AGENTS.md b/AGENTS.md
index a95e44e..0cb5407 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +21,7 @@ Knowledge graph visualization tool for codebases. Python FastAPI backend + React
 
 ```text
 api/                  # Python backend
+  cli.py              # cgraph CLI tool (typer)
   index.py            # FastAPI app, routes, auth, SPA serving
   graph.py            # FalkorDB graph operations (sync + async)
   llm.py              # GraphRAG + LiteLLM chat
@@ -34,6 +35,7 @@ api/                  # Python backend
 app/                  # React frontend (Vite)
   src/components/     # React components (ForceGraph, chat, code-graph, etc.)
   src/lib/            # Utilities
+skills/code-graph/    # Claude Code skill for code graph indexing/querying
 tests/                # Pytest backend tests
   endpoints/          # API endpoint integration tests
 e2e/                  # Playwright E2E tests
@@ -44,6 +46,7 @@ e2e/                  # Playwright E2E tests
 
 ```bash
 make install         # Install all deps (uv sync + npm install)
+make install-cli     # Install cgraph CLI entry point
 make build-dev       # Build frontend (dev mode)
 make build-prod      # Build frontend (production)
 make run-dev         # Build dev frontend + run API with reload
@@ -130,3 +133,22 @@ Key variables (see `.env.template` for full list):
 - `POST /api/analyze_folder` — Analyze local folder
 - `POST /api/analyze_repo` — Clone and analyze repo
 - `POST /api/switch_commit` — Switch to specific commit
+
+## CLI (`cgraph`)
+
+Typer-based CLI wrapping the sync `Graph` and `Project` classes. Outputs JSON to stdout, status to stderr. Entry point: `api/cli.py`.
+
+Install: `make install-cli` or `uv pip install -e .`
+
+```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 list                               # List indexed repos
+cgraph search <prefix> [--repo <name>]    # Full-text prefix search
+cgraph neighbors <id>... [--repo <name>] [--rel <type>] [--label <label>]  # Connected entities
+cgraph paths <src-id> <dest-id> [--repo <name>]  # Call-chain paths
+cgraph info [--repo <name>]              # Repo stats + metadata
+```
+
+`--repo` defaults to the current directory name. Claude Code skill in `skills/code-graph/`.
diff --git a/Makefile b/Makefile
index 37aa58d..e3ff460 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: help install test e2e lint lint-py lint-fe clean build-dev build-prod run-dev run-prod docker-falkordb docker-stop
+.PHONY: help install install-cli test e2e lint lint-py lint-fe clean build-dev build-prod run-dev run-prod docker-falkordb docker-stop
 
 help: ## Show this help message
 	@echo 'Usage: make [target]'
@@ -10,6 +10,9 @@ 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 .
+
 build-dev: ## Build frontend for development
 	npm --prefix ./app run build:dev
 
diff --git a/README.md b/README.md
index 533b32e..834fc43 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,7 @@ 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)
 │   ├── auto_complete.py  # Prefix search helper
 │   ├── analyzers/        # Source analyzers (Python, Java, C#)
 │   ├── entities/         # Graph/entity models
@@ -37,6 +38,7 @@ code-graph/
 │   ├── package.json      # Frontend dependencies and scripts
 │   ├── vite.config.ts    # Vite config and /api proxy for dev mode
 │   └── tsconfig*.json    # TypeScript config
+├── skills/code-graph/    # Claude Code skill for CLI-driven indexing/querying
 ├── tests/                # Backend/unit and endpoint tests
 ├── e2e/                  # End-to-end helpers and Playwright assets
 ├── Dockerfile            # Unified container image
@@ -145,6 +147,7 @@ In this mode, the FastAPI app serves the built React SPA from `app/dist` on `htt
 
 ```bash
 make install       # Install backend + frontend dependencies
+make install-cli   # Install cgraph CLI entry point
 make build-dev     # Build frontend in development mode
 make build-prod    # Build frontend for production
 make run-dev       # Build dev frontend + run Uvicorn with reload
@@ -157,6 +160,58 @@ make clean         # Remove build/test artifacts
 
 `make test` currently points at the right backend test entrypoint, but some legacy analyzer/git-history tests still need maintenance before the suite passes on a clean checkout.
 
+## 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.
+
+### Install
+
+```bash
+make install-cli
+# or
+uv pip install -e .
+```
+
+### Usage
+
+```bash
+# Ensure FalkorDB is running (auto-starts a Docker container if needed)
+cgraph ensure-db
+
+# Index the current project
+cgraph index . --ignore node_modules --ignore .git --ignore venv --ignore __pycache__
+
+# Index a remote repository
+cgraph index-repo https://github.com/user/repo --ignore node_modules
+
+# List indexed repos
+cgraph list
+
+# Search for entities by name prefix
+cgraph search parse_config
+
+# Explore relationships (what does node 42 call?)
+cgraph neighbors 42 --rel CALLS
+
+# Find call-chain paths between two nodes
+cgraph paths 42 99
+
+# Show repo statistics
+cgraph info
+```
+
+The `--repo` flag defaults to the current directory name. Run `cgraph --help` for full details.
+
+### Claude Code Skill
+
+A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill is included in `skills/code-graph/`. Install it with:
+
+```bash
+npx skills add FalkorDB/code-graph
+```
+
+Then ask Claude things like *"what functions call analyze_sources?"* or *"find the dependency chain between parse_config and send_request"* — it will handle the indexing and querying automatically.
+
 ## Running with Docker
 
 ### Using Docker Compose
diff --git a/api/cli.py b/api/cli.py
new file mode 100644
index 0000000..6e4502e
--- /dev/null
+++ b/api/cli.py
@@ -0,0 +1,329 @@
+"""Code Graph CLI — index and query code knowledge graphs.
+
+Machine-readable JSON goes to stdout; human status goes to stderr.
+"""
+
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import List, Optional
+
+import typer
+
+app = typer.Typer(
+    help="Index codebases and query their knowledge graphs.",
+    no_args_is_help=True,
+)
+
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+def _stderr(msg: str) -> None:
+    print(msg, file=sys.stderr)
+
+
+def _json_out(data: object) -> None:
+    print(json.dumps(data, default=str))
+
+
+def _json_error(message: str, code: int = 1) -> None:
+    """Emit a JSON error to stdout and exit."""
+    _json_out({"status": "error", "message": message})
+    raise typer.Exit(code=code)
+
+
+def _default_repo(repo: Optional[str]) -> str:
+    return repo if repo else Path.cwd().name
+
+
+def _check_connection(host: str, port: int) -> bool:
+    """Check if FalkorDB/Redis is reachable via PING."""
+    try:
+        import redis
+
+        r = redis.Redis(host=host, port=port, socket_connect_timeout=2)
+        r.ping()
+        r.close()
+        return True
+    except Exception:
+        return False
+
+
+# ── ensure-db ──────────────────────────────────────────────────────────
+
+
+@app.command("ensure-db")
+def ensure_db() -> None:
+    """Ensure FalkorDB is running, auto-starting a Docker container if needed."""
+
+    host = os.getenv("FALKORDB_HOST", "localhost")
+    port = int(os.getenv("FALKORDB_PORT", "6379"))
+
+    if _check_connection(host, port):
+        _stderr(f"FalkorDB already running on {host}:{port}")
+        _json_out({"status": "ok", "host": host, "port": port})
+        return
+
+    # Only auto-start Docker for local hosts
+    if host not in _LOCAL_HOSTS:
+        _json_error(
+            f"FalkorDB not reachable on {host}:{port} "
+            "and auto-start is only supported for localhost"
+        )
+
+    _stderr(
+        f"FalkorDB not reachable on {host}:{port}, starting Docker container…"
+    )
+
+    try:
+        # Reuse existing stopped container if present
+        inspect = subprocess.run(
+            [
+                "docker",
+                "inspect",
+                "--format",
+                "{{.State.Running}}",
+                "falkordb-cgraph",
+            ],
+            capture_output=True,
+            text=True,
+        )
+
+        if inspect.returncode == 0:
+            if inspect.stdout.strip() == "false":
+                subprocess.run(
+                    ["docker", "start", "falkordb-cgraph"],
+                    check=True,
+                    capture_output=True,
+                )
+                _stderr("Started existing falkordb-cgraph container")
+        else:
+            subprocess.run(
+                [
+                    "docker",
+                    "run",
+                    "-d",
+                    "--name",
+                    "falkordb-cgraph",
+                    "-p",
+                    f"{port}:6379",
+                    "falkordb/falkordb:latest",
+                ],
+                check=True,
+                capture_output=True,
+            )
+            _stderr("Created and started falkordb-cgraph container")
+    except FileNotFoundError:
+        _json_error("Docker is not installed or not on PATH")
+    except subprocess.CalledProcessError as e:
+        _json_error(f"Docker command failed: {e.stderr.strip() if e.stderr else e}")
+
+    # Wait up to 30 s for connectivity
+    for _ in range(30):
+        if _check_connection(host, port):
+            _stderr("FalkorDB is ready")
+            _json_out({"status": "ok", "host": host, "port": port})
+            return
+        time.sleep(1)
+
+    _stderr("Timed out waiting for FalkorDB to become ready")
+    _json_error("timeout")
+
+
+# ── index ──────────────────────────────────────────────────────────────
+
+
+@app.command()
+def index(
+    path: str = typer.Argument(".", help="Local folder to index"),
+    ignore: Optional[List[str]] = typer.Option(
+        None, "--ignore", help="Directories to ignore (repeatable)"
+    ),
+    repo: Optional[str] = typer.Option(
+        None, "--repo", help="Graph name (defaults to folder name)"
+    ),
+) -> None:
+    """Index a local folder into the knowledge graph."""
+    from .project import Project
+
+    folder = Path(path).resolve()
+    if not folder.exists():
+        _json_error(f"path does not exist: {folder}")
+    if not folder.is_dir():
+        _json_error(f"path is not a directory: {folder}")
+
+    name = repo or folder.name
+
+    # Try to detect git remote URL for metadata (non-critical)
+    url = None
+    try:
+        from pygit2.repository import Repository as GitRepo
+
+        remote_url = GitRepo(str(folder)).remotes[0].url
+        url = (
+            remote_url.replace("git@", "https://")
+            .replace(":", "/")
+            .replace(".git", "")
+        )
+    except Exception:
+        # Not a git repo or no remote configured — metadata will be skipped
+        pass
+
+    _stderr(f"Indexing {folder} as '{name}'…")
+    try:
+        project = Project(name, folder, url)
+        graph = project.analyze_sources(ignore=list(ignore) if ignore else [])
+        stats = graph.stats()
+    except Exception as e:
+        _json_error(str(e))
+
+    _stderr(f"Done — {stats['node_count']} nodes, {stats['edge_count']} edges")
+    _json_out({"status": "ok", "repo": name, **stats})
+
+
+# ── index-repo ─────────────────────────────────────────────────────────
+
+
+@app.command("index-repo")
+def index_repo(
+    url: str = typer.Argument(..., help="Git repository URL to clone and index"),
+    ignore: Optional[List[str]] = typer.Option(
+        None, "--ignore", help="Directories to ignore (repeatable)"
+    ),
+) -> None:
+    """Clone a git repository and index it into the knowledge graph."""
+    from .project import Project
+
+    _stderr(f"Cloning and indexing {url}…")
+    try:
+        project = Project.from_git_repository(url)
+        graph = project.analyze_sources(ignore=list(ignore) if ignore else [])
+        stats = graph.stats()
+    except Exception as e:
+        _json_error(str(e))
+
+    _stderr(f"Done — {stats['node_count']} nodes, {stats['edge_count']} edges")
+    _json_out({"status": "ok", "repo": project.name, **stats})
+
+
+# ── list ───────────────────────────────────────────────────────────────
+
+
+@app.command("list")
+def list_repos() -> None:
+    """List all indexed repositories."""
+    from .graph import get_repos
+
+    try:
+        repos = get_repos()
+    except Exception as e:
+        _json_error(str(e))
+
+    _json_out({"repos": repos})
+
+
+# ── search ─────────────────────────────────────────────────────────────
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Prefix to search for"),
+    repo: Optional[str] = typer.Option(
+        None, "--repo", help="Repository name (defaults to CWD name)"
+    ),
+) -> None:
+    """Search for entities by prefix (full-text search)."""
+    from .graph import Graph
+
+    name = _default_repo(repo)
+    try:
+        g = Graph(name)
+        results = g.prefix_search(query)
+    except Exception as e:
+        _json_error(str(e))
+
+    _json_out({"repo": name, "results": results})
+
+
+# ── neighbors ──────────────────────────────────────────────────────────
+
+
+@app.command()
+def neighbors(
+    node_ids: List[int] = typer.Argument(..., help="Node IDs to query"),
+    repo: Optional[str] = typer.Option(
+        None, "--repo", help="Repository name (defaults to CWD name)"
+    ),
+    rel: Optional[str] = typer.Option(
+        None, "--rel", help="Filter by relationship type (e.g. CALLS, DEFINES)"
+    ),
+    label: Optional[str] = typer.Option(
+        None, "--label", help="Filter by destination label (e.g. Function, Class)"
+    ),
+) -> None:
+    """Get neighboring entities of the given node(s)."""
+    from .graph import Graph
+
+    name = _default_repo(repo)
+    try:
+        g = Graph(name)
+        result = g.get_neighbors(node_ids, rel=rel, lbl=label)
+    except Exception as e:
+        _json_error(str(e))
+
+    _json_out({"repo": name, **result})
+
+
+# ── paths ──────────────────────────────────────────────────────────────
+
+
+@app.command()
+def paths(
+    src: int = typer.Argument(..., help="Source node ID"),
+    dest: int = typer.Argument(..., help="Destination node ID"),
+    repo: Optional[str] = typer.Option(
+        None, "--repo", help="Repository name (defaults to CWD name)"
+    ),
+) -> None:
+    """Find call-chain paths between two nodes."""
+    from .graph import Graph
+
+    name = _default_repo(repo)
+    try:
+        g = Graph(name)
+        result = g.find_paths(src, dest)
+    except Exception as e:
+        _json_error(str(e))
+
+    _json_out({"repo": name, "paths": result})
+
+
+# ── info ───────────────────────────────────────────────────────────────
+
+
+@app.command()
+def info(
+    repo: Optional[str] = typer.Option(
+        None, "--repo", help="Repository name (defaults to CWD name)"
+    ),
+) -> None:
+    """Show repository statistics and metadata."""
+    from .graph import Graph
+    from .info import get_repo_info
+
+    name = _default_repo(repo)
+    try:
+        g = Graph(name)
+        stats = g.stats()
+        metadata = get_repo_info(name) or {}
+    except Exception as e:
+        _json_error(str(e))
+
+    _json_out({"repo": name, **stats, "metadata": metadata})
+
+
+if __name__ == "__main__":
+    app()
diff --git a/pyproject.toml b/pyproject.toml
index 49438fb..83d1d6c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -20,8 +20,12 @@ dependencies = [
     "multilspy @ git+https://github.com/AviAvni/multilspy.git@python-init-params",
     "javatools>=1.6.0,<2.0.0",
     "pygit2>=1.17.0,<2.0.0",
+    "typer>=0.24.0,<1.0.0",
 ]
 
+[project.scripts]
+cgraph = "api.cli:app"
+
 [project.optional-dependencies]
 test = [
     "pytest>=9.0.2,<10.0.0",
@@ -29,5 +33,9 @@ test = [
     "httpx>=0.28.0,<1.0.0",
 ]
 
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
 [tool.setuptools.packages.find]
 where = ["."]
diff --git a/skills/code-graph/SKILL.md b/skills/code-graph/SKILL.md
new file mode 100644
index 0000000..38f9923
--- /dev/null
+++ b/skills/code-graph/SKILL.md
@@ -0,0 +1,87 @@
+---
+name: code-graph
+description: "This skill should be used when understanding code structure, finding
+  dependencies between functions/classes, tracing call graphs, or exploring code
+  relationships. Trigger phrases include 'code graph', 'call graph', 'who calls',
+  'what calls', 'find dependencies', 'code structure', 'inheritance', 'find paths'."
+---
+
+# Code Graph Skill
+
+You own the full `cgraph` lifecycle: database, indexing, and querying. The user should never need to run cgraph commands manually.
+
+## Ownership Rules
+
+- If `cgraph` commands fail with connection errors, run `cgraph ensure-db` first.
+- If `cgraph` is not found, see `management.md` for installation instructions.
+- Index at session start or after significant code changes: `cgraph index . --ignore node_modules --ignore venv --ignore .git --ignore __pycache__`
+- No need to re-index between consecutive queries if no code has changed.
+- All command output is JSON on stdout. Status/progress goes to stderr.
+- `--repo` defaults to the current directory name if omitted.
+
+## Indexing
+
+```bash
+# Index the current project
+cgraph index . --ignore node_modules --ignore venv --ignore .git --ignore __pycache__
+
+# Index a specific folder with a custom name
+cgraph index /path/to/project --repo my-project --ignore node_modules
+
+# Clone and index a remote repository
+cgraph index-repo https://github.com/org/repo --ignore node_modules
+```
+
+## Searching
+
+```bash
+# Search for entities by prefix
+cgraph search get_user
+cgraph search parse
+cgraph search MyClass
+```
+
+Results return JSON with node `id`, `labels` (File, Class, Function, etc.), and `properties` (name, path, src_start, src_end). Use the `id` for follow-up queries.
+
+## Exploring Relationships
+
+```bash
+# Get all neighbors of a node
+cgraph neighbors 42 --repo my-project
+
+# Filter by relationship type
+cgraph neighbors 42 --rel CALLS          # what does it call?
+cgraph neighbors 42 --rel DEFINES         # what does it define?
+
+# Filter by destination label
+cgraph neighbors 42 --label Function      # only function neighbors
+
+# Multiple nodes at once
+cgraph neighbors 42 55 --repo my-project
+```
+
+## Finding Paths
+
+```bash
+# Trace call-chain paths between two nodes
+cgraph paths 42 99 --repo my-project
+```
+
+Follows CALLS edges to find how one function reaches another.
+
+## Repository Info
+
+```bash
+# List all indexed repos
+cgraph list
+
+# Show stats for a repo
+cgraph info --repo my-project
+```
+
+## Working with Results
+
+- Search results include `path`, `src_start`, `src_end` — use the Read tool to load the actual source code at those locations.
+- **Node labels**: File, Class, Function, Interface, Struct
+- **Edge types**: DEFINES (hierarchy), CALLS (call graph), EXTENDS (inheritance), IMPLEMENTS (interfaces), RETURNS (return types), PARAMETERS (param types)
+- See `querying.md` for detailed JSON structures and common query patterns.
diff --git a/skills/code-graph/references/management.md b/skills/code-graph/references/management.md
new file mode 100644
index 0000000..f937ee6
--- /dev/null
+++ b/skills/code-graph/references/management.md
@@ -0,0 +1,97 @@
+# Code Graph — Installation & Management
+
+## Prerequisites
+
+- **Docker**: Required for FalkorDB (the graph database)
+- **Python 3.12+**
+- **uv** (Python package manager)
+
+## Installation
+
+### Install the skill (Claude Code)
+
+```bash
+npx skills add FalkorDB/code-graph
+```
+
+### Install the cgraph CLI
+
+From the code-graph repository:
+
+```bash
+cd /path/to/code-graph
+uv sync --all-extras
+uv pip install -e .
+```
+
+Or standalone via pipx:
+
+```bash
+pipx install code-graph-backend
+```
+
+After installation, verify:
+
+```bash
+cgraph --help
+```
+
+## Database
+
+FalkorDB is automatically managed by the `ensure-db` command:
+
+```bash
+cgraph ensure-db
+```
+
+This will:
+1. Check if FalkorDB is reachable on `FALKORDB_HOST:FALKORDB_PORT`
+2. If not, start a Docker container named `falkordb-cgraph`
+3. Wait for connectivity and report status
+
+## Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `FALKORDB_HOST` | `localhost` | FalkorDB/Redis host |
+| `FALKORDB_PORT` | `6379` | FalkorDB/Redis port |
+| `FALKORDB_USERNAME` | _(none)_ | Auth username |
+| `FALKORDB_PASSWORD` | _(none)_ | Auth password |
+
+## Supported Languages
+
+- **Python** (.py) — via tree-sitter
+- **Java** (.java) — via multilspy
+- **C#** (.cs) — via multilspy
+
+## Troubleshooting
+
+### `cgraph` not found
+
+Ensure the package is installed and the entry point is on your PATH:
+
+```bash
+uv pip install -e .   # from the code-graph repo
+# or
+pipx install code-graph-backend
+```
+
+### Connection refused
+
+FalkorDB is not running. Run:
+
+```bash
+cgraph ensure-db
+```
+
+If Docker is not installed, install it first or start FalkorDB manually.
+
+### Stale index
+
+If code has changed significantly since last index, re-index:
+
+```bash
+cgraph index . --ignore node_modules --ignore venv --ignore .git --ignore __pycache__
+```
+
+Re-indexing overwrites the existing graph for the same repo name.
diff --git a/skills/code-graph/references/querying.md b/skills/code-graph/references/querying.md
new file mode 100644
index 0000000..1c91737
--- /dev/null
+++ b/skills/code-graph/references/querying.md
@@ -0,0 +1,101 @@
+# Code Graph — Querying Reference
+
+## JSON Structures
+
+### Node
+
+```json
+{
+  "id": 42,
+  "labels": ["Function"],
+  "properties": {
+    "name": "analyze_sources",
+    "path": "api/project.py",
+    "src_start": 79,
+    "src_end": 94,
+    "doc": "..."
+  }
+}
+```
+
+### Edge
+
+```json
+{
+  "id": 10,
+  "relation": "CALLS",
+  "src_node": 42,
+  "dest_node": 55,
+  "properties": {
+    "pos": 83
+  }
+}
+```
+
+### Neighbors response
+
+```json
+{
+  "repo": "code-graph",
+  "nodes": [ /* node objects */ ],
+  "edges": [ /* edge objects */ ]
+}
+```
+
+### Paths response
+
+```json
+{
+  "repo": "code-graph",
+  "paths": [
+    [ node, edge, node, edge, node ]
+  ]
+}
+```
+
+Each path is an alternating array of node and edge objects.
+
+## Common Query Patterns
+
+### "What does function X call?"
+
+```bash
+cgraph search X
+# note the id from results, e.g. 42
+cgraph neighbors 42 --rel CALLS
+```
+
+### "Who calls function X?"
+
+The graph stores directed edges `(caller)-[:CALLS]->(callee)`. To find callers, search for the function, then look for *incoming* CALLS edges. Since `neighbors` follows outgoing edges, use `cgraph paths` or search for likely callers and check their CALLS neighbors.
+
+### "What does class Y define?"
+
+```bash
+cgraph search Y
+# note the id, e.g. 55
+cgraph neighbors 55 --rel DEFINES
+```
+
+### "Trace path from function A to function B"
+
+```bash
+cgraph search A
+# note id, e.g. 10
+cgraph search B
+# note id, e.g. 99
+cgraph paths 10 99
+```
+
+### "What are the stats for this repo?"
+
+```bash
+cgraph info --repo my-project
+```
+
+## Search Workflow
+
+1. **Search** — find entities by name prefix → get node IDs
+2. **Neighbors** — explore connections from those nodes
+3. **Paths** — trace call chains between specific nodes
+4. **Read source** — use `path`, `src_start`, `src_end` from node properties to read the actual code
diff --git a/tests/test_cli.py b/tests/test_cli.py
new file mode 100644
index 0000000..9b19438
--- /dev/null
+++ b/tests/test_cli.py
@@ -0,0 +1,100 @@
+"""Tests for the cgraph CLI.
+
+Requires FalkorDB running on localhost:6379 (same as the rest of the test suite).
+"""
+
+import json
+import unittest
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+from api.cli import app
+
+runner = CliRunner()
+
+
+class TestCLIList(unittest.TestCase):
+    """list command — always works if FalkorDB is reachable."""
+
+    def test_list_returns_json(self):
+        result = runner.invoke(app, ["list"])
+        self.assertEqual(result.exit_code, 0)
+        data = json.loads(result.output)
+        self.assertIn("repos", data)
+        self.assertIsInstance(data["repos"], list)
+
+
+class TestCLIEnsureDB(unittest.TestCase):
+    """ensure-db command — FalkorDB is already running in CI/test."""
+
+    def test_ensure_db_ok(self):
+        result = runner.invoke(app, ["ensure-db"])
+        self.assertEqual(result.exit_code, 0)
+        data = json.loads(result.output)
+        self.assertEqual(data["status"], "ok")
+
+
+class TestCLIIndex(unittest.TestCase):
+    """Index a small fixture directory and query it."""
+
+    FIXTURE_DIR = Path(__file__).parent / "source_files" / "py"
+    REPO_NAME = "cli_test_py"
+
+    @classmethod
+    def setUpClass(cls):
+        result = runner.invoke(
+            app,
+            ["index", str(cls.FIXTURE_DIR), "--repo", cls.REPO_NAME],
+        )
+        assert result.exit_code == 0, result.output
+        cls.index_data = json.loads(result.output)
+
+    def test_index_status(self):
+        self.assertEqual(self.index_data["status"], "ok")
+        self.assertEqual(self.index_data["repo"], self.REPO_NAME)
+
+    def test_index_created_nodes(self):
+        self.assertGreater(self.index_data["node_count"], 0)
+
+    def test_info(self):
+        result = runner.invoke(app, ["info", "--repo", self.REPO_NAME])
+        self.assertEqual(result.exit_code, 0)
+        data = json.loads(result.output)
+        self.assertIn("node_count", data)
+        self.assertIn("edge_count", data)
+        self.assertEqual(data["repo"], self.REPO_NAME)
+
+    def test_search(self):
+        result = runner.invoke(
+            app, ["search", "src", "--repo", self.REPO_NAME]
+        )
+        self.assertEqual(result.exit_code, 0)
+        data = json.loads(result.output)
+        self.assertIn("results", data)
+        # The fixture has a file named src.py, so we should find something
+        self.assertIsInstance(data["results"], list)
+
+    def test_list_includes_repo(self):
+        result = runner.invoke(app, ["list"])
+        self.assertEqual(result.exit_code, 0)
+        data = json.loads(result.output)
+        self.assertIn(self.REPO_NAME, data["repos"])
+
+
+class TestCLIHelp(unittest.TestCase):
+    """Smoke test: --help should always work without a DB."""
+
+    def test_main_help(self):
+        result = runner.invoke(app, ["--help"])
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn("index", result.output)
+        self.assertIn("search", result.output)
+
+    def test_index_help(self):
+        result = runner.invoke(app, ["index", "--help"])
+        self.assertEqual(result.exit_code, 0)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/uv.lock b/uv.lock
index 44c773a..dd1df3e 100644
--- a/uv.lock
+++ b/uv.lock
@@ -250,7 +250,7 @@ wheels = [
 [[package]]
 name = "code-graph-backend"
 version = "0.4.2"
-source = { virtual = "." }
+source = { editable = "." }
 dependencies = [
     { name = "falkordb" },
     { name = "fastapi" },
@@ -264,6 +264,7 @@ dependencies = [
     { name = "tree-sitter-c-sharp" },
     { name = "tree-sitter-java" },
     { name = "tree-sitter-python" },
+    { name = "typer" },
     { name = "uvicorn", extra = ["standard"] },
     { name = "validators" },
 ]
@@ -292,6 +293,7 @@ requires-dist = [
     { name = "tree-sitter-c-sharp", specifier = ">=0.23.1,<0.24.0" },
     { name = "tree-sitter-java", specifier = ">=0.23.5,<0.24.0" },
     { name = "tree-sitter-python", specifier = ">=0.25.0,<0.26.0" },
+    { name = "typer", specifier = ">=0.24.0,<1.0.0" },
     { name = "uvicorn", extras = ["standard"], specifier = ">=0.34.0,<1.0.0" },
     { name = "validators", specifier = ">=0.35.0,<0.36.0" },
 ]