docs: align cli args and README

README.md

@@ -484,10 +484,10 @@ leann list
 ```
 
 **Key CLI features:**
-- Auto-detects document formats (PDF, TXT, MD, DOCX)
+- Auto-detects document formats (PDF, TXT, MD, DOCX, PPTX + code files)
 - Smart text chunking with overlap
 - Multiple LLM providers (Ollama, OpenAI, HuggingFace)
-- Organized index storage in `~/.leann/indexes/`
+- Organized index storage in `.leann/indexes/` (project-local)
 - Support for advanced search parameters
 
 <details>
@@ -497,7 +497,7 @@ You can use `leann --help`, or `leann build --help`, `leann search --help`, `lea
 
 **Build Command:**
 ```bash
-leann build INDEX_NAME --docs DIRECTORY [OPTIONS]
+leann build INDEX_NAME --docs DIRECTORY|FILE [DIRECTORY|FILE ...] [OPTIONS]
 
 Options:
   --backend {hnsw,diskann}     Backend to use (default: hnsw)

packages/leann-core/src/leann/cli.py

@@ -72,7 +72,7 @@ class LeannCLI:
     def create_parser(self) -> argparse.ArgumentParser:
         parser = argparse.ArgumentParser(
             prog="leann",
-            description="LEANN - Local Enhanced AI Navigation",
+            description="The smallest vector index in the world. RAG Everything with LEANN!",
             formatter_class=argparse.RawDescriptionHelpFormatter,
             epilog="""
 Examples:
@@ -102,9 +102,18 @@ Examples:
             help="Documents directories and/or files (default: current directory)",
         )
         build_parser.add_argument(
-            "--backend", type=str, default="hnsw", choices=["hnsw", "diskann"]
+            "--backend",
+            type=str,
+            default="hnsw",
+            choices=["hnsw", "diskann"],
+            help="Backend to use (default: hnsw)",
+        )
+        build_parser.add_argument(
+            "--embedding-model",
+            type=str,
+            default="facebook/contriever",
+            help="Embedding model (default: facebook/contriever)",
         )
-        build_parser.add_argument("--embedding-model", type=str, default="facebook/contriever")
         build_parser.add_argument(
             "--embedding-mode",
             type=str,
@@ -112,21 +121,27 @@ Examples:
             choices=["sentence-transformers", "openai", "mlx", "ollama"],
             help="Embedding backend mode (default: sentence-transformers)",
         )
-        build_parser.add_argument("--force", "-f", action="store_true", help="Force rebuild")
+        build_parser.add_argument(
-        build_parser.add_argument("--graph-degree", type=int, default=32)
+            "--force", "-f", action="store_true", help="Force rebuild existing index"
-        build_parser.add_argument("--complexity", type=int, default=64)
+        )
+        build_parser.add_argument(
+            "--graph-degree", type=int, default=32, help="Graph degree (default: 32)"
+        )
+        build_parser.add_argument(
+            "--complexity", type=int, default=64, help="Build complexity (default: 64)"
+        )
         build_parser.add_argument("--num-threads", type=int, default=1)
         build_parser.add_argument(
             "--compact",
             action=argparse.BooleanOptionalAction,
             default=True,
-            help="Use compact index storage (default: enabled). Use --no-compact to disable and store full embeddings.",
+            help="Use compact storage (default: true). Must be `no-compact` for `no-recompute` build.",
         )
         build_parser.add_argument(
             "--recompute",
             action=argparse.BooleanOptionalAction,
             default=True,
-            help="Enable embedding recomputation (default: enabled). Use --no-recompute to store full embeddings and speed up queries.",
+            help="Enable recomputation (default: true)",
         )
         build_parser.add_argument(
             "--file-types",
@@ -138,8 +153,12 @@ Examples:
         search_parser = subparsers.add_parser("search", help="Search documents")
         search_parser.add_argument("index_name", help="Index name")
         search_parser.add_argument("query", help="Search query")
-        search_parser.add_argument("--top-k", type=int, default=5)
+        search_parser.add_argument(
-        search_parser.add_argument("--complexity", type=int, default=64)
+            "--top-k", type=int, default=5, help="Number of results (default: 5)"
+        )
+        search_parser.add_argument(
+            "--complexity", type=int, default=64, help="Search complexity (default: 64)"
+        )
         search_parser.add_argument("--beam-width", type=int, default=1)
         search_parser.add_argument("--prune-ratio", type=float, default=0.0)
         search_parser.add_argument(
@@ -147,12 +166,13 @@ Examples:
             dest="recompute_embeddings",
             action=argparse.BooleanOptionalAction,
             default=True,
-            help="Enable/disable embedding recomputation during search (default: enabled)",
+            help="Enable/disable embedding recomputation (default: enabled). Should not do a `no-recompute` search in a `recompute` build.",
         )
         search_parser.add_argument(
             "--pruning-strategy",
             choices=["global", "local", "proportional"],
             default="global",
+            help="Pruning strategy (default: global)",
         )
 
         # Ask command
@@ -163,11 +183,18 @@ Examples:
             type=str,
             default="ollama",
             choices=["simulated", "ollama", "hf", "openai"],
+            help="LLM provider (default: ollama)",
+        )
+        ask_parser.add_argument(
+            "--model", type=str, default="qwen3:8b", help="Model name (default: qwen3:8b)"
         )
-        ask_parser.add_argument("--model", type=str, default="qwen3:8b")
         ask_parser.add_argument("--host", type=str, default="http://localhost:11434")
-        ask_parser.add_argument("--interactive", "-i", action="store_true")
+        ask_parser.add_argument(
-        ask_parser.add_argument("--top-k", type=int, default=20)
+            "--interactive", "-i", action="store_true", help="Interactive chat mode"
+        )
+        ask_parser.add_argument(
+            "--top-k", type=int, default=20, help="Retrieval count (default: 20)"
+        )
         ask_parser.add_argument("--complexity", type=int, default=32)
         ask_parser.add_argument("--beam-width", type=int, default=1)
         ask_parser.add_argument("--prune-ratio", type=float, default=0.0)