lmcache kvcache

The lmcache kvcache command manages KV cache state on a running LMCache server.

lmcache kvcache <sub-command> [options]

$ lmcache kvcache -h
usage: lmcache kvcache [-h] [--format FORMAT] [--output PATH] [-q] {clear} ...

Manage KV cache state.

subcommands:
  clear          Clear all cached KV data in L1 (CPU)

options:
  -h, --help       show this help message and exit
  --format FORMAT  Stdout output format (default: terminal). Available: terminal, json.
  --output PATH    Save metrics to a file at PATH (format chosen by --format).
  -q, --quiet      Suppress stdout output. Exit code only.

clear

Clear all cached KV data in L1 (CPU memory) on the target LMCache server.

lmcache kvcache clear --url <MP_HTTP_URL>

Example:

$ lmcache kvcache clear --url http://localhost:8000

========== KV Cache Clear ==================
Status:                                   OK
=============================================

JSON output (for scripting with jq):

$ lmcache kvcache clear --url http://localhost:8000 --format json
{
  "title": "KV Cache Clear",
  "metrics": {
    "status": "OK"
  }
}

Quiet mode (exit code only, no output):

$ lmcache kvcache clear -q --url http://localhost:8000
$ echo $?
0

Options

Flag	Required	Description
--url	Yes	URL of the LMCache MP HTTP server (e.g. http://localhost:8000).
--format	No	Output format: terminal (default) or json.
--output	No	Save output to a file (uses the format chosen by --format).
-q / --quiet	No	Suppress stdout. Useful in scripts where you only need the exit code.

Exit Codes

Code	Meaning
0	Success.
1	Error (connection failure, server error, bad arguments).

Common Patterns

Handle temporary server unavailability:

If the server is temporarily unreachable (e.g. due to network issue), the command fails with exit code 1. For persistent connectivity issues, use lmcache ping to diagnose.

if lmcache kvcache clear -q --url http://localhost:8000; then
    echo "Cache cleared"
else
    echo "Clear failed — server temporarily unreachable, retrying later"
fi

Clear cache and capture JSON result:

RESULT=$(lmcache kvcache clear --url http://localhost:8000 --format json)
STATUS=$(echo "$RESULT" | jq -r '.metrics.status')
echo "Clear status: $STATUS"