# How to Use Codebase-Memory-MCP CLI Commands: A Complete Guide

> Learn to use Codebase-Memory-MCP CLI commands for repository indexing and semantic code search. Access 14 graph-based code analysis tools without a persistent server.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-04

---

**Codebase-Memory-MCP exposes 14 graph-based code analysis tools through a JSON-RPC-style CLI interface activated by the `cli` sub-command, enabling repository indexing and semantic code search without running a persistent server.**

The `DeusData/codebase-memory-mcp` repository ships as a single static binary that dual-functions as both an MCP server and a standalone command-line utility. When you invoke the binary with the `cli` sub-command, it switches into a JSON-RPC interface that accepts tool-specific JSON payloads, validates them against schemas, and executes operations against an in-memory SQLite graph stored in `~/.cache/codebase-memory-mcp`.

## CLI Architecture and Entry Points

The Python-based entry point for the CLI mode lives in [`pkg/pypi/src/codebase_memory_mcp/_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/src/codebase_memory_mcp/_cli.py). The `main()` function in this module handles platform detection, binary downloads, and argument forwarding.

When you execute a command, the helper function performs the following actions:

1. **Parses** the current version and determines the platform-specific native binary location.
2. **Downloads** the native binary if it does not exist locally.
3. **Executes** the binary directly on Unix systems via `os.execv`, or **spawns** a subprocess on Windows using `subprocess.run`.
4. **Forwards** all arguments verbatim using `args = [str(bin_path)] + sys.argv[1:]`, ensuring that any flags or JSON payloads you provide pass unchanged to the native binary.

This architecture ensures the CLI operates with zero external dependencies once the initial binary is cached.

## Command Syntax and Execution Flow

The native binary implements a strict command dispatcher that expects the following format:

```bash
codebase-memory-mcp cli <tool> <json-payload>

```

The `<tool>` parameter specifies one of 14 available MCP tools (such as `index_repository`, `search_graph`, or `trace_path`), while `<json-payload>` supplies the tool-specific parameters as a JSON object.

The execution flow follows this sequence:

- **Deserialization** of the JSON payload into the tool's request schema.
- **Validation** against the tool's parameter schema.
- **Execution** against the in-memory SQLite graph or the persisted database under `~/.cache/codebase-memory-mcp`.
- **Output** of the JSON-RPC result to **stdout**, while diagnostic logs route to **stderr** according to the logging policy defined in the repository.

## Essential Codebase-Memory-MCP CLI Commands

### Index a Repository

Create a graph representation of your codebase and enable file watching for automatic updates:

```bash
codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/my/project"}'

```

This command parses the repository structure, extracts symbols and relationships, and populates the graph database.

### Search the Code Graph

Find functions matching a specific regex pattern:

```bash
codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*", "label": "Function"}'

```

This returns all `Function` nodes whose names match the provided regular expression, including metadata about file locations and relationships.

### Trace Call Relationships

Analyze inbound and outbound call relationships for a specific function:

```bash
codebase-memory-mcp cli trace_path '{"function_name": "process_order", "direction": "both"}'

```

The `direction` parameter accepts `in`, `out`, or `both` to filter caller and callee relationships.

### Execute Cypher Queries

Run arbitrary read-only openCypher queries against the graph:

```bash
codebase-memory-mcp cli query_graph '{"query": "MATCH (f:Function) RETURN f.name LIMIT 5"}'

```

This provides direct access to the underlying graph database for complex analytical queries.

### List Indexed Projects

View all currently indexed projects and their statistics:

```bash
codebase-memory-mcp cli list_projects

```

The output displays each project's name along with node and edge counts.

### Process Raw JSON Output

For integration with Unix pipelines, use the `--raw` flag to omit the JSON-RPC envelope:

```bash
codebase-memory-mcp cli --raw search_graph '{"label": "Function"}' | jq '.results[].name'

```

This extracts just the result array, making it compatible with tools like `jq`, `grep`, or `awk`.

## Configuration and Automation

Enable automatic indexing when connecting new projects:

```bash
codebase-memory-mcp config set auto_index true

```

Once configured, the system automatically indexes any newly connected repository without requiring explicit `index_repository` calls. All configuration and cached graph data persists in `~/.cache/codebase-memory-mcp`, ensuring fast subsequent startups even for large codebases.

## Summary

- **Codebase-Memory-MCP** ships as a single static binary that doubles as an MCP server and CLI tool.
- The **entry point** at [`pkg/pypi/src/codebase_memory_mcp/_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/src/codebase_memory_mcp/_cli.py) forwards arguments to a native binary using `os.execv` (Unix) or `subprocess.run` (Windows).
- Use the **`cli` sub-command** followed by a tool name and JSON payload to execute graph operations.
- **Standard output** contains JSON-RPC responses suitable for parsing, while **stderr** receives diagnostic logs.
- The **`--raw` flag** strips the JSON-RPC envelope for seamless shell pipeline integration.
- **Configuration** commands like `config set auto_index true` enable automation for continuous indexing workflows.

## Frequently Asked Questions

### What is the difference between the MCP server mode and CLI mode?

The same binary operates in both modes. When invoked without the `cli` sub-command, it starts as a persistent MCP server communicating via standard input/output streams. When invoked with `codebase-memory-mcp cli <tool> <payload>`, it executes a single tool operation and exits immediately, making it suitable for shell scripts and CI/CD pipelines that do not require a long-running process.

### Where does Codebase-Memory-MCP store the graph database?

The system stores the SQLite graph database and related cache files in `~/.cache/codebase-memory-mcp`. This location persists across CLI invocations, allowing you to index a repository once and query it repeatedly without re-indexing. The database operates in-memory during active sessions but persists to this cache directory for fast subsequent loading.

### How does the CLI handle binary dependencies on different platforms?

The `main()` function in [`pkg/pypi/src/codebase_memory_mcp/_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/src/codebase_memory_mcp/_cli.py) automatically detects your platform and downloads the appropriate native binary on first use. On Unix systems, it uses `os.execv` to replace the Python process with the native binary, while on Windows it uses `subprocess.run` to spawn the binary as a child process. This ensures zero manual dependency management regardless of operating system.

### Can I pipe CLI output to other Unix tools?

Yes. The CLI writes JSON-RPC responses to **stdout** and logs to **stderr**, following standard Unix conventions. Use the **`--raw` flag** to remove the JSON-RPC envelope and output only the result payload, which simplifies parsing with tools like `jq`. For example: `codebase-memory-mcp cli --raw search_graph '{"label": "Function"}' | jq '.[].name'`.