# How to Use CLI Mode MCP Tools from the Command Line

> Master the CLI mode MCP tools with DeusData's codebase Memory MCP package. This guide shows how to use command line arguments for seamless execution and platform compatibility.

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

---

**The Codebase Memory MCP package provides a Python shim in [`codebase_memory_mcp/_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/codebase_memory_mcp/_cli.py) that automatically downloads, verifies, and caches the correct native binary for your platform, securely forwarding all command-line arguments to the underlying MCP tools.**

The DeusData/codebase-memory-mcp repository delivers a production-ready command-line interface for managing Model Context Protocol (MCP) memory operations. When you use CLI mode MCP tools from the command line, a lightweight Python bootstrap shim handles cross-platform binary distribution, cryptographic verification, and secure execution without requiring manual toolchain management.

## Installation and Entry Points

Once installed via `pip install codebase-memory-mcp`, you can invoke the CLI through two equivalent methods:

- **Direct entry point**: `codebase-memory-mcp --help`
- **Module execution**: `python -m codebase_memory_mcp --version`

Both routes resolve to the `main()` function defined in [`pkg/pypi/src/codebase_memory_mcp/__main__.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/src/codebase_memory_mcp/__main__.py), which imports the bootstrap logic from [`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).

## How the CLI Shim Works

The shim executes an eight-step pipeline to safely provision and run the native MCP binary:

1. **Version Detection** – Queries `importlib.metadata.version` for the installed package version, falling back to the bundled `_version` string if metadata is unavailable.

2. **Platform Selection** – Inspects `sys.platform` (`linux`, `darwin`, `win32`) and `platform.machine()` (`arm64`, `amd64`) to construct the download URL targeting `https://github.com/DeusData/codebase-memory-mcp/releases/download/v{version}/{archive}`.

3. **URL Validation** – The `_validate_url_scheme` function enforces `https://` exclusively, preventing accidental file or ftp fetches.

4. **Binary Download** – Uses `urllib.request.urlretrieve` within a temporary directory, displaying progress messages like `codebase-memory-mcp: downloading v0.8.1 for linux/amd64...`.

5. **Checksum Verification** – The `_verify_checksum` function computes the SHA-256 hash of the downloaded archive and validates it against the official [`checksums.txt`](https://github.com/DeusData/codebase-memory-mcp/blob/main/checksums.txt) published for that release; mismatches trigger immediate abort.

6. **Safe Extraction** – Archives are processed by `_safe_extract_tar` and `_safe_extract_zip`, which sanitize file paths to prevent "zip-slip" directory traversal vulnerabilities.

7. **Binary Caching** – The extracted executable is copied to the directory returned by `_cache_dir` (typically `<platform-specific>/codebase-memory-mcp/{version}`), marked executable, and reused in future invocations.

8. **Process Execution** – On Unix, the shim uses `os.execv` to replace the Python process with the native binary; on Windows, it uses `subprocess.run`. All original `sys.argv` arguments forward directly without shell interpretation, eliminating injection risks.

## Running MCP Commands

After the initial download and caching, you can use CLI mode MCP tools command line operations transparently:

```bash

# Analyze a project directory

codebase-memory-mcp analyze --path ./my_project

# Check installed version

codebase-memory-mcp --version

# Alternative module invocation

python -m codebase_memory_mcp analyze --path ./src

```

First-time initialization displays download progress, while subsequent runs execute instantly from the cache located at paths like `$HOME/.cache/codebase-memory-mcp/0.8.1/codebase-memory-mcp`.

## Summary

- **The CLI 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) automates platform detection, secure downloading, and binary caching when you use CLI mode MCP tools from the command line.
- **Security features** include HTTPS-only URL validation (`_validate_url_scheme`), SHA-256 checksum verification (`_verify_checksum`), and path-traversal protection during extraction (`_safe_extract_tar`, `_safe_extract_zip`).
- **Entry points** include both the `codebase-memory-mcp` command and `python -m codebase_memory_mcp`, both triggering the same bootstrap logic in [`pkg/pypi/src/codebase_memory_mcp/__main__.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/src/codebase_memory_mcp/__main__.py).
- **Caching** occurs in per-user directories determined by `_cache_dir`, eliminating redundant network operations across sessions.
- **Execution** uses `os.execv` on Unix and `subprocess.run` on Windows, forwarding arguments directly without shell involvement.

## Frequently Asked Questions

### Where does the Codebase Memory MCP CLI store downloaded binaries?

The shim caches the native executable in a per-user directory determined by the `_cache_dir` function, typically resolving to `$HOME/.cache/codebase-memory-mcp/{version}/` on Linux, `~/Library/Caches/codebase-memory-mcp/{version}/` on macOS, or `%LOCALAPPDATA%\codebase-memory-mcp\{version}\` on Windows. This location is validated on every invocation, allowing subsequent runs to skip the download process entirely.

### How does the CLI verify the integrity of downloaded files?

According to the source code 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 `_verify_checksum` function calculates the SHA-256 hash of the downloaded archive and compares it against the expected hash listed in the release's [`checksums.txt`](https://github.com/DeusData/codebase-memory-mcp/blob/main/checksums.txt) file. If the hashes do not match, the process aborts immediately before extraction, preventing the execution of corrupted or malicious binaries.

### Can I run the tool without adding it to my system PATH?

Yes. You can invoke the CLI using Python's module execution syntax: `python -m codebase_memory_mcp [arguments]`. This method executes the `main()` function defined in [`codebase_memory_mcp/__main__.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/codebase_memory_mcp/__main__.py), which triggers the same download, caching, and execution logic as the direct `codebase-memory-mcp` entry point, making it ideal for virtual environments or CI pipelines where PATH modification is restricted.

### What platforms are supported by the CLI shim?

The shim automatically detects your operating system via `sys.platform` (`linux`, `darwin`, `win32`) and architecture via `platform.machine()` (`arm64`, `amd64`) to select the appropriate binary from the GitHub releases page. This platform-specific selection ensures you receive a native executable optimized for your system without manual intervention, as implemented in the `_download` logic of [`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).