hypercli-cli 2026.3.13__tar.gz → 2026.3.22__tar.gz

{hypercli_cli-2026.3.13 → hypercli_cli-2026.3.22}/.gitignore

@@ -28,6 +28,9 @@ coverage
 .DS_Store
 *.pem
 
+# IDE
+.idea/
+
 # Debug
 npm-debug.log*
 yarn-debug.log*

{hypercli_cli-2026.3.13 → hypercli_cli-2026.3.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypercli-cli
-Version: 2026.3.13
+Version: 2026.3.22
 Summary: CLI for HyperCLI - GPU orchestration and LLM API
 Project-URL: Homepage, https://hypercli.com
 Project-URL: Documentation, https://docs.hypercli.com
@@ -9,7 +9,7 @@ Author-email: HyperCLI <support@hypercli.com>
 License: MIT
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: hypercli-sdk>=2026.3.13
+Requires-Dist: hypercli-sdk>=2026.3.22
 Requires-Dist: mutagen>=1.47.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=14.2.0
@@ -19,11 +19,11 @@ Provides-Extra: all
 Requires-Dist: argon2-cffi>=25.0.0; extra == 'all'
 Requires-Dist: eth-account>=0.13.0; extra == 'all'
 Requires-Dist: faster-whisper>=1.1.0; extra == 'all'
-Requires-Dist: hypercli-sdk[comfyui]>=2026.3.13; extra == 'all'
+Requires-Dist: hypercli-sdk[comfyui]>=2026.3.22; extra == 'all'
 Requires-Dist: web3>=7.0.0; extra == 'all'
 Requires-Dist: x402[evm,httpx]>=2.0.0; extra == 'all'
 Provides-Extra: comfyui
-Requires-Dist: hypercli-sdk[comfyui]>=2026.3.13; extra == 'comfyui'
+Requires-Dist: hypercli-sdk[comfyui]>=2026.3.22; extra == 'comfyui'
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.3.0; extra == 'dev'

hypercli_cli-2026.3.22/hypercli_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "2026.3.22"

{hypercli_cli-2026.3.13 → hypercli_cli-2026.3.22}/hypercli_cli/agent.py

@@ -55,6 +55,8 @@ HYPERCLI_DIR = Path.home() / ".hypercli"
 AGENT_KEY_PATH = HYPERCLI_DIR / "agent-key.json"
 DEV_API_BASE = "https://api.dev.hypercli.com"
 PROD_API_BASE = "https://api.hypercli.com"
+DEV_INFERENCE_API_BASE = "https://api.agents.dev.hypercli.com"
+PROD_INFERENCE_API_BASE = "https://api.agents.hypercli.com"
 
 
 def require_x402_deps():
@@ -351,7 +353,7 @@ def models(
     import httpx
 
     api_base = DEV_API_BASE if dev else PROD_API_BASE
-    key = os.getenv("HYPERCLAW_API_KEY")
+    key = os.getenv("HYPER_API_KEY")
     headers = {"Authorization": f"Bearer {key}"} if key else {}
 
     # Prefer OpenAI-compatible endpoint, then fallback to legacy.
@@ -372,7 +374,7 @@ def models(
     if payload is None:
         console.print(
             f"[red]❌ Failed to fetch models from {urls[0]} or {urls[1]} "
-            "(set HYPERCLAW_API_KEY if endpoint requires auth)[/red]"
+            "(set HYPER_API_KEY if endpoint requires auth)[/red]"
         )
         raise typer.Exit(1)
 
@@ -544,12 +546,43 @@ OPENCLAW_CONFIG_PATH = Path.home() / ".openclaw" / "openclaw.json"
 
 def _resolve_api_base(base_url: str | None = None, dev: bool = False) -> str:
     """Resolve API base from flag/env, then fall back to dev/prod defaults."""
-    return (base_url or os.environ.get("HYPERCLAW_API_BASE") or (DEV_API_BASE if dev else PROD_API_BASE)).rstrip("/")
+    return (
+        base_url
+        or os.environ.get("HYPER_API_BASE")
+        or (DEV_INFERENCE_API_BASE if dev else PROD_INFERENCE_API_BASE)
+    ).rstrip("/")
 
 
-def fetch_models(api_key: str, api_base: str = PROD_API_BASE) -> list[dict]:
+def fetch_models(api_key: str, api_base: str = PROD_INFERENCE_API_BASE) -> list[dict]:
     """Fetch available models from LiteLLM /v1/models (served by HyperClaw)."""
     import httpx
+
+    def _infer_mode(model_id: str) -> str | None:
+        normalized = (model_id or "").strip().lower()
+        if "embedding" in normalized:
+            return "embedding"
+        return None
+
+    def _meta_for_model(model_id: str) -> dict:
+        normalized = (model_id or "").strip().lower()
+        aliases = {
+            "kimi-k2.5": {"name": "Kimi K2.5", "reasoning": True, "contextWindow": 262144},
+            "moonshotai/kimi-k2.5": {"name": "Kimi K2.5", "reasoning": True, "contextWindow": 262144},
+            "glm-5": {"name": "GLM-5", "reasoning": True, "contextWindow": 202752},
+            "zai-org/glm-5": {"name": "GLM-5", "reasoning": True, "contextWindow": 202752},
+            "qwen3-embedding-4b": {
+                "name": "Qwen3 Embedding 4B",
+                "reasoning": False,
+                "contextWindow": 32768,
+                "mode": "embedding",
+                "input": ["text"],
+            },
+        }
+        if normalized in aliases:
+            return aliases[normalized]
+        suffix = normalized.rsplit("/", 1)[-1]
+        return aliases.get(suffix, {})
+
     try:
         resp = httpx.get(
             f"{api_base}/v1/models",
@@ -558,19 +591,14 @@ def fetch_models(api_key: str, api_base: str = PROD_API_BASE) -> list[dict]:
         )
         resp.raise_for_status()
         data = resp.json().get("data", [])
-        # Known model metadata (context windows, reasoning, etc.)
-        MODEL_META = {
-            "kimi-k2.5": {"name": "Kimi K2.5", "reasoning": True, "contextWindow": 262144},
-            "glm-5": {"name": "GLM-5", "reasoning": True, "contextWindow": 202752},
-        }
         return [
             {
                 "id": m["id"],
-                "name": MODEL_META.get(m["id"], {}).get("name", m["id"].replace("-", " ").title()),
-                "reasoning": MODEL_META.get(m["id"], {}).get("reasoning", False),
-                "input": ["text"],
-                "contextWindow": MODEL_META.get(m["id"], {}).get("contextWindow", 200000),
-                **({"mode": m["mode"]} if m.get("mode") else {}),
+                "name": _meta_for_model(m["id"]).get("name", m["id"].replace("-", " ").title()),
+                "reasoning": _meta_for_model(m["id"]).get("reasoning", False),
+                "input": _meta_for_model(m["id"]).get("input", ["text", "image"]),
+                "contextWindow": _meta_for_model(m["id"]).get("contextWindow", 200000),
+                **({"mode": m.get("mode") or _meta_for_model(m["id"]).get("mode") or _infer_mode(m["id"])} if (m.get("mode") or _meta_for_model(m["id"]).get("mode") or _infer_mode(m["id"])) else {}),
             }
             for m in data
             if m.get("id")
@@ -583,16 +611,24 @@ def fetch_models(api_key: str, api_base: str = PROD_API_BASE) -> list[dict]:
                 "id": "kimi-k2.5",
                 "name": "Kimi K2.5",
                 "reasoning": True,
-                "input": ["text"],
+                "input": ["text", "image"],
                 "contextWindow": 262144,
             },
             {
                 "id": "glm-5",
                 "name": "GLM-5",
                 "reasoning": True,
-                "input": ["text"],
+                "input": ["text", "image"],
                 "contextWindow": 202752,
             },
+            {
+                "id": "qwen3-embedding-4b",
+                "name": "Qwen3 Embedding 4B",
+                "reasoning": False,
+                "input": ["text"],
+                "contextWindow": 32768,
+                "mode": "embedding",
+            },
         ]
 
 
@@ -620,49 +656,21 @@ def openclaw_setup(
         console.print("[red]❌ Invalid key file — missing 'key' field[/red]")
         raise typer.Exit(1)
 
-    # Read existing config (or start empty)
+    config = {}
     if OPENCLAW_CONFIG_PATH.exists():
         with open(OPENCLAW_CONFIG_PATH) as f:
             config = json.load(f)
-    else:
-        config = {}
-
-    # Fetch current model list from LiteLLM via API
-    models = fetch_models(api_key)
-
-    # Patch models.providers.hyperclaw + embedding config
-    config.setdefault("models", {}).setdefault("providers", {})
-    chat_models = [m for m in models if m.get("mode") != "embedding"]
-    embedding_models = [m for m in models if m.get("mode") == "embedding"]
-    config["models"]["providers"]["hyperclaw"] = {
-        "baseUrl": "https://api.hypercli.com",
-        "apiKey": api_key,
-        "api": "anthropic-messages",
-        "models": chat_models,
-    }
-    config["models"]["providers"]["hyperclaw-embed"] = {
-        "baseUrl": "https://api.hypercli.com/v1",
-        "apiKey": api_key,
-        "api": "openai-completions",
-        "models": embedding_models,
-    }
 
-    # Always set embedding provider (reuses same API key)
-    config.setdefault("agents", {}).setdefault("defaults", {})
-    config["agents"]["defaults"]["memorySearch"] = {
-        "provider": "openai",
-        "model": "qwen3-embedding-4b",
-        "remote": {
-            "baseUrl": "https://api.hypercli.com/v1/",
-            "apiKey": api_key,
-        }
-    }
+    models = fetch_models(api_key, PROD_INFERENCE_API_BASE)
+    snippet = _config_openclaw(api_key, models, PROD_INFERENCE_API_BASE)
+    if not default:
+        defaults = (((snippet.get("agents") or {}).get("defaults") or {}))
+        model_cfg = defaults.get("model") or {}
+        model_cfg.pop("primary", None)
+        if not model_cfg and "model" in defaults:
+            defaults.pop("model", None)
 
-    # Optionally set default model
-    if default:
-        config["agents"]["defaults"].setdefault("model", {})
-        if chat_models:
-            config["agents"]["defaults"]["model"]["primary"] = f"hyperclaw/{chat_models[0]['id']}"
+    _deep_merge(config, snippet)
 
     # Write back
     OPENCLAW_CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
@@ -671,15 +679,14 @@ def openclaw_setup(
         f.write("\n")
 
     console.print(f"[green]✅ Patched {OPENCLAW_CONFIG_PATH}[/green]")
-    console.print(f"   provider: hyperclaw  key: {api_key[:16]}...")
-    if embedding_models:
-        console.print("   embedding provider: hyperclaw-embed")
-    for m in chat_models:
-        console.print(f"   model: hyperclaw/{m['id']}")
-    for m in embedding_models:
-        console.print(f"   model: hyperclaw-embed/{m['id']}")
-    if default and chat_models:
-        console.print(f"   default model: hyperclaw/{chat_models[0]['id']}")
+    providers = ((snippet.get("models") or {}).get("providers") or {})
+    for provider_id, provider_cfg in providers.items():
+        console.print(f"   provider: {provider_id}  key: {api_key[:16]}...")
+        for m in provider_cfg.get("models") or []:
+            console.print(f"   model: {provider_id}/{m['id']}")
+    primary = ((((snippet.get("agents") or {}).get("defaults") or {}).get("model") or {}).get("primary"))
+    if primary:
+        console.print(f"   default model: {primary}")
     console.print("\nOpenClaw will use the Anthropic-compatible /v1/messages endpoint.")
     console.print("Run: [bold]openclaw gateway restart[/bold]")
 
@@ -703,11 +710,43 @@ def _resolve_api_key(key: str | None) -> str:
     raise typer.Exit(1)
 
 
-def _config_openclaw(api_key: str, models: list[dict], api_base: str = PROD_API_BASE) -> dict:
-    """OpenClaw openclaw.json provider snippet (LLM + embeddings)."""
+def _config_openclaw(
+    api_key: str,
+    models: list[dict],
+    api_base: str = PROD_INFERENCE_API_BASE,
+    placeholder_env: str | None = None,
+) -> dict:
+    """OpenClaw openclaw.json provider snippet (LLM only)."""
+    def _model_suffix(model_id: str) -> str:
+        return str(model_id or "").strip().lower().rsplit("/", 1)[-1]
+
+    def _is_supported_openclaw_model(model: dict) -> bool:
+        suffix = _model_suffix(model.get("id", ""))
+        return (
+            suffix == "glm-5"
+            or "kimi" in suffix
+            or "embedding" in suffix
+        )
+
     api_base = api_base.rstrip("/")
-    chat_models = [m for m in models if m.get("mode") != "embedding"]
-    embedding_models = [m for m in models if m.get("mode") == "embedding"]
+    supported_models = [m for m in models if _is_supported_openclaw_model(m)]
+    chat_models = [m for m in supported_models if m.get("mode") != "embedding"]
+    embedding_models = [m for m in supported_models if m.get("mode") == "embedding"]
+    kimi_models = [m for m in chat_models if "kimi" in _model_suffix(m.get("id", ""))]
+    glm_models = [m for m in chat_models if _model_suffix(m.get("id", "")) == "glm-5"]
+    openai_chat_models = [
+        m for m in chat_models
+        if m not in kimi_models and m not in glm_models
+    ]
+    embedding_model_id = embedding_models[0]["id"] if embedding_models else None
+    primary_model = (
+        f"kimi-coding/{kimi_models[0]['id']}" if kimi_models else (
+            f"hyperclaw/{glm_models[0]['id']}" if glm_models else (
+                f"hyperclaw-openai/{openai_chat_models[0]['id']}" if openai_chat_models else None
+            )
+        )
+    )
+    config_api_key = f"${{{placeholder_env}}}" if placeholder_env else api_key
     return {
         "models": {
             "mode": "merge",
@@ -715,39 +754,69 @@ def _config_openclaw(api_key: str, models: list[dict], api_base: str = PROD_API_
                 "hyperclaw": {
                     # OpenClaw/pi-ai appends /v1/messages for anthropic-messages.
                     "baseUrl": api_base,
-                    "apiKey": api_key,
+                    "apiKey": config_api_key,
                     "api": "anthropic-messages",
-                    "models": chat_models,
-                },
-                "hyperclaw-embed": {
-                    # Embeddings go through the OpenAI-compatible /v1 endpoints.
-                    "baseUrl": f"{api_base}/v1",
-                    "apiKey": api_key,
-                    "api": "openai-completions",
-                    "models": embedding_models,
+                    "models": glm_models,
                 },
+                **(
+                    {
+                        "kimi-coding": {
+                            # Use the upstream Kimi provider semantics while still
+                            # routing requests through the HyperClaw Anthropic proxy.
+                            "baseUrl": api_base,
+                            "apiKey": config_api_key,
+                            "api": "anthropic-messages",
+                            "headers": {
+                                "User-Agent": "claude-code/0.1.0",
+                            },
+                            "models": kimi_models,
+                        },
+                    }
+                    if kimi_models
+                    else {}
+                ),
+                **(
+                    {
+                        "hyperclaw-openai": {
+                            "baseUrl": f"{api_base}/v1",
+                            "apiKey": config_api_key,
+                            "api": "openai-completions",
+                            "models": openai_chat_models,
+                        },
+                    }
+                    if openai_chat_models
+                    else {}
+                ),
             }
         },
         "agents": {
             "defaults": {
+                **({"model": {"primary": primary_model}} if primary_model else {}),
                 "models": {
-                    **{f"hyperclaw/{m['id']}": {"alias": m['id'].split('-')[0]} for m in chat_models},
-                    **{f"hyperclaw-embed/{m['id']}": {"alias": m['id'].split('-')[0]} for m in embedding_models},
+                    **{f"hyperclaw/{m['id']}": {"alias": "glm"} for m in glm_models},
+                    **{f"kimi-coding/{m['id']}": {"alias": "kimi"} for m in kimi_models},
+                    **{f"hyperclaw-openai/{m['id']}": {"alias": m['id'].split('-')[0]} for m in openai_chat_models},
                 },
-                "memorySearch": {
-                    "provider": "openai",
-                    "model": "qwen3-embedding-4b",
-                    "remote": {
-                        "baseUrl": f"{api_base}/v1/",
-                        "apiKey": api_key,
+                **(
+                    {
+                        "memorySearch": {
+                            "provider": "openai",
+                            "model": embedding_model_id,
+                            "remote": {
+                                "baseUrl": f"{api_base}/v1",
+                                "apiKey": config_api_key,
+                            },
+                        }
                     }
-                }
+                    if embedding_model_id
+                    else {}
+                ),
             }
         }
     }
 
 
-def _config_opencode(api_key: str, models: list[dict], api_base: str = PROD_API_BASE) -> dict:
+def _config_opencode(api_key: str, models: list[dict], api_base: str = PROD_INFERENCE_API_BASE) -> dict:
     """OpenCode opencode.json provider snippet."""
     api_base = api_base.rstrip("/")
     model_entries = {}
@@ -769,7 +838,7 @@ def _config_opencode(api_key: str, models: list[dict], api_base: str = PROD_API_
     }
 
 
-def _config_env(api_key: str, models: list[dict], api_base: str = PROD_API_BASE) -> str:
+def _config_env(api_key: str, models: list[dict], api_base: str = PROD_INFERENCE_API_BASE) -> str:
     """Shell env vars for generic OpenAI-compatible tools."""
     api_base = api_base.rstrip("/")
     lines = [
@@ -786,7 +855,7 @@ def exec_cmd(
     command: str = typer.Argument(..., help="Command to execute"),
     timeout: int = typer.Option(30, "--timeout", "-t", help="Command timeout (seconds)"),
 ):
-    """Execute a command on a HyperClaw agent container."""
+    """Execute a command on a `hypercli-openclaw` agent container."""
     from . import agents
 
     agents.exec_cmd(agent_id=agent_id, command=command, timeout=timeout)
@@ -796,7 +865,7 @@ def exec_cmd(
 def shell_cmd(
     agent_id: str = typer.Argument(..., help="Agent ID (or prefix)"),
 ):
-    """Open an interactive shell on a HyperClaw agent container."""
+    """Open an interactive shell on a `hypercli-openclaw` agent container."""
     from . import agents
 
     agents.shell(agent_id=agent_id)
@@ -812,7 +881,8 @@ def config_cmd(
         help=f"Output format: {', '.join(FORMAT_CHOICES)}. Omit to show all.",
     ),
     key: str = typer.Option(None, "--key", "-k", help="API key (sk-...). Falls back to ~/.hypercli/agent-key.json"),
-    base_url: str = typer.Option(None, "--base-url", help="HyperClaw API base URL. Falls back to HYPERCLAW_API_BASE, then --dev/prod defaults"),
+    base_url: str = typer.Option(None, "--base-url", help="HyperClaw API base URL. Falls back to HYPER_API_BASE, then --dev/prod defaults"),
+    placeholder_env: str = typer.Option(None, "--placeholder-env", help="Write ${ENV_VAR} placeholders into generated config instead of literal API keys"),
     apply: bool = typer.Option(False, "--apply", help="Write config to the appropriate file (openclaw/opencode only)"),
     dev: bool = typer.Option(False, "--dev", help="Use dev API"),
 ):
@@ -844,7 +914,7 @@ def config_cmd(
 
     for fmt in formats:
         if fmt == "openclaw":
-            snippet = _config_openclaw(api_key, models, api_base)
+            snippet = _config_openclaw(api_key, models, api_base, placeholder_env=placeholder_env)
             _show_snippet("OpenClaw", "~/.openclaw/openclaw.json", snippet, apply, OPENCLAW_CONFIG_PATH)
         elif fmt == "opencode":
             snippet = _config_opencode(api_key, models, api_base)

{hypercli_cli-2026.3.13 → hypercli_cli-2026.3.22}/hypercli_cli/agents.py

@@ -12,14 +12,12 @@ import typer
 from rich.console import Console
 from rich.table import Table
 
-from hypercli.agents import Agent, Deployments, OpenClawAgent
+from hypercli.agents import Agent, Deployments, OpenClawAgent, DEFAULT_OPENCLAW_IMAGE
 
-app = typer.Typer(help="Manage OpenClaw agent pods (reef containers)")
+app = typer.Typer(help="Manage OpenClaw agent pods")
 console = Console()
 PROD_API_BASE = "https://api.hypercli.com"
 DEV_API_BASE = "https://api.dev.hypercli.com"
-PROD_AGENTS_WS_URL = "wss://api.agents.hypercli.com/ws"
-DEV_AGENTS_WS_URL = "wss://api.agents.dev.hypercli.com/ws"
 _GLOBAL_DEV = False
 _GLOBAL_AGENTS_WS_URL: str | None = None
 
@@ -29,6 +27,13 @@ STATE_DIR = Path.home() / ".hypercli"
 AGENTS_STATE = STATE_DIR / "agents.json"
 
 
+def _default_openclaw_image(image: str | None, config: dict | None = None) -> str:
+    if image:
+        return image
+    configured = str((config or {}).get("image") or "").strip()
+    return configured or DEFAULT_OPENCLAW_IMAGE
+
+
 @app.callback()
 def agents_root(
     dev: bool = typer.Option(False, "--dev", help="Use the dev HyperClaw agents API"),
@@ -42,7 +47,10 @@ def agents_root(
 
 def _get_agent_api_key() -> str:
     """Resolve HyperClaw API key from env or saved key file."""
-    key = os.environ.get("HYPERCLAW_API_KEY", "")
+    key = os.environ.get("HYPER_AGENTS_API_KEY", "").strip()
+    if key:
+        return key
+    key = os.environ.get("HYPER_API_KEY", "").strip()
     if key:
         return key
     if AGENT_KEY_PATH.exists():
@@ -52,7 +60,7 @@ def _get_agent_api_key() -> str:
         if key:
             return key
     console.print("[red]❌ No HyperClaw API key found.[/red]")
-    console.print("Set HYPERCLAW_API_KEY or subscribe: [bold]hyper agent subscribe 1aiu[/bold]")
+    console.print("Set HYPER_AGENTS_API_KEY or HYPER_API_KEY, or subscribe: [bold]hyper agent subscribe 1aiu[/bold]")
     raise typer.Exit(1)
 
 
@@ -60,12 +68,13 @@ def _get_deployments_client(agents_ws_url: str | None = None) -> Deployments:
     """Create a Deployments client using the HyperClaw API key."""
     from hypercli.http import HTTPClient
     api_key = _get_agent_api_key()
-    api_base = os.environ.get("HYPERCLI_API_URL") or (DEV_API_BASE if _GLOBAL_DEV else PROD_API_BASE)
+    api_base = (
+        os.environ.get("AGENTS_API_BASE_URL")
+        or os.environ.get("HYPER_API_BASE")
+        or os.environ.get("HYPERCLI_API_URL")
+        or (DEV_API_BASE if _GLOBAL_DEV else PROD_API_BASE)
+    )
     resolved_agents_ws_url = agents_ws_url or _GLOBAL_AGENTS_WS_URL or os.environ.get("AGENTS_WS_URL")
-    if _GLOBAL_DEV and not resolved_agents_ws_url:
-        resolved_agents_ws_url = DEV_AGENTS_WS_URL
-    if not _GLOBAL_DEV and not resolved_agents_ws_url and os.environ.get("HYPERCLI_API_URL", "").strip() == "":
-        resolved_agents_ws_url = PROD_AGENTS_WS_URL
     http = HTTPClient(api_base, api_key)
     return Deployments(http, api_key=api_key, api_base=api_base, agents_ws_url=resolved_agents_ws_url)
 
@@ -125,10 +134,11 @@ def _resolve_agent(agent_id: str) -> str:
 
 def _get_pod_with_token(agent_id: str) -> Agent:
     """Get an agent, filling JWT from local state if needed."""
+    resolved_agent_id = _resolve_agent(agent_id)
     agents = _get_deployments_client()
-    pod = agents.get(agent_id)
+    pod = agents.get(resolved_agent_id)
     state = _load_state()
-    local = state.get(agent_id, {})
+    local = state.get(resolved_agent_id, {})
     if not pod.jwt_token and local.get("jwt_token"):
         pod.jwt_token = local["jwt_token"]
     if isinstance(pod, OpenClawAgent) and not pod.gateway_token and local.get("gateway_token"):
@@ -274,7 +284,7 @@ def create(
     port: list[str] = typer.Option(None, "--port", help="Expose port as PORT or PORT:noauth. Repeatable."),
     command: str = typer.Option(None, "--command", help="Container args as a shell-style string"),
     entrypoint: str = typer.Option(None, "--entrypoint", help="Container entrypoint as a shell-style string"),
-    image: str = typer.Option(None, "--image", help="Override the default reef image"),
+    image: str = typer.Option(None, "--image", help="Override the default OpenClaw image"),
     registry_url: str = typer.Option(None, "--registry-url", help="Container registry URL for private image pulls"),
     registry_username: str = typer.Option(None, "--registry-username", help="Registry username"),
     registry_password: str = typer.Option(None, "--registry-password", help="Registry password"),
@@ -303,7 +313,7 @@ def create(
             ports=ports_list,
             command=command_argv,
             entrypoint=entrypoint_argv,
-            image=image,
+            image=_default_openclaw_image(image),
             registry_url=registry_url,
             registry_auth=registry_auth,
             gateway_token=gateway_token,
@@ -322,7 +332,7 @@ def create(
     console.print(f"  Size:     {pod.cpu} CPU, {pod.memory} GB")
     console.print(f"  State:    {pod.state}")
     console.print(f"  Desktop:  {pod.vnc_url}")
-    console.print(f"  Shell:    {pod.shell_url}")
+    console.print(f"  Shell:    {'via hyper agents shell' if not pod.shell_url else pod.shell_url}")
     display_ports = pod.ports or ports_list or []
     for p in display_ports:
         auth_text = "auth" if p.get("auth", True) else "noauth"
@@ -330,26 +340,14 @@ def create(
 
     if wait and not pod.dry_run:
         console.print("\n[dim]Waiting for pod to start...[/dim]")
-        for i in range(60):
-            time.sleep(5)
-            try:
-                pod = agents.get(pod.id)
-                _save_pod_state(pod)
-                if pod.is_running:
-                    console.print(f"[green]✅ Agent is running![/green]")
-                    break
-                elif pod.state in ("failed", "stopped"):
-                    console.print(f"[red]❌ Agent failed: {pod.state}[/red]")
-                    if pod.last_error:
-                        console.print(f"  Error: {pod.last_error}")
-                    raise typer.Exit(1)
-                else:
-                    console.print(f"  [{i*5}s] State: {pod.state}")
-            except typer.Exit:
-                raise
-            except Exception as e:
-                console.print(f"  [{i*5}s] Checking... ({e})")
-        else:
+        try:
+            pod = agents.wait_running(pod.id, timeout=300, poll_interval=5)
+            _save_pod_state(pod)
+            console.print(f"[green]✅ Agent is running![/green]")
+        except RuntimeError as e:
+            console.print(f"[red]❌ Agent failed: {e}[/red]")
+            raise typer.Exit(1)
+        except TimeoutError:
             console.print("[yellow]⚠ Timed out (5 min). Pod may still be starting.[/yellow]")
 
     if pod.dry_run:
@@ -360,6 +358,33 @@ def create(
         console.print(f"Desktop: {pod.vnc_url}")
 
 
+@app.command("wait")
+def wait_agent(
+    agent_id: str = typer.Argument(None, help="Agent ID or name"),
+    timeout: int = typer.Option(300, "--timeout", help="Seconds to wait for RUNNING"),
+    poll_interval: float = typer.Option(5.0, "--poll-interval", help="Seconds between polls"),
+):
+    """Wait for an agent to reach RUNNING."""
+    agents = _get_deployments_client()
+    pod = _get_pod_with_token(agent_id)
+
+    try:
+        pod = agents.wait_running(pod.id, timeout=timeout, poll_interval=poll_interval)
+    except RuntimeError as e:
+        console.print(f"[red]❌ Agent failed: {e}[/red]")
+        raise typer.Exit(1)
+    except TimeoutError as e:
+        console.print(f"[yellow]⚠ {e}[/yellow]")
+        raise typer.Exit(1)
+
+    _save_pod_state(pod)
+    console.print(f"[green]✅ Agent is running:[/green] [bold]{pod.id[:12]}[/bold]")
+    console.print(f"  Name:     {pod.name or pod.pod_name}")
+    console.print(f"  State:    {pod.state}")
+    console.print(f"  Desktop:  {pod.vnc_url}")
+    console.print(f"  Shell:    {'via hyper agents shell' if not pod.shell_url else pod.shell_url}")
+
+
 @app.command("list")
 def list_agents(
     json_output: bool = typer.Option(False, "--json", help="JSON output"),
@@ -442,7 +467,7 @@ def status(
     console.print(f"  Size:       {pod.cpu} CPU, {pod.memory} GB")
     console.print(f"  State:      {pod.state}")
     console.print(f"  Desktop:    {pod.vnc_url}")
-    console.print(f"  Shell:      {pod.shell_url}")
+    console.print(f"  Shell:      {'via hyper agents shell' if not pod.shell_url else pod.shell_url}")
     console.print(f"  Created:    {pod.created_at}")
     if pod.started_at:
         console.print(f"  Started:    {pod.started_at}")
@@ -470,7 +495,7 @@ def start(
     port: list[str] = typer.Option(None, "--port", help="Expose port as PORT or PORT:noauth. Repeatable."),
     command: str = typer.Option(None, "--command", help="Container args as a shell-style string"),
     entrypoint: str = typer.Option(None, "--entrypoint", help="Container entrypoint as a shell-style string"),
-    image: str = typer.Option(None, "--image", help="Override the default reef image"),
+    image: str = typer.Option(None, "--image", help="Override the default OpenClaw image"),
     registry_url: str = typer.Option(None, "--registry-url", help="Container registry URL for private image pulls"),
     registry_username: str = typer.Option(None, "--registry-username", help="Registry username"),
     registry_password: str = typer.Option(None, "--registry-password", help="Registry password"),
@@ -489,6 +514,7 @@ def start(
     registry_auth = _build_registry_auth(registry_username, registry_password)
     launch_config = dict(local.get("launch_config") or {})
     effective_gateway_token = gateway_token or local.get("gateway_token")
+    effective_image = _default_openclaw_image(image, launch_config)
 
     try:
         pod = agents.start(
@@ -498,7 +524,7 @@ def start(
             ports=ports_list,
             command=command_argv,
             entrypoint=entrypoint_argv,
-            image=image,
+            image=effective_image,
             registry_url=registry_url,
             registry_auth=registry_auth,
             gateway_token=effective_gateway_token,
@@ -978,18 +1004,21 @@ def gateway_cron(
 def gateway_chat(
     agent_id: str = typer.Argument(None, help="Agent ID or name"),
     message: str = typer.Argument(..., help="Message to send"),
+    session_key: str = typer.Option("main", "--session-key", help="Gateway chat session key"),
 ):
     """Send a chat message to an agent via the Gateway and stream the response."""
     pod = _require_openclaw_agent(_get_pod_with_token(agent_id))
 
     async def _run():
-        async for event in pod.chat_send(message):
+        async for event in pod.chat_send(message, session_key=session_key):
             if event.type == "content":
                 print(event.text, end="", flush=True)
             elif event.type == "thinking":
                 console.print(f"[dim]{event.text}[/dim]", end="")
             elif event.type == "tool_call":
                 console.print(f"\n[yellow]🔧 {event.data}[/yellow]")
+            elif event.type == "tool_result":
+                console.print(f"\n[cyan]📤 {event.data}[/cyan]")
             elif event.type == "error":
                 console.print(f"\n[red]❌ {event.text}[/red]")
             elif event.type == "done":

{hypercli_cli-2026.3.13 → hypercli_cli-2026.3.22}/hypercli_cli/cli.py

@@ -1,5 +1,6 @@
 """HyperCLI - Main entry point"""
 import sys
+import json
 import typer
 from rich.console import Console
 from rich.prompt import Prompt
@@ -143,7 +144,8 @@ def cli():
     try:
         app()
     except APIError as e:
-        detail = e.detail or str(e)
+        raw_detail = e.detail or str(e)
+        detail = raw_detail if isinstance(raw_detail, str) else json.dumps(raw_detail)
 
         # Check for GPU type errors and suggest corrections
         if "GPU type" in detail and "not found" in detail and "Available:" in detail:

{hypercli_cli-2026.3.13 → hypercli_cli-2026.3.22}/hypercli_cli/embed.py

@@ -17,10 +17,10 @@ DEV_API_BASE = "https://api.dev.hypercli.com"
 
 
 def _get_api_key(key: str | None) -> str:
-    """Resolve API key: --key flag > env HYPERCLAW_API_KEY > agent-key.json."""
+    """Resolve API key: --key flag > env HYPER_API_KEY > agent-key.json."""
     if key:
         return key
-    env_key = os.environ.get("HYPERCLAW_API_KEY", "").strip()
+    env_key = os.environ.get("HYPER_API_KEY", "").strip()
     if env_key:
         return env_key
     if AGENT_KEY_PATH.exists():
@@ -29,7 +29,7 @@ def _get_api_key(key: str | None) -> str:
         if k:
             return k
     console.print("[red]❌ No API key found.[/red]")
-    console.print("Pass [bold]--key sk-...[/bold], set [bold]HYPERCLAW_API_KEY[/bold], or run [bold]hyper agent subscribe[/bold]")
+    console.print("Pass [bold]--key sk-...[/bold], set [bold]HYPER_API_KEY[/bold], or run [bold]hyper agent subscribe[/bold]")
     raise typer.Exit(1)
 
 

{hypercli_cli-2026.3.13 → hypercli_cli-2026.3.22}/hypercli_cli/instances.py

@@ -11,6 +11,21 @@ def get_client() -> HyperCLI:
     return HyperCLI()
 
 
+def _parse_constraints(
+    constraints: Optional[list[str]],
+    cpu_vendor: Optional[str],
+) -> dict[str, str] | None:
+    parsed: dict[str, str] = {}
+    for item in constraints or []:
+        key, sep, value = item.partition("=")
+        if not sep or not key or not value:
+            raise typer.BadParameter(f"Invalid constraint '{item}', expected KEY=VALUE")
+        parsed[key.strip()] = value.strip()
+    if cpu_vendor:
+        parsed.setdefault("cpu_vendor", cpu_vendor.strip())
+    return parsed or None
+
+
 @app.command("list")
 def list_instances(
     gpu: Optional[str] = typer.Option(None, "--gpu", "-g", help="Filter by GPU type"),
@@ -64,7 +79,13 @@ def list_gpus(
 
     if fmt == "json":
         output({k: {"name": v.name, "description": v.description, "configs": [
-            {"gpu_count": c.gpu_count, "cpu_cores": c.cpu_cores, "memory_gb": c.memory_gb, "regions": c.regions}
+            {
+                "gpu_count": c.gpu_count,
+                "cpu_cores": c.cpu_cores,
+                "memory_gb": c.memory_gb,
+                "regions": c.regions,
+                "constraints": c.constraints,
+            }
             for c in v.configs
         ]} for k, v in types.items()}, "json")
     else:
@@ -187,6 +208,8 @@ def launch(
     gpu: str = typer.Option("l40s", "--gpu", "-g", help="GPU type"),
     count: int = typer.Option(1, "--count", "-n", help="Number of GPUs"),
     region: Optional[str] = typer.Option(None, "--region", "-r", help="Region code"),
+    constraint: Optional[list[str]] = typer.Option(None, "--constraint", help="Placement constraint KEY=VALUE (repeatable)"),
+    cpu_vendor: Optional[str] = typer.Option(None, "--cpu-vendor", help="CPU vendor constraint (e.g. intel, amd)"),
     runtime: Optional[int] = typer.Option(None, "--runtime", "-t", help="Runtime in seconds"),
     interruptible: bool = typer.Option(True, "--interruptible/--on-demand", help="Use interruptible instances"),
     env: Optional[list[str]] = typer.Option(None, "--env", "-e", help="Env vars (KEY=VALUE)"),
@@ -256,6 +279,8 @@ def launch(
     if command and any(op in command for op in ["&&", "||", "|", ";", ">", "<", "$"]):
         command = f'sh -c "{command}"'
 
+    constraints = _parse_constraints(constraint, cpu_vendor)
+
     follow_api_key = None
 
     if x402:
@@ -281,6 +306,7 @@ def launch(
                 gpu_type=gpu,
                 gpu_count=count,
                 region=region,
+                constraints=constraints,
                 interruptible=interruptible,
                 env=env_dict,
                 ports=ports_dict,
@@ -330,6 +356,7 @@ def launch(
                 gpu_type=gpu,
                 gpu_count=count,
                 region=region,
+                constraints=constraints,
                 runtime=runtime,
                 interruptible=interruptible,
                 env=env_dict,

{hypercli_cli-2026.3.13 → hypercli_cli-2026.3.22}/hypercli_cli/voice.py

@@ -18,10 +18,13 @@ DEFAULT_API_BASE = "https://api.hypercli.com"
 
 
 def _get_api_key(key: str | None) -> str:
-    """Resolve API key: --key flag > env HYPERCLAW_API_KEY > agent-key.json."""
+    """Resolve API key: --key > HYPER_API_KEY > HYPER_AGENTS_API_KEY > agent-key.json."""
     if key:
         return key
-    env_key = os.environ.get("HYPERCLAW_API_KEY", "").strip()
+    env_key = os.environ.get("HYPER_API_KEY", "").strip()
+    if env_key:
+        return env_key
+    env_key = os.environ.get("HYPER_AGENTS_API_KEY", "").strip()
     if env_key:
         return env_key
     if AGENT_KEY_PATH.exists():
@@ -30,15 +33,18 @@ def _get_api_key(key: str | None) -> str:
         if k:
             return k
     console.print("[red]❌ No API key found.[/red]")
-    console.print("Pass [bold]--key sk-...[/bold], set [bold]HYPERCLAW_API_KEY[/bold], or run [bold]hyper agent subscribe[/bold]")
+    console.print("Pass [bold]--key sk-...[/bold], set [bold]HYPER_API_KEY[/bold] or [bold]HYPER_AGENTS_API_KEY[/bold], or run [bold]hyper agent subscribe[/bold]")
     raise typer.Exit(1)
 
 
 def _resolve_api_base(base_url: str | None) -> str:
-    """Resolve API base: --base-url > HYPERCLAW_API_BASE env > default."""
+    """Resolve API base: --base-url > HYPER_API_BASE > HYPERCLI_API_URL > default."""
     if base_url:
         return base_url.rstrip("/")
-    env_base = os.environ.get("HYPERCLAW_API_BASE", "").strip()
+    env_base = os.environ.get("HYPER_API_BASE", "").strip()
+    if env_base:
+        return env_base.rstrip("/")
+    env_base = os.environ.get("HYPERCLI_API_URL", "").strip()
     if env_base:
         return env_base.rstrip("/")
     return DEFAULT_API_BASE

{hypercli_cli-2026.3.13 → hypercli_cli-2026.3.22}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypercli-cli"
-version = "2026.3.13"
+version = "2026.3.22"
 description = "CLI for HyperCLI - GPU orchestration and LLM API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -13,7 +13,7 @@ authors = [
     { name = "HyperCLI", email = "support@hypercli.com" }
 ]
 dependencies = [
-    "hypercli-sdk>=2026.3.13",
+    "hypercli-sdk>=2026.3.22",
     "typer>=0.20.0",
     "rich>=14.2.0",
     "websocket-client>=1.6.0",
@@ -24,7 +24,7 @@ dependencies = [
 
 [project.optional-dependencies]
 comfyui = [
-    "hypercli-sdk[comfyui]>=2026.3.13",
+    "hypercli-sdk[comfyui]>=2026.3.22",
 ]
 wallet = [
     "x402[httpx,evm]>=2.0.0",
@@ -37,7 +37,7 @@ stt = [
     "faster-whisper>=1.1.0",
 ]
 all = [
-    "hypercli-sdk[comfyui]>=2026.3.13",
+    "hypercli-sdk[comfyui]>=2026.3.22",
     "x402[httpx,evm]>=2.0.0",
     "eth-account>=0.13.0",
     "web3>=7.0.0",

hypercli_cli-2026.3.22/tests/test_agent_env_resolution.py

@@ -0,0 +1,39 @@
+import importlib
+
+
+def test_agents_cli_prefers_agent_key_env(monkeypatch):
+    monkeypatch.setenv("HYPER_API_KEY", "sk-product")
+    monkeypatch.setenv("HYPER_AGENTS_API_KEY", "sk-agent")
+
+    import hypercli_cli.agents as agents
+
+    importlib.reload(agents)
+
+    assert agents._get_agent_api_key() == "sk-agent"
+
+
+def test_agents_cli_prefers_agent_base_env(monkeypatch):
+    monkeypatch.setenv("AGENTS_API_BASE_URL", "https://api.agents.dev.hypercli.com")
+    monkeypatch.setenv("AGENTS_WS_URL", "wss://api.agents.dev.hypercli.com/ws")
+    monkeypatch.setenv("HYPER_AGENTS_API_KEY", "sk-agent")
+
+    import hypercli_cli.agents as agents
+
+    importlib.reload(agents)
+
+    client = agents._get_deployments_client()
+    assert client._api_base == "https://api.dev.hypercli.com/agents"
+
+
+def test_voice_cli_prefers_product_envs(monkeypatch):
+    monkeypatch.setenv("HYPER_API_KEY", "sk-product")
+    monkeypatch.setenv("HYPER_AGENTS_API_KEY", "sk-agent")
+    monkeypatch.setenv("HYPER_API_BASE", "https://api.hypercli.com")
+    monkeypatch.setenv("HYPERCLI_API_URL", "https://api.dev.hypercli.com")
+
+    import hypercli_cli.voice as voice
+
+    importlib.reload(voice)
+
+    assert voice._get_api_key(None) == "sk-product"
+    assert voice._resolve_api_base(None) == "https://api.hypercli.com"

{hypercli_cli-2026.3.13 → hypercli_cli-2026.3.22}/tests/test_exec_shell_dryrun.py

@@ -98,6 +98,52 @@ def test_instances_launch_dry_run_mock(monkeypatch):
     assert "job-dryrun" in result.stdout
 
 
+def test_instances_launch_dry_run_includes_constraints(monkeypatch):
+    captured = {}
+
+    class FakeJobs:
+        def create(self, **kwargs):
+            captured.update(kwargs)
+            return SimpleNamespace(
+                job_id="job-dryrun",
+                state="validated",
+                gpu_type="h200",
+                gpu_count=8,
+                region="br",
+                constraints={"cpu_vendor": "amd"},
+                price_per_hour=12.34,
+                runtime=300,
+                cold_boot=False,
+                hostname=None,
+            )
+
+    fake_client = SimpleNamespace(jobs=FakeJobs())
+    monkeypatch.setattr("hypercli_cli.instances.get_client", lambda: fake_client)
+
+    result = runner.invoke(
+        app,
+        [
+            "instances",
+            "launch",
+            "nvidia/cuda:12.0-base-ubuntu22.04",
+            "--dry-run",
+            "--gpu",
+            "h200",
+            "--count",
+            "8",
+            "--cpu-vendor",
+            "amd",
+            "--constraint",
+            "stack=prod",
+            "--output",
+            "json",
+        ],
+    )
+
+    assert result.exit_code == 0
+    assert captured["constraints"] == {"cpu_vendor": "amd", "stack": "prod"}
+
+
 def test_agent_exec_command(monkeypatch):
     called = {}
 

hypercli_cli-2026.3.22/tests/test_openclaw_config.py

@@ -0,0 +1,63 @@
+from hypercli_cli.agent import _config_openclaw
+
+
+def test_config_openclaw_limits_runtime_models_to_supported_set():
+    api_key = "sk-test"
+    api_base = "https://api.agents.hypercli.com"
+    models = [
+        {"id": "kimi-k2.5", "name": "Kimi K2.5", "reasoning": True},
+        {"id": "glm-5", "name": "GLM-5", "reasoning": True},
+        {
+            "id": "qwen3-embedding-4b",
+            "name": "Qwen3 Embedding 4B",
+            "reasoning": False,
+            "mode": "embedding",
+        },
+        {"id": "claude-sonnet-4", "name": "Claude Sonnet 4", "reasoning": False},
+        {"id": "minimax-m2.5", "name": "MiniMax M2.5", "reasoning": False},
+    ]
+
+    config = _config_openclaw(api_key, models, api_base)
+    providers = config["models"]["providers"]
+
+    assert set(providers) == {"hyperclaw", "kimi-coding"}
+    assert [m["id"] for m in providers["hyperclaw"]["models"]] == ["glm-5"]
+    assert [m["id"] for m in providers["kimi-coding"]["models"]] == ["kimi-k2.5"]
+
+    defaults = config["agents"]["defaults"]
+    assert defaults["model"]["primary"] == "kimi-coding/kimi-k2.5"
+    assert defaults["memorySearch"]["provider"] == "openai"
+    assert defaults["memorySearch"]["model"] == "qwen3-embedding-4b"
+    assert defaults["memorySearch"]["remote"]["baseUrl"] == "https://api.agents.hypercli.com/v1"
+
+
+def test_config_openclaw_uses_first_embedding_model_for_memory_search():
+    config = _config_openclaw(
+        "sk-test",
+        [
+            {"id": "kimi-k2.5", "name": "Kimi K2.5", "reasoning": True},
+            {"id": "text-embedding-3-large", "name": "Text Embedding 3 Large", "mode": "embedding"},
+        ],
+        "https://api.agents.hypercli.com",
+    )
+
+    defaults = config["agents"]["defaults"]
+    assert defaults["memorySearch"]["model"] == "text-embedding-3-large"
+
+
+def test_config_openclaw_supports_placeholder_api_key_env():
+    config = _config_openclaw(
+        "sk-real",
+        [
+            {"id": "kimi-k2.5", "name": "Kimi K2.5", "reasoning": True},
+            {"id": "glm-5", "name": "GLM-5", "reasoning": True},
+            {"id": "qwen3-embedding-4b", "name": "Qwen3 Embedding 4B", "mode": "embedding"},
+        ],
+        "https://api.agents.hypercli.com",
+        placeholder_env="HYPER_API_KEY",
+    )
+
+    providers = config["models"]["providers"]
+    assert providers["hyperclaw"]["apiKey"] == "${HYPER_API_KEY}"
+    assert providers["kimi-coding"]["apiKey"] == "${HYPER_API_KEY}"
+    assert config["agents"]["defaults"]["memorySearch"]["remote"]["apiKey"] == "${HYPER_API_KEY}"

hypercli_cli-2026.3.13/hypercli_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "2026.3.13"