CLI Reference

LMCache provides a unified lmcache command-line interface for interacting with KV cache servers, running benchmarks, and inspecting cache state.

lmcache <command> [options]

Quick Start

After installing LMCache, the lmcache command is available:

# Show available commands
lmcache -h

# Run the example mock command
lmcache mock --name my-run --num-items 5

# JSON on stdout (for scripts)
lmcache mock --name my-run --format json

# Save metrics to a file (format follows --format, default: terminal)
lmcache mock --name my-run --num-items 5 --format json --output result.json

Available Commands

Command	Description
mock	Example command that outputs fake metrics. Useful for testing the CLI framework and as a reference for new commands.

Metrics Output

All commands that produce metrics support two output formats:

Terminal Output

Human-readable ASCII table matching the vllm bench serve style:

============= Mock Result ==============
----------- Input Parameters -----------
Name:                           test-run
Num items:                             5
------------- Mock Metrics -------------
Items processed:                      42
Total time (ms):                   12.34
Throughput (items/s):            3403.73
-------------- Validation --------------
Status:                               OK
========================================

JSON Output

Machine-readable output with structured keys, available via --format json (stdout) or --output (file):

lmcache mock --name test-run --output result.json

{
  "title": "Mock Result",
  "metrics": {
    "input": {
      "name": "test-run",
      "num_items": 5
    },
    "mock": {
      "items_processed": 42,
      "total_time_ms": 12.34,
      "throughput": 3403.73
    },
    "validation": {
      "status": "OK"
    }
  }
}

The terminal output uses human-readable labels (e.g., "Total time (ms)"), while the JSON output uses machine-readable keys (e.g., "total_time_ms").

Adding New Commands

New CLI subcommands can be added by creating a BaseCommand subclass and registering it. See Extending the CLI for details.