From 365c30fbfe9faa603db7f18083490d42fc9be407 Mon Sep 17 00:00:00 2001
From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>
Date: Tue, 7 Apr 2026 07:55:47 -0500
Subject: [PATCH] docs infer cli examples and alias note

---
 docs/cli/capability.md | 76 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 74 insertions(+), 2 deletions(-)

diff --git a/docs/cli/capability.md b/docs/cli/capability.md
index 9128681fc69..45ff06258f2 100644
--- a/docs/cli/capability.md
+++ b/docs/cli/capability.md
@@ -10,10 +10,26 @@ title: "Inference CLI"
 
 `openclaw infer` is the canonical headless surface for provider-backed inference workflows.
 
-`openclaw capability` remains supported as a fallback alias for compatibility.
-
 It intentionally exposes capability families, not raw gateway RPC names and not raw agent tool ids.
 
+## Common tasks
+
+This table maps common inference tasks to the corresponding infer command.
+
+| If the user wants to...         | Use this command                                                       |
+| ------------------------------- | ---------------------------------------------------------------------- |
+| run a text/model prompt         | `openclaw infer model run --prompt "..." --json`                       |
+| list configured model providers | `openclaw infer model providers --json`                                |
+| generate an image               | `openclaw infer image generate --prompt "..." --json`                  |
+| describe an image file          | `openclaw infer image describe --file ./image.png --json`              |
+| transcribe audio                | `openclaw infer audio transcribe --file ./memo.m4a --json`             |
+| synthesize speech               | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` |
+| generate a video                | `openclaw infer video generate --prompt "..." --json`                  |
+| describe a video file           | `openclaw infer video describe --file ./clip.mp4 --json`               |
+| search the web                  | `openclaw infer web search --query "..." --json`                       |
+| fetch a web page                | `openclaw infer web fetch --url https://example.com --json`            |
+| create embeddings               | `openclaw infer embedding create --text "..." --json`                  |
+
 ## Command tree
 
 ```text
@@ -65,6 +81,35 @@ It intentionally exposes capability families, not raw gateway RPC names and not
     providers
 ```
 
+## Examples
+
+These examples show the standard command shape across the infer surface.
+
+```bash
+openclaw infer list --json
+openclaw infer inspect --name image.generate --json
+openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
+openclaw infer model providers --json
+openclaw infer image generate --prompt "friendly lobster illustration" --json
+openclaw infer image describe --file ./photo.jpg --json
+openclaw infer audio transcribe --file ./memo.m4a --json
+openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json
+openclaw infer video generate --prompt "cinematic sunset over the ocean" --json
+openclaw infer video describe --file ./clip.mp4 --json
+openclaw infer web search --query "OpenClaw docs" --json
+openclaw infer embedding create --text "friendly lobster" --json
+```
+
+## Additional examples
+
+```bash
+openclaw infer audio transcribe --file ./team-sync.m4a --language en --prompt "Focus on names and action items" --json
+openclaw infer image describe --file ./ui-screenshot.png --model openai/gpt-4.1-mini --json
+openclaw infer tts convert --text "Your build is complete" --output ./build-complete.mp3 --json
+openclaw infer web search --query "OpenClaw docs infer web providers" --json
+openclaw infer embedding create --text "customer support ticket: delayed shipment" --model openai/text-embedding-3-large --json
+```
+
 ## Transport
 
 Supported transport flags:
@@ -86,6 +131,14 @@ openclaw infer tts status --json
 openclaw infer embedding create --text "hello world" --json
 ```
 
+## Usage notes
+
+- `openclaw infer ...` is the primary CLI surface for these workflows.
+- Use `--json` when the output will be consumed by another command or script.
+- Use `--provider` or `--model provider/model` when a specific backend is required.
+- For `image describe`, `audio transcribe`, and `video describe`, `--model` must use the form `<provider/model>`.
+- The normal local path does not require the gateway to be running.
+
 ## JSON output
 
 Capability commands normalize JSON output under a shared envelope:
@@ -113,7 +166,26 @@ Top-level fields are stable:
 - `outputs`
 - `error`
 
+## Common pitfalls
+
+```bash
+# Bad
+openclaw infer media image generate --prompt "friendly lobster"
+
+# Good
+openclaw infer image generate --prompt "friendly lobster"
+```
+
+```bash
+# Bad
+openclaw infer audio transcribe --file ./memo.m4a --model whisper-1 --json
+
+# Good
+openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json
+```
+
 ## Notes
 
 - `model run` reuses the agent runtime so provider/model overrides behave like normal agent execution.
 - `tts status` defaults to gateway because it reflects gateway-managed TTS state.
+- `openclaw capability ...` is an alias for `openclaw infer ...`.