moss-cli 0.1.0__py3-none-any.whl

moss_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Moss CLI - Command-line interface for Moss semantic search."""
+
+__version__ = "0.1.0"

moss_cli/commands/doc.py

@@ -0,0 +1,101 @@
+"""moss doc {add, delete, get} commands."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from moss import MossClient, GetDocumentsOptions, MutationOptions
+
+from .. import output
+from ..config import resolve_credentials
+from ..documents import load_documents
+from ..job_waiter import wait_for_job
+
+console = Console()
+doc_app = typer.Typer(name="doc", help="Manage documents in an index")
+
+
+def _client(ctx: typer.Context) -> MossClient:
+    pid, pkey = resolve_credentials(
+        ctx.obj.get("project_id"), ctx.obj.get("project_key")
+    )
+    return MossClient(pid, pkey)
+
+
+@doc_app.command(name="add")
+def add(
+    ctx: typer.Context,
+    index_name: str = typer.Argument(..., help="Index name"),
+    file: str = typer.Option(..., "--file", "-f", help="Path to JSON/CSV document file, or '-' for stdin"),
+    upsert: bool = typer.Option(False, "--upsert", "-u", help="Update existing documents"),
+    wait: bool = typer.Option(False, "--wait", "-w", help="Wait for job to complete"),
+    poll_interval: float = typer.Option(2.0, "--poll-interval", help="Seconds between status checks"),
+) -> None:
+    """Add documents to an index."""
+    json_mode = ctx.obj.get("json_output", False)
+    client = _client(ctx)
+    docs = load_documents(file)
+
+    options = MutationOptions(upsert=True) if upsert else None
+
+    if not json_mode:
+        console.print(
+            f"Adding {len(docs)} document(s) to [cyan]{index_name}[/cyan]"
+            f"{' (upsert)' if upsert else ''}..."
+        )
+
+    result = asyncio.run(client.add_docs(index_name, docs, options))
+    output.print_mutation_result(result, json_mode=json_mode)
+
+    if wait:
+        asyncio.run(wait_for_job(client, result.job_id, poll_interval, json_mode))
+
+
+@doc_app.command(name="delete")
+def delete(
+    ctx: typer.Context,
+    index_name: str = typer.Argument(..., help="Index name"),
+    ids: str = typer.Option(..., "--ids", "-i", help="Comma-separated document IDs"),
+    wait: bool = typer.Option(False, "--wait", "-w", help="Wait for job to complete"),
+    poll_interval: float = typer.Option(2.0, "--poll-interval", help="Seconds between status checks"),
+) -> None:
+    """Delete documents from an index by ID."""
+    json_mode = ctx.obj.get("json_output", False)
+    client = _client(ctx)
+    doc_ids = [i.strip() for i in ids.split(",") if i.strip()]
+
+    if not doc_ids:
+        output.print_error("No document IDs provided.", json_mode=json_mode)
+        raise typer.Exit(1)
+
+    if not json_mode:
+        console.print(f"Deleting {len(doc_ids)} document(s) from [cyan]{index_name}[/cyan]...")
+
+    result = asyncio.run(client.delete_docs(index_name, doc_ids))
+    output.print_mutation_result(result, json_mode=json_mode)
+
+    if wait:
+        asyncio.run(wait_for_job(client, result.job_id, poll_interval, json_mode))
+
+
+@doc_app.command(name="get")
+def get(
+    ctx: typer.Context,
+    index_name: str = typer.Argument(..., help="Index name"),
+    ids: Optional[str] = typer.Option(None, "--ids", "-i", help="Comma-separated document IDs (omit for all)"),
+) -> None:
+    """Retrieve documents from an index."""
+    json_mode = ctx.obj.get("json_output", False)
+    client = _client(ctx)
+
+    options = None
+    if ids:
+        doc_ids = [i.strip() for i in ids.split(",") if i.strip()]
+        options = GetDocumentsOptions(doc_ids=doc_ids)
+
+    docs = asyncio.run(client.get_docs(index_name, options))
+    output.print_doc_table(docs, json_mode=json_mode)

moss_cli/commands/index.py

@@ -0,0 +1,92 @@
+"""moss index {create, list, get, delete} commands."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from moss import MossClient
+
+from .. import output
+from ..config import resolve_credentials
+from ..documents import load_documents
+from ..job_waiter import wait_for_job
+
+console = Console()
+index_app = typer.Typer(name="index", help="Manage indexes")
+
+
+def _client(ctx: typer.Context) -> MossClient:
+    pid, pkey = resolve_credentials(
+        ctx.obj.get("project_id"), ctx.obj.get("project_key")
+    )
+    return MossClient(pid, pkey)
+
+
+@index_app.command(name="create")
+def create(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Index name"),
+    file: str = typer.Option(..., "--file", "-f", help="Path to JSON/CSV document file, or '-' for stdin"),
+    model: Optional[str] = typer.Option(None, "--model", "-m", help="Model ID (default: moss-minilm)"),
+    wait: bool = typer.Option(False, "--wait", "-w", help="Wait for job to complete"),
+    poll_interval: float = typer.Option(2.0, "--poll-interval", help="Seconds between status checks"),
+) -> None:
+    """Create a new index with documents."""
+    json_mode = ctx.obj.get("json_output", False)
+    client = _client(ctx)
+    docs = load_documents(file)
+
+    if not json_mode:
+        console.print(f"Creating index [cyan]{name}[/cyan] with {len(docs)} document(s)...")
+
+    result = asyncio.run(client.create_index(name, docs, model))
+    output.print_mutation_result(result, json_mode=json_mode)
+
+    if wait:
+        asyncio.run(wait_for_job(client, result.job_id, poll_interval, json_mode))
+
+
+@index_app.command(name="list")
+def list_indexes(ctx: typer.Context) -> None:
+    """List all indexes."""
+    json_mode = ctx.obj.get("json_output", False)
+    client = _client(ctx)
+    indexes = asyncio.run(client.list_indexes())
+    output.print_index_table(indexes, json_mode=json_mode)
+
+
+@index_app.command(name="get")
+def get(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Index name"),
+) -> None:
+    """Get details of an index."""
+    json_mode = ctx.obj.get("json_output", False)
+    client = _client(ctx)
+    info = asyncio.run(client.get_index(name))
+    output.print_index_detail(info, json_mode=json_mode)
+
+
+@index_app.command(name="delete")
+def delete(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Index name"),
+    confirm: bool = typer.Option(False, "--confirm", "-y", help="Skip confirmation"),
+) -> None:
+    """Delete an index."""
+    json_mode = ctx.obj.get("json_output", False)
+    if not confirm and not json_mode:
+        typer.confirm(f"Delete index '{name}'?", abort=True)
+
+    client = _client(ctx)
+    result = asyncio.run(client.delete_index(name))
+
+    if result:
+        output.print_success(f"Index '{name}' deleted.", json_mode=json_mode)
+    else:
+        output.print_error(f"Failed to delete index '{name}'.", json_mode=json_mode)
+        raise typer.Exit(1)

moss_cli/commands/init_cmd.py

@@ -0,0 +1,52 @@
+"""moss init — interactive credential setup."""
+
+from __future__ import annotations
+
+import asyncio
+
+import typer
+from rich.console import Console
+from rich.prompt import Prompt
+
+from moss import MossClient
+
+from ..config import get_config_path, load_config, save_config
+
+console = Console()
+
+
+def init_command(
+    force: bool = typer.Option(False, "--force", help="Overwrite existing config"),
+) -> None:
+    """Save project credentials to ~/.moss/config.json."""
+    path = get_config_path()
+    if path.exists() and not force:
+        existing = load_config()
+        if existing.get("project_id"):
+            console.print(f"[yellow]Config already exists at {path}[/yellow]")
+            console.print(f"  Project ID: {existing['project_id'][:8]}...")
+            overwrite = Prompt.ask("Overwrite?", choices=["y", "n"], default="n")
+            if overwrite != "y":
+                raise typer.Abort()
+
+    project_id = Prompt.ask("Project ID")
+    project_key = Prompt.ask("Project Key", password=True)
+
+    if not project_id or not project_key:
+        console.print("[red]Both project ID and key are required.[/red]")
+        raise typer.Exit(1)
+
+    # Test credentials
+    console.print("[dim]Validating credentials...[/dim]")
+    try:
+        client = MossClient(project_id, project_key)
+        indexes = asyncio.run(client.list_indexes())
+        console.print(f"[green]Authenticated. Found {len(indexes)} index(es).[/green]")
+    except Exception as e:
+        console.print(f"[red]Authentication failed: {e}[/red]")
+        save_anyway = Prompt.ask("Save anyway?", choices=["y", "n"], default="n")
+        if save_anyway != "y":
+            raise typer.Exit(1)
+
+    save_config({"project_id": project_id, "project_key": project_key})
+    console.print(f"[green]Config saved to {path}[/green]")

moss_cli/commands/job.py

@@ -0,0 +1,42 @@
+"""moss job status command."""
+
+from __future__ import annotations
+
+import asyncio
+
+import typer
+from rich.console import Console
+
+from moss import MossClient
+
+from .. import output
+from ..config import resolve_credentials
+from ..job_waiter import wait_for_job
+
+console = Console()
+job_app = typer.Typer(name="job", help="Track background jobs")
+
+
+def _client(ctx: typer.Context) -> MossClient:
+    pid, pkey = resolve_credentials(
+        ctx.obj.get("project_id"), ctx.obj.get("project_key")
+    )
+    return MossClient(pid, pkey)
+
+
+@job_app.command(name="status")
+def status(
+    ctx: typer.Context,
+    job_id: str = typer.Argument(..., help="Job ID"),
+    wait: bool = typer.Option(False, "--wait", "-w", help="Poll until job completes"),
+    poll_interval: float = typer.Option(2.0, "--poll-interval", help="Seconds between status checks"),
+) -> None:
+    """Get the status of a background job."""
+    json_mode = ctx.obj.get("json_output", False)
+    client = _client(ctx)
+
+    if wait:
+        asyncio.run(wait_for_job(client, job_id, poll_interval, json_mode))
+    else:
+        result = asyncio.run(client.get_job_status(job_id))
+        output.print_job_status(result, json_mode=json_mode)

moss_cli/commands/search.py

@@ -0,0 +1,74 @@
+"""moss query command."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from moss import MossClient, QueryOptions
+
+from .. import output
+from ..config import resolve_credentials
+
+console = Console()
+
+
+def query_command(
+    ctx: typer.Context,
+    index_name: str = typer.Argument(..., help="Index name"),
+    query_text: Optional[str] = typer.Argument(None, help="Search query (reads from stdin if omitted)"),
+    top_k: int = typer.Option(10, "--top-k", "-k", help="Number of results"),
+    alpha: float = typer.Option(0.8, "--alpha", "-a", help="Semantic weight (0.0=keyword, 1.0=semantic)"),
+    filter_json: Optional[str] = typer.Option(None, "--filter", help="Metadata filter as JSON string"),
+    cloud: bool = typer.Option(False, "--cloud", "-c", help="Query via cloud API instead of downloading the index"),
+) -> None:
+    """Query an index. Downloads the index and queries on-device by default. Use --cloud to skip the download and query via the cloud API."""
+    json_mode = ctx.obj.get("json_output", False)
+
+    # Resolve query text
+    if query_text is None:
+        if sys.stdin.isatty():
+            output.print_error("No query provided. Pass as argument or pipe via stdin.", json_mode)
+            raise typer.Exit(1)
+        query_text = sys.stdin.read().strip()
+        if not query_text:
+            output.print_error("Empty query from stdin.", json_mode)
+            raise typer.Exit(1)
+
+    # Parse filter
+    parsed_filter = None
+    if filter_json:
+        try:
+            parsed_filter = json.loads(filter_json)
+        except json.JSONDecodeError as e:
+            output.print_error(f"Invalid --filter JSON: {e}", json_mode)
+            raise typer.Exit(1)
+
+    pid, pkey = resolve_credentials(
+        ctx.obj.get("project_id"), ctx.obj.get("project_key")
+    )
+    if cloud and parsed_filter:
+        output.print_error(
+            "Metadata filters are only supported for local queries. Remove --cloud or --filter.",
+            json_mode,
+        )
+        raise typer.Exit(1)
+
+    client = MossClient(pid, pkey)
+
+    async def _run() -> None:
+        if not cloud:
+            if not json_mode:
+                console.print(f"Loading index [cyan]{index_name}[/cyan] locally...")
+            await client.load_index(index_name)
+
+        options = QueryOptions(top_k=top_k, alpha=alpha, filter=parsed_filter)
+        result = await client.query(index_name, query_text, options)
+        output.print_search_results(result, json_mode=json_mode)
+
+    asyncio.run(_run())

moss_cli/commands/version.py

@@ -0,0 +1,24 @@
+"""moss version command."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+
+def version_command(ctx: typer.Context) -> None:
+    """Print CLI and SDK version information."""
+    import moss_cli
+    import moss
+
+    json_mode = ctx.obj.get("json_output", False)
+
+    if json_mode:
+        import json
+
+        print(json.dumps({"cli": moss_cli.__version__, "sdk": moss.__version__}))
+    else:
+        console.print(f"moss-cli  {moss_cli.__version__}")
+        console.print(f"moss SDK  {moss.__version__}")

moss_cli/config.py

@@ -0,0 +1,57 @@
+"""Auth resolution: CLI flags > env vars > config file."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Optional, Tuple
+
+import typer
+
+
+def get_config_path() -> Path:
+    return Path.home() / ".moss" / "config.json"
+
+
+def load_config() -> dict:
+    path = get_config_path()
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_config(data: dict) -> None:
+    path = get_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+
+
+def resolve_credentials(
+    project_id: Optional[str] = None,
+    project_key: Optional[str] = None,
+) -> Tuple[str, str]:
+    """Resolve credentials from flags, env vars, or config file."""
+    pid = project_id or os.getenv("MOSS_PROJECT_ID")
+    pkey = project_key or os.getenv("MOSS_PROJECT_KEY")
+
+    if pid and pkey:
+        return pid, pkey
+
+    config = load_config()
+    pid = pid or config.get("project_id")
+    pkey = pkey or config.get("project_key")
+
+    if not pid or not pkey:
+        raise typer.BadParameter(
+            "Missing credentials. Provide --project-id/--project-key, "
+            "set MOSS_PROJECT_ID/MOSS_PROJECT_KEY env vars, "
+            "or run 'moss init' to save them."
+        )
+    return pid, pkey

moss_cli/documents.py

@@ -0,0 +1,116 @@
+"""Load documents from JSON/CSV files or stdin."""
+
+from __future__ import annotations
+
+import csv
+import json
+import sys
+from pathlib import Path
+from typing import Any, List
+
+import typer
+from moss import DocumentInfo
+
+
+def load_documents(file_path: str) -> List[DocumentInfo]:
+    """Load documents from a JSON/CSV file or stdin ('-')."""
+    if file_path == "-":
+        raw = sys.stdin.read()
+        return _parse_json_docs(raw, source="stdin")
+
+    path = Path(file_path)
+    if not path.exists():
+        raise typer.BadParameter(f"File not found: {file_path}")
+
+    suffix = path.suffix.lower()
+    content = path.read_text()
+
+    if suffix == ".csv":
+        return _parse_csv_docs(content)
+    elif suffix == ".jsonl":
+        return _parse_jsonl_docs(content, source=file_path)
+    elif suffix == ".json":
+        return _parse_json_docs(content, source=file_path)
+    else:
+        return _parse_json_docs(content, source=file_path)
+
+
+def _parse_json_docs(raw: str, source: str = "input") -> List[DocumentInfo]:
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise typer.BadParameter(f"Invalid JSON in {source}: {e}")
+
+    if isinstance(data, dict):
+        data = data.get("documents", data.get("docs", []))
+
+    if not isinstance(data, list):
+        raise typer.BadParameter(
+            f"Expected a JSON array of documents, got {type(data).__name__}"
+        )
+
+    return [_dict_to_doc(d, i) for i, d in enumerate(data)]
+
+
+def _parse_jsonl_docs(raw: str, source: str = "input") -> List[DocumentInfo]:
+    docs = []
+    for line_no, line in enumerate(raw.splitlines(), start=1):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError as e:
+            raise typer.BadParameter(f"Invalid JSON on line {line_no} in {source}: {e}")
+        docs.append(_dict_to_doc(obj, line_no - 1))
+    return docs
+
+
+def _parse_csv_docs(content: str) -> List[DocumentInfo]:
+    reader = csv.DictReader(content.splitlines())
+    docs = []
+    for i, row in enumerate(reader):
+        if "id" not in row or "text" not in row:
+            raise typer.BadParameter(
+                f"CSV row {i + 1}: missing required 'id' or 'text' column"
+            )
+        metadata = None
+        if "metadata" in row and row["metadata"]:
+            try:
+                metadata = json.loads(row["metadata"])
+            except json.JSONDecodeError:
+                raise typer.BadParameter(
+                    f"CSV row {i + 1}: invalid JSON in 'metadata' column"
+                )
+
+        embedding = None
+        if "embedding" in row and row["embedding"]:
+            try:
+                embedding = json.loads(row["embedding"])
+            except json.JSONDecodeError:
+                raise typer.BadParameter(
+                    f"CSV row {i + 1}: invalid JSON in 'embedding' column"
+                )
+
+        docs.append(
+            DocumentInfo(
+                id=row["id"],
+                text=row["text"],
+                metadata=metadata,
+                embedding=embedding,
+            )
+        )
+    return docs
+
+
+def _dict_to_doc(d: Any, index: int) -> DocumentInfo:
+    if not isinstance(d, dict):
+        raise typer.BadParameter(f"Document at index {index}: expected object, got {type(d).__name__}")
+    if "id" not in d or "text" not in d:
+        raise typer.BadParameter(f"Document at index {index}: missing required 'id' or 'text' field")
+    return DocumentInfo(
+        id=str(d["id"]),
+        text=str(d["text"]),
+        metadata=d.get("metadata"),
+        embedding=d.get("embedding"),
+    )

moss_cli/job_waiter.py

@@ -0,0 +1,71 @@
+"""Poll job status with a rich progress bar."""
+
+from __future__ import annotations
+
+import asyncio
+
+from rich.console import Console
+from rich.live import Live
+from rich.spinner import Spinner
+from rich.text import Text
+
+from moss import MossClient
+
+from . import output
+
+console = Console()
+
+
+def _status_str(status_obj: object) -> str:
+    raw = status_obj.status.value if hasattr(status_obj.status, "value") else str(status_obj.status)
+    return raw.upper()
+
+
+def _progress_float(status_obj: object) -> float:
+    p = float(status_obj.progress)
+    return p / 100.0 if p > 1 else p
+
+
+async def wait_for_job(
+    client: MossClient,
+    job_id: str,
+    poll_interval: float = 2.0,
+    json_mode: bool = False,
+) -> None:
+    """Poll job status until terminal state, showing progress."""
+    terminal = {"COMPLETED", "FAILED"}
+
+    if json_mode:
+        while True:
+            status = await client.get_job_status(job_id)
+            status_val = _status_str(status)
+            if status_val in terminal:
+                output.print_job_status(status, json_mode=True)
+                if status_val == "FAILED":
+                    raise SystemExit(1)
+                return
+            await asyncio.sleep(poll_interval)
+
+    with Live(Spinner("dots", text="Waiting for job..."), console=console, transient=True) as live:
+        while True:
+            status = await client.get_job_status(job_id)
+            status_val = _status_str(status)
+
+            phase = getattr(status, "current_phase", None)
+            phase_str = ""
+            if phase is not None:
+                phase_str = f" ({phase.value if hasattr(phase, 'value') else str(phase)})"
+
+            progress_pct = f"{_progress_float(status):.0%}"
+            text = Text.from_markup(
+                f"[yellow]{status_val}[/yellow] {progress_pct}{phase_str}"
+            )
+            live.update(Spinner("dots", text=text))
+
+            if status_val in terminal:
+                break
+            await asyncio.sleep(poll_interval)
+
+    output.print_job_status(status, json_mode=False)
+    if status_val == "FAILED":
+        raise SystemExit(1)

moss_cli/main.py

@@ -0,0 +1,77 @@
+"""Main CLI entry point."""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from .commands.doc import doc_app
+from .commands.index import index_app
+from .commands.init_cmd import init_command
+from .commands.job import job_app
+from .commands.search import query_command
+from .commands.version import version_command
+from .output import print_error
+
+console = Console()
+
+app = typer.Typer(
+    name="moss",
+    help="Moss Semantic Search CLI",
+    add_completion=True,
+    no_args_is_help=True,
+)
+
+# Register subgroups
+app.add_typer(index_app, name="index", help="Manage indexes")
+app.add_typer(doc_app, name="doc", help="Manage documents")
+app.add_typer(job_app, name="job", help="Track background jobs")
+
+# Register top-level commands
+app.command(name="query")(query_command)
+app.command(name="init")(init_command)
+app.command(name="version")(version_command)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    project_id: Optional[str] = typer.Option(
+        None, "--project-id", "-p", envvar="MOSS_PROJECT_ID", help="Project ID"
+    ),
+    project_key: Optional[str] = typer.Option(
+        None, "--project-key", envvar="MOSS_PROJECT_KEY", help="Project key"
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Output as JSON"
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="Enable debug logging"
+    ),
+) -> None:
+    """Moss Semantic Search CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj["project_id"] = project_id
+    ctx.obj["project_key"] = project_key
+    ctx.obj["json_output"] = json_output
+
+    if verbose:
+        logging.basicConfig(level=logging.DEBUG)
+
+
+def run() -> None:
+    """Entry point for the console script."""
+    try:
+        app()
+    except (typer.Exit, typer.Abort, SystemExit):
+        raise
+    except Exception as e:
+        print_error(str(e))
+        raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+    run()

moss_cli/output.py

@@ -0,0 +1,221 @@
+"""Output formatting: tables, JSON, search results."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Dict, List
+
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _index_to_dict(info: Any) -> Dict[str, Any]:
+    return {
+        "id": info.id,
+        "name": info.name,
+        "version": info.version,
+        "status": info.status,
+        "doc_count": info.doc_count,
+        "created_at": info.created_at,
+        "updated_at": info.updated_at,
+        "model": {"id": info.model.id, "version": info.model.version},
+    }
+
+
+def _doc_to_dict(doc: Any) -> Dict[str, Any]:
+    d: Dict[str, Any] = {"id": doc.id, "text": doc.text}
+    meta = getattr(doc, "metadata", None)
+    if meta is not None:
+        d["metadata"] = dict(meta)
+    emb = getattr(doc, "embedding", None)
+    if emb is not None:
+        d["embedding"] = list(emb)
+    return d
+
+
+def _result_doc_to_dict(doc: Any) -> Dict[str, Any]:
+    d: Dict[str, Any] = {"id": doc.id, "text": doc.text, "score": doc.score}
+    meta = getattr(doc, "metadata", None)
+    if meta is not None:
+        d["metadata"] = dict(meta)
+    return d
+
+
+def _search_result_to_dict(result: Any) -> Dict[str, Any]:
+    return {
+        "query": result.query,
+        "index_name": result.index_name,
+        "time_taken_ms": result.time_taken_ms,
+        "docs": [_result_doc_to_dict(d) for d in result.docs],
+    }
+
+
+def _mutation_to_dict(result: Any) -> Dict[str, Any]:
+    return {
+        "job_id": result.job_id,
+        "index_name": result.index_name,
+        "doc_count": result.doc_count,
+    }
+
+
+def _job_status_to_dict(status: Any) -> Dict[str, Any]:
+    d: Dict[str, Any] = {
+        "job_id": status.job_id,
+        "status": status.status.value if hasattr(status.status, "value") else str(status.status),
+        "progress": status.progress,
+        "created_at": status.created_at,
+        "updated_at": status.updated_at,
+        "completed_at": status.completed_at,
+    }
+    phase = getattr(status, "current_phase", None)
+    if phase is not None:
+        d["current_phase"] = phase.value if hasattr(phase, "value") else str(phase)
+    else:
+        d["current_phase"] = None
+    error = getattr(status, "error", None)
+    if error is not None:
+        d["error"] = error
+    return d
+
+
+def _print_json(data: Any) -> None:
+    print(json.dumps(data, indent=2, default=str))
+
+
+# --- Public API ---
+
+
+def print_index_table(indexes: list, json_mode: bool = False) -> None:
+    if json_mode:
+        _print_json([_index_to_dict(i) for i in indexes])
+        return
+    if not indexes:
+        console.print("[dim]No indexes found.[/dim]")
+        return
+    table = Table(title="Indexes")
+    table.add_column("Name", style="cyan")
+    table.add_column("Status", style="green")
+    table.add_column("Docs", justify="right")
+    table.add_column("Model")
+    table.add_column("Created")
+    table.add_column("Updated")
+    for idx in indexes:
+        table.add_row(
+            idx.name,
+            idx.status,
+            str(idx.doc_count),
+            idx.model.id,
+            idx.created_at,
+            idx.updated_at,
+        )
+    console.print(table)
+
+
+def print_index_detail(info: Any, json_mode: bool = False) -> None:
+    if json_mode:
+        _print_json(_index_to_dict(info))
+        return
+    console.print(f"[bold cyan]Index:[/bold cyan] {info.name}")
+    console.print(f"  ID:         {info.id}")
+    console.print(f"  Status:     {info.status}")
+    console.print(f"  Documents:  {info.doc_count}")
+    console.print(f"  Model:      {info.model.id} v{info.model.version}")
+    console.print(f"  Version:    {info.version}")
+    console.print(f"  Created:    {info.created_at}")
+    console.print(f"  Updated:    {info.updated_at}")
+
+
+def print_doc_table(docs: list, json_mode: bool = False) -> None:
+    if json_mode:
+        _print_json([_doc_to_dict(d) for d in docs])
+        return
+    if not docs:
+        console.print("[dim]No documents found.[/dim]")
+        return
+    table = Table(title="Documents")
+    table.add_column("ID", style="cyan")
+    table.add_column("Text", max_width=80)
+    table.add_column("Metadata")
+    for doc in docs:
+        meta = getattr(doc, "metadata", None)
+        meta_str = json.dumps(dict(meta), default=str) if meta else ""
+        text = doc.text
+        if len(text) > 80:
+            text = text[:77] + "..."
+        table.add_row(doc.id, text, meta_str)
+    console.print(table)
+
+
+def print_search_results(result: Any, json_mode: bool = False) -> None:
+    if json_mode:
+        _print_json(_search_result_to_dict(result))
+        return
+    time_str = f" in {result.time_taken_ms}ms" if result.time_taken_ms else ""
+    console.print(
+        f'[bold]Query:[/bold] "{result.query}"  '
+        f"[dim]index={result.index_name}{time_str}[/dim]\n"
+    )
+    if not result.docs:
+        console.print("[dim]No results.[/dim]")
+        return
+    for i, doc in enumerate(result.docs, 1):
+        meta = getattr(doc, "metadata", None)
+        meta_str = f"  [dim]{json.dumps(dict(meta), default=str)}[/dim]" if meta else ""
+        console.print(f"[bold cyan]{i}.[/bold cyan] [green]{doc.score:.4f}[/green]  {doc.id}")
+        console.print(f"   {doc.text}")
+        if meta_str:
+            console.print(meta_str)
+        console.print()
+
+
+def print_mutation_result(result: Any, json_mode: bool = False) -> None:
+    if json_mode:
+        _print_json(_mutation_to_dict(result))
+        return
+    console.print(f"[green]Job submitted[/green]")
+    console.print(f"  Job ID:  {result.job_id}")
+    console.print(f"  Index:   {result.index_name}")
+    console.print(f"  Docs:    {result.doc_count}")
+
+
+def print_job_status(status: Any, json_mode: bool = False) -> None:
+    if json_mode:
+        _print_json(_job_status_to_dict(status))
+        return
+    status_val = (status.status.value if hasattr(status.status, "value") else str(status.status)).upper()
+    color = "green" if status_val == "COMPLETED" else "red" if status_val == "FAILED" else "yellow"
+    progress = float(status.progress)
+    if progress > 1:
+        progress /= 100.0
+    console.print(f"[bold]Job:[/bold] {status.job_id}")
+    console.print(f"  Status:   [{color}]{status_val}[/{color}]")
+    console.print(f"  Progress: {progress:.0%}")
+    phase = getattr(status, "current_phase", None)
+    if phase is not None:
+        phase_val = phase.value if hasattr(phase, "value") else str(phase)
+        console.print(f"  Phase:    {phase_val}")
+    error = getattr(status, "error", None)
+    if error:
+        console.print(f"  [red]Error: {error}[/red]")
+    console.print(f"  Created:  {status.created_at}")
+    console.print(f"  Updated:  {status.updated_at}")
+    if status.completed_at:
+        console.print(f"  Completed: {status.completed_at}")
+
+
+def print_success(message: str, json_mode: bool = False) -> None:
+    if json_mode:
+        _print_json({"status": "ok", "message": message})
+        return
+    console.print(f"[green]{message}[/green]")
+
+
+def print_error(message: str, json_mode: bool = False) -> None:
+    if json_mode:
+        print(json.dumps({"error": message}), file=sys.stderr)
+    else:
+        err_console.print(f"[red]{message}[/red]")

moss_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: moss-cli
+Version: 0.1.0
+Summary: Command-line interface for Moss semantic search
+Author-email: "InferEdge Inc." <contact@usemoss.dev>
+Keywords: search,semantic,cli,moss
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: moss>=1.0.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: isort>=5.0.0; extra == "dev"
+Requires-Dist: flake8>=7.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# Moss CLI
+
+**Command-line interface for Moss semantic search** — manage indexes, documents, and queries directly from your terminal.
+
+Moss CLI wraps the [Moss Python SDK](https://docs.usemoss.dev/) so you can build and query semantic search indexes without writing any code. Ideal for quick prototyping, scripting, CI/CD pipelines, and data workflows.
+
+## Features
+
+- ⚡ **Full SDK coverage** — every SDK operation available as a CLI command
+- 🔍 **Semantic search** — query indexes with configurable hybrid search (semantic + keyword)
+- 📦 **Index management** — create, list, inspect, and delete indexes
+- 📄 **Document management** — add, update, retrieve, and delete documents
+- 🚀 **Local by default** — downloads indexes for on-device queries, `--cloud` to skip
+- 🔧 **Flexible auth** — CLI flags, environment variables, or config file
+- 📊 **Multiple output formats** — rich tables for humans, `--json` for scripts
+- ⏳ **Job tracking** — poll background jobs with live progress display
+- 🔗 **Pipe-friendly** — stdin/stdout support for composing with other tools
+
+## Installation
+
+```bash
+pip install moss-cli
+```
+
+## Quick Start
+
+```bash
+# 1. Save your credentials
+moss init
+
+# 2. List your indexes
+moss index list
+
+# 3. Create an index from a JSON file
+moss index create my-index -f docs.json --wait
+
+# 4. Search it
+moss query my-index "what is machine learning"
+
+# 5. Search via cloud API (skips local download)
+moss query my-index "neural networks" --cloud
+```
+
+## Authentication
+
+Credentials are resolved in this order:
+
+1. **CLI flags**: `--project-id` and `--project-key`
+2. **Environment variables**: `MOSS_PROJECT_ID` and `MOSS_PROJECT_KEY`
+3. **Config file**: `~/.moss/config.json` (created by `moss init`)
+
+```bash
+# Option 1: Interactive setup (recommended)
+moss init
+
+# Option 2: Environment variables
+export MOSS_PROJECT_ID="your-project-id"
+export MOSS_PROJECT_KEY="your-project-key"
+
+# Option 3: Inline flags
+moss index list --project-id "..." --project-key "..."
+```
+
+## Commands
+
+### Index Management
+
+```bash
+# Create an index with documents from a JSON file
+moss index create my-index -f documents.json --model moss-minilm
+
+# Create and wait for completion
+moss index create my-index -f documents.json --wait
+
+# List all indexes
+moss index list
+
+# Get index details
+moss index get my-index
+
+# Delete an index
+moss index delete my-index
+moss index delete my-index --confirm  # skip prompt
+```
+
+### Document Management
+
+```bash
+# Add documents to an existing index
+moss doc add my-index -f new-docs.json
+
+# Add with upsert (update existing, insert new)
+moss doc add my-index -f docs.json --upsert --wait
+
+# Get all documents
+moss doc get my-index
+
+# Get specific documents
+moss doc get my-index --ids doc1,doc2,doc3
+
+# Delete documents
+moss doc delete my-index --ids doc1,doc2
+```
+
+### Query
+
+```bash
+# Search (downloads index and queries on-device by default)
+moss query my-index "what is deep learning"
+
+# Tune results: more results, keyword-heavy
+moss query my-index "neural networks" --top-k 20 --alpha 0.3
+
+# Cloud mode (skip download, query via cloud API)
+moss query my-index "transformers" --cloud
+
+# With metadata filter (local only)
+moss query my-index "shoes" --filter '{"field": "category", "condition": {"$eq": "footwear"}}'
+
+# Pipe query from stdin
+echo "what is AI" | moss query my-index
+
+# JSON output for scripting
+moss query my-index "query" --json | jq '.docs[0].text'
+```
+
+### Job Tracking
+
+```bash
+# Check job status
+moss job status <job-id>
+
+# Wait for job to finish (with live progress)
+moss job status <job-id> --wait
+```
+
+### Other
+
+```bash
+# Print version info
+moss version
+
+# Global JSON output
+moss index list --json
+moss doc get my-index --json
+```
+
+## Document File Format
+
+### JSON (recommended)
+
+```json
+[
+  {"id": "doc1", "text": "Machine learning fundamentals", "metadata": {"topic": "ml"}},
+  {"id": "doc2", "text": "Deep learning with neural networks"},
+  {"id": "doc3", "text": "Natural language processing", "metadata": {"topic": "nlp"}}
+]
+```
+
+Also supports a wrapper format: `{"documents": [...]}`.
+
+### CSV
+
+```csv
+id,text,metadata
+doc1,Machine learning fundamentals,"{""topic"": ""ml""}"
+doc2,Deep learning with neural networks,
+doc3,Natural language processing,"{""topic"": ""nlp""}"
+```
+
+### stdin
+
+```bash
+cat docs.json | moss index create my-index -f -
+cat docs.json | moss doc add my-index -f -
+```
+
+## Global Options
+
+| Flag | Short | Description |
+|---|---|---|
+| `--project-id` | `-p` | Project ID (overrides env/config) |
+| `--project-key` | | Project key (overrides env/config) |
+| `--json` | | Machine-readable JSON output |
+| `--verbose` | `-v` | Enable debug logging |
+
+## Available Models
+
+| Model | Description |
+|---|---|
+| `moss-minilm` | Lightweight, optimized for speed (default) |
+| `moss-mediumlm` | Balanced accuracy and performance |
+| `custom` | Used automatically when documents include embeddings |
+
+## License
+
+Copyright (c) 2026 InferEdge Inc. — PolyForm Shield License 1.0.0.
+
+See [LICENSE](LICENSE) for full terms. For commercial licensing, contact contact@usemoss.dev.

moss_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+moss_cli/__init__.py,sha256=sR54tN-3tE31q3Bx22CmeXpI6-hAAq9vJ-1nZV0VMow,89
+moss_cli/config.py,sha256=NBtpQNpw1S7SxfVjEZv-v3VIzbS6yvvf6d8kJVdz1aI,1529
+moss_cli/documents.py,sha256=Uj4IcOWpCn4GmvDY9Yoh4dd8Jq09vk0jp-OpWIEopNc,3656
+moss_cli/job_waiter.py,sha256=reVeioDD0aRBkWIrpYvKmLIe48-uXv_8nja2-nSAHR0,2124
+moss_cli/main.py,sha256=ERH1sfvJVEPQquNQiAgocdTIyathsq2yr20eyZRAPbQ,1989
+moss_cli/output.py,sha256=ValjrhEUVVUV0WFnFHidS0D8N1UOhGcKyLCbf1m8y7w,7265
+moss_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+moss_cli/commands/doc.py,sha256=tY2sA4m0qwHM33a72Dk0MDJw93qmQv0dvLdVKo7YFmI,3520
+moss_cli/commands/index.py,sha256=ASbJkF6W1KsrHLiFoUgIQAMaCcrK6ydTJuIETh-Lgko,2993
+moss_cli/commands/init_cmd.py,sha256=q9N6nDy76Wulippn45ys8LClIzZOqLqcUfYKW8JbZ1A,1812
+moss_cli/commands/job.py,sha256=BDdVdJTPYIg4VZ6VOYsmJby2KEK9AyiBUIDH9scqTWg,1201
+moss_cli/commands/search.py,sha256=MCkbhtzmSh6xSOSfb2ii4961BuwW39ge5Qlzjo9yo7o,2608
+moss_cli/commands/version.py,sha256=YJI0dE1jkxJrLl5F8fS_fFt2p8O6hGcHAx5LjBdg9go,565
+moss_cli-0.1.0.dist-info/licenses/LICENSE,sha256=vxxHLNz1Z_C_D6GyOS8mAyFwpjjSqkkkSnbp3BVIUks,191
+moss_cli-0.1.0.dist-info/METADATA,sha256=I934fiOyNlKmec7JP9fqCuh6AF0K6dSbbFt_YSXYVPg,6238
+moss_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+moss_cli-0.1.0.dist-info/entry_points.txt,sha256=xlsFrsY-yJUfEJZTTAtfPflXHI5STBkQL7JsDtr-I2g,43
+moss_cli-0.1.0.dist-info/top_level.txt,sha256=7Uft9WhtCk6F02s2ouw-avZ8qHIzRMM6bQQNvxSiyI0,9
+moss_cli-0.1.0.dist-info/RECORD,,

moss_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

moss_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+moss = moss_cli.main:run

moss_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2026 InferEdge Inc.
+
+Licensed under the PolyForm Shield License 1.0.0.
+https://polyformproject.org/licenses/shield/1.0.0
+
+For commercial licensing, contact contact@usemoss.dev.

moss_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+moss_cli