CCMD(1)

NAME
ccmd - browse and manage cache directories

SYNOPSIS
ccmd [-r path] [-s field] [--no-confirm] [--vulncheck] [--versioncheck]

ccmd mcp

DESCRIPTION
ccmd (Cache Commander) is a terminal user interface for exploring, analyzing, and cleaning up cache directories. It scans common cache locations, displays a navigable tree of cached data sorted by size, and lets you selectively delete entries to reclaim disk space.

Security features include vulnerability scanning via OSV.dev and version checking against upstream package registries.

The mcp subcommand starts an MCP (Model Context Protocol) server on stdio, allowing AI assistants like Claude to query and manage caches programmatically. Requires the binary to be built with the mcp feature flag.

OPTIONS

-r, --root=path
    Cache root directory to scan. Can be specified multiple times. Overrides roots from the configuration file. If omitted, default roots are used (see CONFIGURATION below).

-s, --sort=field
    Initial sort field: size (default), name, or modified.

--no-confirm
    Skip the confirmation prompt when deleting entries.

--vulncheck
    Enable vulnerability scanning. Queries OSV.dev for known vulnerabilities in cached packages.

--versioncheck
    Enable version checking. Queries package registries to identify outdated cached packages.

KEYBINDINGS

  Navigation

j/Down
    Move cursor down.

k/Up
    Move cursor up.

l/Right
    Expand node.

h/Left
    Collapse node.

Enter
    Toggle expand/collapse.

g   Jump to top.

G   Jump to bottom.

/   Filter by name (hides non-matching entries).

  Selection

Space
    Toggle mark on current entry.

Shift+Space
    Unmark all entries.

u   Unmark all entries.

  Security

v   Scan selected entry for vulnerabilities (via OSV.dev).

V   Scan all entries for vulnerabilities.

o   Check selected entry for outdated versions.

O   Check all entries for outdated versions.

f   Cycle status filter (none → vuln → outdated → vuln+outdated).

c   Copy upgrade command to clipboard.

  Actions

d/D Delete marked entries. Does nothing if no entries are marked.

m   Mark all visible (non-dimmed) items for deletion.

s   Cycle sort field (size → name → modified).

r   Refresh selected entry.

R   Full rescan of all roots.

?   Show in-app help screen.

q / Ctrl+C
    Quit.

CONFIGURATION
ccmd reads its configuration from:

    ~/.config/ccmd/config.toml

Example configuration:

    roots = ["~/.cache", "~/Library/Caches"]
    sort_by = "size"
    sort_desc = true
    confirm_delete = true
    [vulncheck]
    enabled = false
    [versioncheck]
    enabled = false

CLI options override the corresponding configuration values.

SUPPORTED CACHES
ccmd recognizes and provides rich metadata for the following cache ecosystems:

Provider | Typical location
Bun | ~/.bun/install/cache
Cargo | ~/.cargo/registry
Chroma | ~/.cache/chroma
GitHub CLI | ~/.cache/gh
Homebrew | ~/Library/Caches/Homebrew
HuggingFace Hub | ~/.cache/huggingface
npm | ~/.npm
pip | ~/.cache/pip
pnpm | ~/.local/share/pnpm/store
pre-commit | ~/.cache/pre-commit
Prisma | ~/.cache/prisma
PyTorch | ~/.cache/torch
uv | ~/.cache/uv
Whisper | ~/.cache/whisper
Yarn | ~/.yarn-cache, ~/.yarn/berry/cache

Unrecognized directories are displayed with generic metadata. Entries for known providers include a safety indicator: ● (safe to delete), ◐ (caution), or ○ (unsafe).

MCP SERVER
When invoked as ccmd mcp (requires the mcp feature flag), the binary starts an MCP server using stdio transport. The server exposes these tools:

list_caches
    List all cache directories with size and item count per provider.

get_summary
    High-level dashboard of total cache usage.

search_packages
    Find packages by name with optional ecosystem filter.

get_package_details
    Full metadata for a specific cache entry.

scan_vulnerabilities
    Check for known CVEs via OSV.dev.

check_outdated
    Check for available version updates from package registries.

preview_delete
    Dry-run showing what would be deleted.

delete_packages
    Delete cache entries with safety enforcement.

Deletions through MCP enforce a safety system: Safe entries are deleted directly, Caution entries require explicit confirmation, and Unsafe entries are rejected.

EXIT STATUS

0   Normal exit.

1   An error occurred.

BUGS
Report bugs at https://github.com/juliensimon/cache-commander/issues.

AUTHOR
Julien Simon <julien@julien.org>

SEE ALSO
du(1), ncdu(1)