# How to Use CLI Mode to Invoke MCP Tools from the Command Line in codebase-memory-mcp

> Learn how to use CLI mode to invoke MCP tools from the command line with codebase-memory-mcp. Execute tools directly from your shell without complex network setup.

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

---

**Use `codebase-memory-mcp cli <tool_name> '<JSON-payload>'` to invoke any MCP tool directly from your shell without network configuration.**

The `codebase-memory-mcp` repository by DeusData ships with a built-in command-line interface that transforms the binary into a standalone JSON-RPC client. This CLI mode lets you execute graph operations, repository indexing, and code tracing directly from bash or PowerShell scripts without spawning an HTTP server or writing Python code.

## How the CLI Shim Works

The magic happens 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), where the `main()` function (lines 6-24) acts as a thin shim between your shell and the static binary. When you invoke the tool with `cli` as the first argument, the shim bypasses the network layer entirely and forwards your commands as a JSON-RPC request to the embedded MCP server.

The implementation handles cross-platform execution gracefully:

- **Unix systems**: Uses `os.execv()` to replace the Python process with the binary, preserving file descriptors and exit codes.
- **Windows systems**: Falls back to `subprocess.run()` to execute the static binary located at the downloaded path.

This architecture ensures that arguments are passed as a list (`[str(bin_path)] + sys.argv[1:]`), eliminating shell interpretation risks and making the tool behave like a native command-line utility.

## Invoking MCP Tools via CLI Mode

### Basic Syntax

All CLI invocations follow a consistent three-part pattern:

```bash
codebase-memory-mcp cli <tool_name> '<JSON-rpc-payload>'

```

The `<tool_name>` corresponds to any method exposed by the MCP server, and the JSON payload must match the tool's expected parameters exactly as documented in the protocol.

### Indexing Repositories

To populate the knowledge graph with a new codebase, use the `index_repository` tool with an absolute path:

```bash
codebase-memory-mcp cli index_repository '{"repo_path": "/home/alice/myproject"}'

```

This triggers the parser to extract functions, classes, and call relationships, storing them in the local graph database for subsequent queries.

### Querying the Graph

Search for specific code patterns using `search_graph` or arbitrary Cypher queries via `query_graph`:

```bash

# Find all functions matching a regex pattern

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

# Execute custom Cypher against the stored graph

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

```

### Tracing Code Paths

Analyze call hierarchies for impact analysis or onboarding using the `trace_path` tool:

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

```

The `direction` parameter accepts `"inbound"`, `"outbound"`, or `"both"` to control whether you see callers, callees, or the complete call graph.

## Advanced CLI Options

### Raw JSON Output

For integration with other Unix tools like `jq`, add the `--raw` flag to stream unformatted JSON:

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

```

This outputs the raw JSON-RPC response directly to stdout, allowing you to extract specific fields or pipe results into CI pipelines.

### Graph Visualization UI

To launch the interactive web interface instead of returning JSON, append the `--ui=true` flag to any command:

```bash
codebase-memory-mcp cli --ui=true search_graph '{"label": "Function"}'

```

This opens the graph visualization in your default browser, rendering nodes and edges extracted from the query results.

## Summary

- **CLI mode** in `codebase-memory-mcp` provides direct shell access to all 14 MCP tools without network overhead.
- The entry point in [`_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/_cli.py) handles binary execution via `execv` (Unix) or `subprocess.run` (Windows), ensuring POSIX-compliant exit codes.
- Use the pattern `cli <tool_name> '<JSON-payload>'` to invoke methods like `index_repository`, `search_graph`, and `trace_path`.
- Add `--raw` for machine-readable JSON pipelines or `--ui=true` for visual graph exploration.

## Frequently Asked Questions

### How do I list all available projects in the graph database?

Use the `list_projects` tool, which requires no payload:

```bash
codebase-memory-mcp cli list_projects

```

This returns a JSON array of all indexed repository names, helping you discover the exact identifiers needed for other queries.

### Can I use the CLI without installing the Python package?

No. The CLI functionality depends on the Python shim 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), which manages binary downloads and argument forwarding. While the underlying binary is standalone, the `cli` subcommand wrapper is only available through the pip-installed package or the install scripts at [`scripts/install.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/install.sh).

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

CLI mode invokes the same binary but bypasses the STDIO transport layer used by MCP clients. Instead of listening for JSON-RPC over stdin/stdout, the shim constructs the request internally and exits with the tool's return code. This makes CLI mode ideal for one-off commands and scripting, while the server mode is required for integration with Claude Desktop or other MCP clients.

### Why does my command fail with "binary not found" errors?

The [`_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/_cli.py) shim downloads the platform-specific binary on first run to a cached location. If this download fails or the cache is corrupted, the CLI cannot forward arguments. Ensure you have internet connectivity on first use, or manually verify the binary exists at the path returned by the package's internal downloader.