chore: import upstream snapshot with attribution

2026-07-13 12:24:33 +08:00
commit f213ec8976
2101 changed files with 494002 additions and 0 deletions
@@ -0,0 +1,126 @@
+lmcache kvcache
+===============
+
+The ``lmcache kvcache`` command manages KV cache state on a running LMCache
+server.
+
+.. code-block:: bash
+
+   lmcache kvcache <sub-command> [options]
+
+.. code-block:: text
+
+   $ 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.
+
+.. code-block:: bash
+
+   lmcache kvcache clear --url <MP_HTTP_URL>
+
+**Example:**
+
+.. code-block:: bash
+
+   $ lmcache kvcache clear --url http://localhost:8000
+
+   ================ KV Cache Clear ================
+   Status:                                       OK
+   ================================================
+
+**JSON output** (for scripting with ``jq``):
+
+.. code-block:: bash
+
+   $ lmcache kvcache clear --url http://localhost:8000 --format json
+   {
+     "title": "KV Cache Clear",
+     "metrics": {
+       "status": "OK"
+     }
+   }
+
+**Quiet mode** (exit code only, no output):
+
+.. code-block:: bash
+
+   $ lmcache kvcache clear -q --url http://localhost:8000
+   $ echo $?
+   0
+
+Options
+~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 10 65
+
+   * - 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
+~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 85
+
+   * - 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.
+
+.. code-block:: bash
+
+   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:**
+
+.. code-block:: bash
+
+   RESULT=$(lmcache kvcache clear --url http://localhost:8000 --format json)
+   STATUS=$(echo "$RESULT" | jq -r '.metrics.status')
+   echo "Clear status: $STATUS"