Split CLI into separate lightweight falkordb-cgraph package

[Copilot]

pipx install falkordb-code-graph pulls in the entire server dependency tree (tree-sitter grammars, graphrag-sdk, fastapi, pygit2, multilspy, etc.) because api/__init__.py eagerly imports everything — even though the CLI only needs falkordb + typer for query commands.

New cli/ package (falkordb-cgraph)

• cli/pyproject.toml — declares only falkordb, typer, python-dotenv as dependencies
• cli/cgraph/main.py — standalone CLI with zero imports from api/; implements query commands directly against FalkorDB via Cypher

pipx install falkordb-cgraph   # fast, lightweight — query commands only
pip install falkordb-code-graph  # full server package — includes indexing

Command behavior

Command	falkordb-cgraph	falkordb-code-graph
ensure-db, list, search, neighbors, paths, info	✅ works	✅ works
index, index-repo	Prints helpful error → install falkordb-code-graph	✅ works

Other changes

• Makefile: install-cli now installs from cli/ instead of the root package
• README.md, AGENTS.md, skills/code-graph/references/management.md: updated install instructions to recommend falkordb-cgraph for end users
• .github/workflows/pypi-publish.yml: added a publish-cli job that builds and publishes falkordb-cgraph from cli/dist/ in parallel with the existing server publish job, both triggered on v*.*.* tags using trusted OIDC publishing

Original prompt

Problem

Running pipx install falkordb-code-graph freezes the machine because the single pyproject.toml bundles all dependencies (tree-sitter grammars, graphrag-sdk, fastapi, uvicorn, pygit2, javatools, multilspy, etc.) even though the CLI only needs typer and falkordb for most commands. After install, cgraph may also not be found due to packaging issues.

The root cause is that api/cli.py lives inside the api/ package, and api/__init__.py eagerly imports everything:

# api/__init__.py
from .info import *
from .llm import ask
from .graph import *
from .project import *
from .entities import *
from .git_utils import *
from .code_coverage import *
from .analyzers.source_analyzer import *
from .auto_complete import prefix_search

So even though cli.py uses lazy imports for heavy modules, Python resolves the api package and pulls in the entire dependency tree.

Solution

Split the CLI into its own separate lightweight package. The repo should have two pyproject.toml files:

1. New lightweight CLI package (e.g. cli/ directory)

Create a new cli/ directory at the repo root with its own pyproject.toml:

• Package name: falkordb-cgraph (or similar lightweight name)
• Entry point: cgraph command
• Dependencies: Only typer, falkordb (which brings in redis), and maybe python-dotenv
• Contains: The CLI commands that only need to talk to FalkorDB directly: list, search, neighbors, paths, info, ensure-db
• This is what end users install: pipx install falkordb-cgraph — fast, lightweight, just works

The CLI code should be extracted from api/cli.py into the new package. The query commands (search, neighbors, paths, info, list, ensure-db) only use falkordb to query the graph database directly — they don't need any analysis pipeline code.

For the index and index-repo commands, which DO need the heavy dependencies (tree-sitter, pygit2, project.py, analyzers, etc.), there are a few options:

• Remove them from the lightweight CLI and keep them only in the server package
• Or have the lightweight CLI call the server's REST API (POST /api/analyze_folder, POST /api/analyze_repo) instead of importing the analysis code directly
• Or make them print a helpful error message saying "install falkordb-code-graph for indexing support"

2. Existing server/full package (root pyproject.toml)

The existing pyproject.toml at the repo root keeps all the heavy dependencies for the server (fastapi, uvicorn, tree-sitter grammars, graphrag-sdk, pygit2, javatools, multilspy, etc.). This is what gets deployed via Docker or uv run for the web server + indexing pipeline. It may optionally still expose a cgraph entry point for development convenience, but the primary install path for CLI users is the lightweight package.

Key architectural point

The new CLI package must NOT import from the api package (since api/__init__.py eagerly imports everything heavy). It should have its own clean module that only depends on falkordb for graph queries and typer for the CLI framework. The graph query logic needed by the CLI (prefix_search, get_neighbors, find_paths, stats, get_repos) is straightforward FalkorDB/Cypher queries that can be duplicated or extracted into shared lightweight query code.

Current relevant files

• pyproject.toml — single package definition with all deps
• api/cli.py — CLI entry point (cgraph = "api.cli:app")
• api/__init__.py — eagerly imports everything
• api/graph.py — Graph class with query methods (only needs falkordb)
• api/project.py — imports pygit2, validators, SourceAnalyzer (heavy)
• api/index.py — FastAPI server (heavy)
• Makefile — has install-cli target
• README.md — documents CLI install
• AGENTS.md — documents CLI
• skills/code-graph/ — Claude Code skill references CLI

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: running pipx install falkordb-code-graph on my local ubuntu is freezing my machine and even after the install finishes cgraph command is not found

Assistant:

Let me investigate this issue by looking at the repository's setup configuration and installation mechanism.

Assistant: I found two issues causing your problems. Let me look at the dependency list more closely to understand the freeze issue:

Assistant: I can see two issues here. Let me explain what's happening:

1. Machine Freezing During Install

The falkordb-code-graph package has a very heavy dependency tree (26 direct dependencies including graphrag-sdk, multiple tree-sitter-* grammars, fastapi, uvicorn, pygit2, javatools, etc.). When pipx resolves and installs all of these into an isolated virtualenv, it can be extremely CPU and memory intensive — especially if some packages need to be built from source (e.g., pygit2 has native C extensions).

Workaround: Try...

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[gkorland]

@copilot did you also organize the publish workflow to pypi?

[Copilot]

@copilot did you also organize the publish workflow to pypi?

Done in commit 9f65d25. The pypi-publish.yml workflow now has two parallel jobs triggered on v*.*.* tags:

• publish-server — unchanged, builds and publishes falkordb-code-graph from the repo root
• publish-cli — new job, runs cd cli && uv build and publishes falkordb-cgraph using packages-dir: cli/dist/

Both jobs use trusted publishing (OIDC id-token: write) against the existing pypi environment.