applied-cli 0.1.0__py3-none-any.whl

applied_cli/commands/discover.py

@@ -0,0 +1,1006 @@
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+
+from applied_cli.commands._parsers import (
+    parse_optional_bool,
+    validate_uuid,
+)
+from applied_cli.error_reporting import render_api_error
+from applied_cli.http import (
+    APIError,
+    create_conversation_benchmark,
+    create_conversation_scenario,
+    create_scenario_run,
+    delete_conversation,
+    delete_conversation_benchmark,
+    delete_conversation_scenario,
+    get_conversation,
+    import_conversations_bulk,
+    get_conversation_benchmark,
+    get_conversation_scenario,
+    get_scenario_run,
+    list_conversation_benchmarks,
+    list_conversation_messages,
+    list_conversation_references,
+    list_conversation_scenarios,
+    list_conversations,
+    list_scenario_runs,
+    patch_conversation_scenario,
+    patch_scenario_run,
+)
+from applied_cli.runtime import resolve_runtime
+
+conversations_app = typer.Typer(help="List and inspect conversations.")
+benchmarks_app = typer.Typer(help="List and inspect test coverage benchmarks.")
+scenarios_app = typer.Typer(help="Manage test scenarios.")
+runs_app = typer.Typer(help="Manage scenario runs.")
+
+
+def _emit(items: Any, as_json: bool) -> None:
+    if as_json:
+        typer.echo(json.dumps(items, indent=2, default=str))
+        return
+    if isinstance(items, list):
+        if not items:
+            typer.echo("No results.")
+            return
+        for item in items:
+            if isinstance(item, dict):
+                row: list[str] = []
+                identifier = item.get("id")
+                if identifier is not None:
+                    row.append(f"id={identifier}")
+                name = item.get("name")
+                if name:
+                    row.append(f"name={name}")
+                item_type = item.get("type") or item.get("target_type")
+                if item_type:
+                    row.append(f"type={item_type}")
+                pass_status = item.get("pass_status")
+                if pass_status:
+                    row.append(f"pass_status={pass_status}")
+                csat_score = item.get("csat_score")
+                if csat_score is not None:
+                    row.append(f"csat_score={csat_score}")
+                created_at = item.get("created_at")
+                if created_at:
+                    row.append(f"created_at={created_at}")
+                typer.echo(" | ".join(row))
+            else:
+                typer.echo(str(item))
+        return
+    typer.echo(json.dumps(items, indent=2, default=str))
+
+
+def _require_option(value: Optional[str], *, option: str, example: str) -> str:
+    if value:
+        return value
+    raise typer.BadParameter(
+        f"{option} is required. Example: {example}",
+        param_hint=option,
+    )
+
+
+def _parse_optional_pass_status(raw: Optional[str]) -> Optional[str]:
+    if raw is None:
+        return None
+    value = raw.strip().lower()
+    if value not in {"pass", "fail"}:
+        raise typer.BadParameter("pass-status must be one of: pass, fail.")
+    return value
+
+
+def _is_test_conversation(row: dict[str, Any]) -> bool:
+    is_test = row.get("is_test")
+    if isinstance(is_test, bool):
+        return is_test
+    metadata = row.get("metadata")
+    if isinstance(metadata, dict) and isinstance(metadata.get("is_test"), bool):
+        return metadata["is_test"]
+    return False
+
+
+@conversations_app.command(
+    "list",
+    help=(
+        "List conversations. Example: applied-cli conversations list --agent-id <uuid> "
+        "--is-test true --limit 20"
+    ),
+)
+def conversations_list(
+    agent_id: Optional[str] = typer.Option(
+        None, "--agent-id", "--agent", help="Filter by agent UUID."
+    ),
+    is_test: Optional[str] = typer.Option(
+        None, help="Filter by test flag: true/false."
+    ),
+    limit: int = typer.Option(20, help="Maximum number of results."),
+    ordering: str = typer.Option("-created_at", help="Ordering, e.g. -created_at."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    if agent_id:
+        validate_uuid(agent_id, field_name="agent-id")
+    parsed_is_test = parse_optional_bool(is_test, field_name="is-test")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        rows = list_conversations(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+            is_test=parsed_is_test,
+            limit=limit,
+            ordering=ordering,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="list conversations"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(rows, output_json)
+
+
+@conversations_app.command(
+    "describe",
+    help=(
+        "Describe one conversation and optional transcript. Example: applied-cli conversations "
+        "describe --conversation-id <uuid> --include-references"
+    ),
+)
+@conversations_app.command(
+    "show",
+    help=(
+        "Show one conversation and optional transcript. Example: applied-cli conversations show "
+        "--conversation-id <uuid> --include-references"
+    ),
+)
+def conversations_show(
+    conversation_id: Optional[str] = typer.Option(
+        None, "--conversation-id", "--conversation", "--id", help="Conversation UUID."
+    ),
+    include_messages: bool = typer.Option(
+        True, "--include-messages/--no-include-messages", help="Include transcript."
+    ),
+    include_references: bool = typer.Option(
+        False,
+        "--include-references/--no-include-references",
+        help="Include message references.",
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    conversation_id = _require_option(
+        conversation_id,
+        option="--conversation-id",
+        example="applied-cli conversations show --conversation-id <uuid>",
+    )
+    validate_uuid(conversation_id, field_name="conversation-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        conversation = get_conversation(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            conversation_id=conversation_id,
+        )
+        messages: list[dict[str, Any]] = []
+        references: list[dict[str, Any]] = []
+        if include_messages:
+            messages = list_conversation_messages(
+                base_url=resolved_base_url,
+                shop_id=resolved_shop_id,
+                api_token=resolved_token,
+                conversation_id=conversation_id,
+            )
+        if include_references:
+            references = list_conversation_references(
+                base_url=resolved_base_url,
+                shop_id=resolved_shop_id,
+                api_token=resolved_token,
+                conversation_id=conversation_id,
+            )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="show conversation"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    payload: dict[str, Any] = {"conversation": conversation}
+    if include_messages:
+        payload["messages"] = messages
+    if include_references:
+        payload["references"] = references
+    _emit(payload, output_json)
+
+
+@conversations_app.command(
+    "references",
+    help=(
+        "List message references for a conversation. Example: applied-cli conversations references "
+        "--conversation-id <uuid>"
+    ),
+)
+def conversations_references(
+    conversation_id: Optional[str] = typer.Option(
+        None, "--conversation-id", "--conversation", "--id", help="Conversation UUID."
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    conversation_id = _require_option(
+        conversation_id,
+        option="--conversation-id",
+        example="applied-cli conversations references --conversation-id <uuid>",
+    )
+    validate_uuid(conversation_id, field_name="conversation-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        references = list_conversation_references(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            conversation_id=conversation_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="list conversation references"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(references, output_json)
+
+
+@conversations_app.command(
+    "delete",
+    help=(
+        "Delete a test conversation only. Example: applied-cli conversations delete "
+        "--conversation-id <uuid> --yes"
+    ),
+)
+def conversations_delete(
+    conversation_id: Optional[str] = typer.Option(
+        None, "--conversation-id", "--conversation", "--id", help="Conversation UUID."
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    conversation_id = _require_option(
+        conversation_id,
+        option="--conversation-id",
+        example="applied-cli conversations delete --conversation-id <uuid> --yes",
+    )
+    validate_uuid(conversation_id, field_name="conversation-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        row = get_conversation(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            conversation_id=conversation_id,
+        )
+        if not _is_test_conversation(row):
+            raise typer.BadParameter(
+                "Only test conversations can be deleted. This conversation is not marked is_test=true."
+            )
+        if not yes and not typer.confirm(
+            f"Delete test conversation {conversation_id} in shop {resolved_shop_id}?"
+        ):
+            raise typer.Exit(code=1)
+        delete_conversation(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            conversation_id=conversation_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="delete test conversation"), err=True)
+        raise typer.Exit(code=1) from exc
+    payload = {"deleted": True, "resource": "conversation", "id": conversation_id}
+    if output_json:
+        typer.echo(json.dumps(payload, indent=2))
+    else:
+        typer.echo(f"result=success | deleted=true | resource=conversation | id={conversation_id}")
+
+
+@conversations_app.command(
+    "import",
+    help=(
+        "Import historical conversations from CSV file/URL. Example: applied-cli conversations "
+        "import --agent-id <uuid> --file-path ./historical.csv --process-labels. "
+        "Expected CSV headers: ID, DATE_CREATED, SENDER, TYPE, MESSAGE_DATE, BODY, TITLE, TOPIC, "
+        "INTENT, SENTIMENT, SENTIMENT_SCORE. CONTACT_PHONE is optional; importer now normalizes or fills placeholders."
+    ),
+)
+def conversations_import(
+    agent_id: str = typer.Option(..., "--agent-id", "--agent", "--id", help="Target agent UUID."),
+    file_path: Optional[str] = typer.Option(
+        None,
+        "--file-path",
+        help="Local CSV path. Use either --file-path or --url.",
+    ),
+    source_url: Optional[str] = typer.Option(
+        None,
+        "--url",
+        help="Remote CSV URL (s3://, http://, https://). Use either --url or --file-path.",
+    ),
+    process_labels: bool = typer.Option(
+        False,
+        "--process-labels/--no-process-labels",
+        help="Apply topic/intent labels during import.",
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    validate_uuid(agent_id, field_name="agent-id")
+    if bool(file_path) == bool(source_url):
+        raise typer.BadParameter(
+            "Provide exactly one source: --file-path or --url. Example: applied-cli conversations import --agent-id <uuid> --file-path ./historical.csv"
+        )
+    if file_path:
+        path = Path(file_path)
+        if not path.exists() or not path.is_file():
+            raise typer.BadParameter(f"file-path not found: {file_path}")
+
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        result = import_conversations_bulk(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+            file_path=file_path,
+            url=source_url,
+            process_labels=process_labels,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="import historical conversations"), err=True)
+        typer.echo(
+            "CSV format reminder: ID, DATE_CREATED, SENDER, TYPE, MESSAGE_DATE, BODY, TITLE, TOPIC, INTENT, SENTIMENT, SENTIMENT_SCORE, CSAT_SCORE",
+            err=True,
+        )
+        typer.echo(
+            "CONTACT_PHONE is optional. Import now normalizes long phones and generates safe placeholders when missing.",
+            err=True,
+        )
+        raise typer.Exit(code=1) from exc
+
+    payload = {
+        "result": "success",
+        "agent_id": agent_id,
+        "source": file_path or source_url,
+        "process_labels": process_labels,
+        "summary": result,
+    }
+    _emit(payload, output_json)
+
+
+@benchmarks_app.command(
+    "list",
+    help=(
+        "List conversation benchmarks. Example: applied-cli test benchmarks list --agent-id <uuid>"
+    ),
+)
+def benchmarks_list(
+    agent_id: Optional[str] = typer.Option(
+        None, "--agent-id", "--agent", help="Filter by agent UUID."
+    ),
+    limit: int = typer.Option(50, help="Maximum number of results."),
+    ordering: str = typer.Option("-created_at", help="Ordering, e.g. -created_at."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    if agent_id:
+        validate_uuid(agent_id, field_name="agent-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        rows = list_conversation_benchmarks(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+            limit=limit,
+            ordering=ordering,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="list benchmarks"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(rows, output_json)
+
+
+@benchmarks_app.command(
+    "describe",
+    help=(
+        "Describe one benchmark. Example: applied-cli test benchmarks describe --benchmark-id <uuid>"
+    ),
+)
+@benchmarks_app.command(
+    "show",
+    help="Show one benchmark. Example: applied-cli test benchmarks show --benchmark-id <uuid>",
+)
+def benchmarks_show(
+    benchmark_id: Optional[str] = typer.Option(
+        None, "--benchmark-id", "--benchmark", "--id", help="Benchmark UUID."
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    benchmark_id = _require_option(
+        benchmark_id,
+        option="--benchmark-id",
+        example="applied-cli test benchmarks show --benchmark-id <uuid>",
+    )
+    validate_uuid(benchmark_id, field_name="benchmark-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        row = get_conversation_benchmark(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            benchmark_id=benchmark_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="show benchmark"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(row, output_json)
+
+
+@benchmarks_app.command(
+    "create",
+    help=(
+        "Create one benchmark. Example: applied-cli test benchmarks create --agent-id <uuid> "
+        "--name 'CLI Self-Rated Conversations'"
+    ),
+)
+def benchmarks_create(
+    agent_id: str = typer.Option(..., "--agent-id", "--agent", help="Target agent UUID."),
+    name: str = typer.Option(..., "--name", help="Benchmark name."),
+    description: str = typer.Option(
+        "Benchmark collection created by applied-cli.",
+        "--description",
+        help="Benchmark description.",
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    validate_uuid(agent_id, field_name="agent-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        row = create_conversation_benchmark(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+            name=name.strip(),
+            description=description.strip(),
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="create benchmark"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(row, output_json)
+
+
+@benchmarks_app.command(
+    "delete",
+    help="Delete one benchmark. Example: applied-cli test benchmarks delete --benchmark-id <uuid> --yes",
+)
+def benchmarks_delete(
+    benchmark_id: Optional[str] = typer.Option(
+        None, "--benchmark-id", "--benchmark", "--id", help="Benchmark UUID."
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    benchmark_id = _require_option(
+        benchmark_id,
+        option="--benchmark-id",
+        example="applied-cli test benchmarks delete --benchmark-id <uuid> --yes",
+    )
+    validate_uuid(benchmark_id, field_name="benchmark-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        if not yes and not typer.confirm(
+            f"Delete benchmark {benchmark_id} in shop {resolved_shop_id}?"
+        ):
+            raise typer.Exit(code=1)
+        delete_conversation_benchmark(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            benchmark_id=benchmark_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="delete benchmark"), err=True)
+        raise typer.Exit(code=1) from exc
+    payload = {"deleted": True, "resource": "benchmark", "id": benchmark_id}
+    if output_json:
+        typer.echo(json.dumps(payload, indent=2))
+    else:
+        typer.echo(f"result=success | deleted=true | resource=benchmark | id={benchmark_id}")
+
+
+@scenarios_app.command(
+    "list",
+    help=(
+        "List scenarios by benchmark/agent. Example: applied-cli test scenarios list "
+        "--benchmark-id <uuid> --agent-id <uuid> --pass-status fail"
+    ),
+)
+def scenarios_list(
+    benchmark_id: Optional[str] = typer.Option(
+        None, "--benchmark-id", "--benchmark", help="Filter by benchmark UUID."
+    ),
+    agent_id: Optional[str] = typer.Option(
+        None, "--agent-id", "--agent", help="Filter by agent UUID."
+    ),
+    name: Optional[str] = typer.Option(None, help="Filter by scenario name."),
+    pass_status: Optional[str] = typer.Option(
+        None, "--pass-status", help="Filter by pass status: pass/fail."
+    ),
+    limit: int = typer.Option(50, help="Maximum number of results."),
+    ordering: str = typer.Option("-created_at", help="Ordering, e.g. -created_at."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    if benchmark_id:
+        validate_uuid(benchmark_id, field_name="benchmark-id")
+    if agent_id:
+        validate_uuid(agent_id, field_name="agent-id")
+    parsed_pass_status = _parse_optional_pass_status(pass_status)
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        rows = list_conversation_scenarios(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+            benchmark_id=benchmark_id,
+            name=name,
+            pass_status=parsed_pass_status,
+            limit=limit,
+            ordering=ordering,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="list scenarios"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(rows, output_json)
+
+
+@scenarios_app.command(
+    "describe",
+    help="Describe one scenario. Example: applied-cli test scenarios describe --scenario-id <uuid>",
+)
+@scenarios_app.command(
+    "show",
+    help="Show one scenario. Example: applied-cli test scenarios show --scenario-id <uuid>",
+)
+def scenarios_show(
+    scenario_id: Optional[str] = typer.Option(
+        None, "--scenario-id", "--scenario", "--id", help="Scenario UUID."
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    scenario_id = _require_option(
+        scenario_id,
+        option="--scenario-id",
+        example="applied-cli test scenarios show --scenario-id <uuid>",
+    )
+    validate_uuid(scenario_id, field_name="scenario-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        row = get_conversation_scenario(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            scenario_id=scenario_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="show scenario"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(row, output_json)
+
+
+@scenarios_app.command(
+    "create",
+    help=(
+        "Create one scenario. Example: applied-cli test scenarios create --agent-id <uuid> "
+        "--name 'Escalation test' --input-conversation-id <uuid>"
+    ),
+)
+def scenarios_create(
+    agent_id: str = typer.Option(..., "--agent-id", "--agent", help="Target agent UUID."),
+    name: str = typer.Option(..., "--name", help="Scenario name."),
+    input_conversation_id: str = typer.Option(
+        ...,
+        "--input-conversation-id",
+        "--conversation-id",
+        help="Input conversation UUID.",
+    ),
+    benchmark_id: Optional[str] = typer.Option(
+        None, "--benchmark-id", "--benchmark", help="Optional benchmark UUID."
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    validate_uuid(agent_id, field_name="agent-id")
+    validate_uuid(input_conversation_id, field_name="input-conversation-id")
+    if benchmark_id:
+        validate_uuid(benchmark_id, field_name="benchmark-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        row = create_conversation_scenario(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+            benchmark_id=benchmark_id,
+            name=name.strip(),
+            input_conversation_id=input_conversation_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="create scenario"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(row, output_json)
+
+
+@scenarios_app.command(
+    "update",
+    help=(
+        "Update one scenario. Example: applied-cli test scenarios update --scenario-id <uuid> "
+        "--pass-status pass --csat-score 5"
+    ),
+)
+def scenarios_update(
+    scenario_id: str = typer.Option(..., "--scenario-id", "--scenario", "--id"),
+    name: Optional[str] = typer.Option(None, "--name", help="Scenario name."),
+    benchmark_id: Optional[str] = typer.Option(
+        None, "--benchmark-id", "--benchmark", help="Single benchmark UUID to attach."
+    ),
+    pass_status: Optional[str] = typer.Option(
+        None, "--pass-status", help="pass/fail aggregate status."
+    ),
+    csat_score: Optional[float] = typer.Option(None, "--csat-score"),
+    feedback: Optional[str] = typer.Option(None, "--feedback"),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    validate_uuid(scenario_id, field_name="scenario-id")
+    if benchmark_id:
+        validate_uuid(benchmark_id, field_name="benchmark-id")
+    parsed_pass_status = _parse_optional_pass_status(pass_status)
+    payload: dict[str, Any] = {}
+    if name is not None:
+        payload["name"] = name.strip()
+    if benchmark_id is not None:
+        payload["benchmark_ids"] = [benchmark_id]
+    if parsed_pass_status is not None:
+        payload["pass_status"] = parsed_pass_status
+    if csat_score is not None:
+        payload["csat_score"] = float(csat_score)
+    if feedback is not None:
+        payload["feedback"] = feedback
+    if not payload:
+        raise typer.BadParameter("No fields provided. Pass at least one update option.")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        row = patch_conversation_scenario(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            scenario_id=scenario_id,
+            payload=payload,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="update scenario"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(row, output_json)
+
+
+@scenarios_app.command(
+    "delete",
+    help="Delete one scenario. Example: applied-cli test scenarios delete --scenario-id <uuid> --yes",
+)
+def scenarios_delete(
+    scenario_id: Optional[str] = typer.Option(
+        None, "--scenario-id", "--scenario", "--id", help="Scenario UUID."
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    scenario_id = _require_option(
+        scenario_id,
+        option="--scenario-id",
+        example="applied-cli test scenarios delete --scenario-id <uuid> --yes",
+    )
+    validate_uuid(scenario_id, field_name="scenario-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        if not yes and not typer.confirm(
+            f"Delete scenario {scenario_id} in shop {resolved_shop_id}?"
+        ):
+            raise typer.Exit(code=1)
+        delete_conversation_scenario(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            scenario_id=scenario_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="delete scenario"), err=True)
+        raise typer.Exit(code=1) from exc
+    payload = {"deleted": True, "resource": "scenario", "id": scenario_id}
+    if output_json:
+        typer.echo(json.dumps(payload, indent=2))
+    else:
+        typer.echo(f"result=success | deleted=true | resource=scenario | id={scenario_id}")
+
+
+@runs_app.command(
+    "list",
+    help="List scenario runs. Example: applied-cli test runs list --scenario-id <uuid> --latest",
+)
+def runs_list(
+    scenario_id: Optional[str] = typer.Option(
+        None, "--scenario-id", "--scenario", "--id", help="Scenario UUID."
+    ),
+    latest: bool = typer.Option(
+        False, "--latest/--all", help="Return only latest run per scenario."
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    scenario_id = _require_option(
+        scenario_id,
+        option="--scenario-id",
+        example="applied-cli test runs list --scenario-id <uuid>",
+    )
+    validate_uuid(scenario_id, field_name="scenario-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        rows = list_scenario_runs(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            scenario_id=scenario_id,
+            latest_only=latest,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="list runs"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(rows, output_json)
+
+
+@runs_app.command(
+    "describe",
+    help="Describe one run. Example: applied-cli test runs describe --run-id <uuid>",
+)
+@runs_app.command(
+    "show",
+    help="Show one run. Example: applied-cli test runs show --run-id <uuid>",
+)
+def runs_show(
+    run_id: Optional[str] = typer.Option(None, "--run-id", "--run", "--id", help="Run UUID."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    run_id = _require_option(
+        run_id, option="--run-id", example="applied-cli test runs show --run-id <uuid>"
+    )
+    validate_uuid(run_id, field_name="run-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        row = get_scenario_run(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            run_id=run_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="show run"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(row, output_json)
+
+
+@runs_app.command(
+    "create",
+    help=(
+        "Create one run. Example: applied-cli test runs create --scenario-id <uuid> "
+        "--output-conversation-id <uuid>"
+    ),
+)
+def runs_create(
+    scenario_id: str = typer.Option(..., "--scenario-id", "--scenario", help="Scenario UUID."),
+    output_conversation_id: str = typer.Option(
+        ...,
+        "--output-conversation-id",
+        "--conversation-id",
+        help="Output conversation UUID.",
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    validate_uuid(scenario_id, field_name="scenario-id")
+    validate_uuid(output_conversation_id, field_name="output-conversation-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        row = create_scenario_run(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            scenario_id=scenario_id,
+            output_conversation_id=output_conversation_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="create run"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(row, output_json)
+
+
+@runs_app.command(
+    "update",
+    help=(
+        "Update one run. Example: applied-cli test runs update --run-id <uuid> "
+        "--pass-status pass --csat-score 5"
+    ),
+)
+def runs_update(
+    run_id: str = typer.Option(..., "--run-id", "--run", "--id", help="Run UUID."),
+    pass_status: Optional[str] = typer.Option(None, "--pass-status", help="pass/fail result."),
+    csat_score: Optional[float] = typer.Option(None, "--csat-score"),
+    feedback: Optional[str] = typer.Option(None, "--feedback"),
+    reference_score: Optional[float] = typer.Option(None, "--reference-score"),
+    reference_notes: Optional[str] = typer.Option(None, "--reference-notes"),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    validate_uuid(run_id, field_name="run-id")
+    parsed_pass_status = _parse_optional_pass_status(pass_status)
+    payload: dict[str, Any] = {}
+    if parsed_pass_status is not None:
+        payload["pass_status"] = parsed_pass_status
+    if csat_score is not None:
+        payload["csat_score"] = float(csat_score)
+    if feedback is not None:
+        payload["feedback"] = feedback
+    if reference_score is not None:
+        payload["reference_score"] = float(reference_score)
+    if reference_notes is not None:
+        payload["reference_notes"] = reference_notes
+    if not payload:
+        raise typer.BadParameter("No fields provided. Pass at least one update option.")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        row = patch_scenario_run(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            run_id=run_id,
+            payload=payload,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="update run"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(row, output_json)
+
+
+# =============================================================================
+# SCENARIOS: RATE (imported from rate module)
+# =============================================================================
+
+from applied_cli.commands.rate import conversation as rate_conversation
+
+scenarios_app.command(
+    "rate",
+    help=(
+        "Rate a conversation and create a scenario. "
+        "Example: applied-cli test scenarios rate --conversation-id <uuid>"
+    ),
+)(rate_conversation)