opensandbox-cli 0.1.0.dev1__py3-none-any.whl

opensandbox_cli/__init__.py

@@ -0,0 +1,20 @@
+# Copyright 2026 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("opensandbox-cli")
+except Exception:
+    __version__ = "0.0.0-dev"

opensandbox_cli/__main__.py

@@ -0,0 +1,20 @@
+# Copyright 2026 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Allow running as ``python -m opensandbox_cli``."""
+
+from opensandbox_cli.main import cli
+
+if __name__ == "__main__":
+    cli()

opensandbox_cli/client.py

@@ -0,0 +1,172 @@
+# Copyright 2026 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""SDK client factory stored in Click context."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import timedelta
+from typing import Any
+
+import click
+import httpx
+from opensandbox.config.connection_sync import ConnectionConfigSync
+from opensandbox.models.sandboxes import SandboxFilter
+from opensandbox.sync.manager import SandboxManagerSync
+from opensandbox.sync.sandbox import SandboxSync
+
+from opensandbox_cli.output import OutputFormatter
+
+# Full UUID pattern: 8-4-4-4-12 hex characters
+_UUID_RE = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+
+
+@dataclass
+class ClientContext:
+    """Shared context passed via ``ctx.obj`` to all Click commands."""
+
+    resolved_config: dict[str, Any]
+    output: OutputFormatter
+    _connection_config: ConnectionConfigSync | None = field(
+        default=None, init=False, repr=False
+    )
+    _manager: SandboxManagerSync | None = field(
+        default=None, init=False, repr=False
+    )
+    _shared_transport: httpx.BaseTransport | None = field(
+        default=None, init=False, repr=False
+    )
+    _devops_client: httpx.Client | None = field(
+        default=None, init=False, repr=False
+    )
+
+    @property
+    def connection_config(self) -> ConnectionConfigSync:
+        if self._connection_config is None:
+            cfg = self.resolved_config
+            self._shared_transport = httpx.HTTPTransport(
+                limits=httpx.Limits(
+                    max_connections=100,
+                    max_keepalive_connections=20,
+                    keepalive_expiry=30.0,
+                ),
+            )
+            self._connection_config = ConnectionConfigSync(
+                api_key=cfg.get("api_key"),
+                domain=cfg.get("domain"),
+                protocol=cfg.get("protocol", "http"),
+                request_timeout=timedelta(seconds=cfg.get("request_timeout", 30)),
+                use_server_proxy=cfg.get("use_server_proxy", False),
+                transport=self._shared_transport,
+            )
+        return self._connection_config
+
+    def get_devops_client(self) -> httpx.Client:
+        """Return a cached HTTP client for experimental diagnostics endpoints."""
+        if self._devops_client is None:
+            config = self.connection_config
+            headers = dict(config.headers)
+            headers.setdefault("Accept", "text/plain")
+            headers.setdefault("User-Agent", config.user_agent)
+            if config.api_key:
+                headers["OPEN-SANDBOX-API-KEY"] = config.api_key
+
+            self._devops_client = httpx.Client(
+                base_url=config.get_base_url(),
+                headers=headers,
+                timeout=config.request_timeout.total_seconds(),
+                transport=self._shared_transport,
+            )
+        return self._devops_client
+
+    def get_manager(self) -> SandboxManagerSync:
+        """Return a lazily-created ``SandboxManagerSync``."""
+        if self._manager is None:
+            self._manager = SandboxManagerSync.create(self.connection_config)
+        return self._manager
+
+    def resolve_sandbox_id(self, prefix: str) -> str:
+        """Resolve a sandbox ID prefix to the full ID (Docker-style).
+
+        If *prefix* looks like a complete UUID, it is returned as-is without
+        querying the server.  Otherwise **all pages** of sandboxes are fetched
+        so that prefix collisions on later pages are never missed.
+        """
+        # Skip resolution for full UUIDs
+        if _UUID_RE.match(prefix):
+            return prefix
+
+        mgr = self.get_manager()
+        matches: list[str] = []
+        page = 0
+
+        while True:
+            result = mgr.list_sandbox_infos(
+                SandboxFilter(page=page, page_size=100)
+            )
+            if result.sandbox_infos:
+                matches.extend(
+                    info.id
+                    for info in result.sandbox_infos
+                    if info.id.startswith(prefix)
+                )
+            # Stop early if we already found >1 match (ambiguous)
+            if len(matches) > 1:
+                break
+            if not result.pagination.has_next_page:
+                break
+            page += 1
+
+        if len(matches) == 1:
+            return matches[0]
+        elif len(matches) == 0:
+            raise click.ClickException(
+                f"No sandbox found with ID prefix '{prefix}'"
+            )
+        else:
+            ids_str = ", ".join(matches[:5])
+            if len(matches) > 5:
+                ids_str += ", ..."
+            raise click.ClickException(
+                f"Ambiguous ID prefix '{prefix}' matches {len(matches)} sandboxes: {ids_str}"
+            )
+
+    def connect_sandbox(
+        self, sandbox_id: str, *, skip_health_check: bool = True
+    ) -> SandboxSync:
+        """Connect to an existing sandbox by ID (supports prefix matching)."""
+        sandbox_id = self.resolve_sandbox_id(sandbox_id)
+        return SandboxSync.connect(
+            sandbox_id,
+            connection_config=self.connection_config,
+            skip_health_check=skip_health_check,
+        )
+
+    def close(self) -> None:
+        """Release resources."""
+        if self._manager is not None:
+            self._manager.close()
+            self._manager = None
+        if self._devops_client is not None:
+            self._devops_client.close()
+            self._devops_client = None
+        if self._connection_config is not None:
+            self._connection_config = None
+        if self._shared_transport is not None:
+            self._shared_transport.close()
+            self._shared_transport = None

opensandbox_cli/commands/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2026 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

opensandbox_cli/commands/command.py

@@ -0,0 +1,303 @@
+# Copyright 2026 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Command execution commands: one-shot commands and persistent sessions."""
+
+from __future__ import annotations
+
+import shlex
+import sys
+from datetime import timedelta
+
+import click
+from opensandbox.models.execd import OutputMessage, RunCommandOpts
+from opensandbox.models.execd_sync import ExecutionHandlersSync
+
+from opensandbox_cli.client import ClientContext
+from opensandbox_cli.utils import DURATION, handle_errors
+
+
+@click.group("command", invoke_without_command=True)
+@click.pass_context
+def command_group(ctx: click.Context) -> None:
+    """⚡ Execute commands in a sandbox."""
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+# ---- run ------------------------------------------------------------------
+
+def _run_command(
+    obj: ClientContext,
+    sandbox_id: str,
+    command: tuple[str, ...],
+    background: bool,
+    workdir: str | None,
+    timeout: timedelta | None,
+) -> None:
+    """Shared implementation for 'command run' and top-level 'exec'."""
+    cmd_str = " ".join(shlex.quote(arg) for arg in command)
+    sandbox = obj.connect_sandbox(sandbox_id)
+
+    try:
+        opts = RunCommandOpts(
+            background=background,
+            working_directory=workdir,
+            timeout=timeout,
+        )
+
+        if background:
+            execution = sandbox.commands.run(cmd_str, opts=opts)
+            obj.output.success_panel(
+                {
+                    "execution_id": execution.id,
+                    "sandbox_id": sandbox_id,
+                    "mode": "background",
+                },
+                title="Background Command Started",
+            )
+            return
+
+        # Foreground: stream stdout/stderr to terminal
+        last_text = ""
+
+        def on_stdout(msg: OutputMessage) -> None:
+            nonlocal last_text
+            last_text = msg.text
+            sys.stdout.write(msg.text)
+            sys.stdout.flush()
+
+        def on_stderr(msg: OutputMessage) -> None:
+            nonlocal last_text
+            last_text = msg.text
+            sys.stderr.write(msg.text)
+            sys.stderr.flush()
+
+        handlers = ExecutionHandlersSync(on_stdout=on_stdout, on_stderr=on_stderr)
+        execution = sandbox.commands.run(cmd_str, opts=opts, handlers=handlers)
+
+        # Ensure terminal prompt starts on a new line
+        if last_text and not last_text.endswith("\n"):
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+
+        _handle_execution_error(obj, execution)
+    finally:
+        sandbox.close()
+
+
+def _handle_execution_error(obj: ClientContext, execution) -> None:
+    """Exit non-zero if the execution finished with an error."""
+    if execution.error:
+        obj.output.error_panel(
+            f"{execution.error.name}: {execution.error.value}",
+            title="Execution Error",
+        )
+        sys.exit(1)
+
+
+@command_group.command("run")
+@click.argument("sandbox_id")
+@click.argument("command", nargs=-1, required=True)
+@click.option("-d", "--background", is_flag=True, default=False, help="Run in background.")
+@click.option("-w", "--workdir", default=None, help="Working directory.")
+@click.option("-t", "--timeout", type=DURATION, default=None, help="Command timeout (e.g. 30s, 5m).")
+@click.pass_obj
+@handle_errors
+def command_run(
+    obj: ClientContext,
+    sandbox_id: str,
+    command: tuple[str, ...],
+    background: bool,
+    workdir: str | None,
+    timeout: timedelta | None,
+) -> None:
+    """Run a command in a sandbox."""
+    _run_command(obj, sandbox_id, command, background, workdir, timeout)
+
+
+# ---- status ---------------------------------------------------------------
+
+@command_group.command("status")
+@click.argument("sandbox_id")
+@click.argument("execution_id")
+@click.pass_obj
+@handle_errors
+def command_status(obj: ClientContext, sandbox_id: str, execution_id: str) -> None:
+    """Get command execution status."""
+    sandbox = obj.connect_sandbox(sandbox_id)
+    try:
+        status = sandbox.commands.get_command_status(execution_id)
+        obj.output.print_model(status, title="Command Status")
+    finally:
+        sandbox.close()
+
+
+# ---- logs -----------------------------------------------------------------
+
+@command_group.command("logs")
+@click.argument("sandbox_id")
+@click.argument("execution_id")
+@click.option("--cursor", type=int, default=None, help="Cursor for incremental reads.")
+@click.pass_obj
+@handle_errors
+def command_logs(
+    obj: ClientContext, sandbox_id: str, execution_id: str, cursor: int | None
+) -> None:
+    """Get background command logs."""
+    sandbox = obj.connect_sandbox(sandbox_id)
+    try:
+        logs = sandbox.commands.get_background_command_logs(execution_id, cursor=cursor)
+        if obj.output.fmt in ("json", "yaml"):
+            obj.output.print_model(logs, title="Command Logs")
+        else:
+            click.echo(logs.content)
+    finally:
+        sandbox.close()
+
+
+# ---- interrupt ------------------------------------------------------------
+
+@command_group.command("interrupt")
+@click.argument("sandbox_id")
+@click.argument("execution_id")
+@click.pass_obj
+@handle_errors
+def command_interrupt(obj: ClientContext, sandbox_id: str, execution_id: str) -> None:
+    """Interrupt a running command."""
+    sandbox = obj.connect_sandbox(sandbox_id)
+    try:
+        sandbox.commands.interrupt(execution_id)
+        obj.output.success(f"Interrupted: {execution_id}")
+    finally:
+        sandbox.close()
+
+
+@command_group.group("session", invoke_without_command=True)
+@click.pass_context
+def session_group(ctx: click.Context) -> None:
+    """Manage persistent bash sessions."""
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+@session_group.command("create")
+@click.argument("sandbox_id")
+@click.option("-w", "--workdir", default=None, help="Initial working directory.")
+@click.pass_obj
+@handle_errors
+def session_create(obj: ClientContext, sandbox_id: str, workdir: str | None) -> None:
+    """Create a persistent bash session."""
+    sandbox = obj.connect_sandbox(sandbox_id)
+    try:
+        session_id = sandbox.commands.create_session(working_directory=workdir)
+        obj.output.success_panel(
+            {
+                "sandbox_id": sandbox.id,
+                "session_id": session_id,
+                "working_directory": workdir,
+            },
+            title="Session Created",
+        )
+    finally:
+        sandbox.close()
+
+
+@session_group.command("run")
+@click.argument("sandbox_id")
+@click.argument("session_id")
+@click.argument("command", nargs=-1, required=True)
+@click.option("-w", "--workdir", default=None, help="Working directory override for this run.")
+@click.option("-t", "--timeout", type=DURATION, default=None, help="Command timeout (e.g. 30s, 5m).")
+@click.pass_obj
+@handle_errors
+def session_run(
+    obj: ClientContext,
+    sandbox_id: str,
+    session_id: str,
+    command: tuple[str, ...],
+    workdir: str | None,
+    timeout: timedelta | None,
+) -> None:
+    """Run a command in an existing bash session."""
+    cmd_str = " ".join(shlex.quote(arg) for arg in command)
+    sandbox = obj.connect_sandbox(sandbox_id)
+    try:
+        last_text = ""
+
+        def on_stdout(msg: OutputMessage) -> None:
+            nonlocal last_text
+            last_text = msg.text
+            sys.stdout.write(msg.text)
+            sys.stdout.flush()
+
+        def on_stderr(msg: OutputMessage) -> None:
+            nonlocal last_text
+            last_text = msg.text
+            sys.stderr.write(msg.text)
+            sys.stderr.flush()
+
+        handlers = ExecutionHandlersSync(on_stdout=on_stdout, on_stderr=on_stderr)
+        execution = sandbox.commands.run_in_session(
+            session_id,
+            cmd_str,
+            working_directory=workdir,
+            timeout=int(timeout.total_seconds() * 1000) if timeout is not None else None,
+            handlers=handlers,
+        )
+
+        if last_text and not last_text.endswith("\n"):
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+
+        _handle_execution_error(obj, execution)
+    finally:
+        sandbox.close()
+
+
+@session_group.command("delete")
+@click.argument("sandbox_id")
+@click.argument("session_id")
+@click.pass_obj
+@handle_errors
+def session_delete(obj: ClientContext, sandbox_id: str, session_id: str) -> None:
+    """Delete a persistent bash session."""
+    sandbox = obj.connect_sandbox(sandbox_id)
+    try:
+        sandbox.commands.delete_session(session_id)
+        obj.output.success(f"Deleted session: {session_id}")
+    finally:
+        sandbox.close()
+
+
+# ---- top-level exec alias ------------------------------------------------
+
+@click.command("exec")
+@click.argument("sandbox_id")
+@click.argument("command", nargs=-1, required=True)
+@click.option("-d", "--background", is_flag=True, default=False, help="Run in background.")
+@click.option("-w", "--workdir", default=None, help="Working directory.")
+@click.option("-t", "--timeout", type=DURATION, default=None, help="Command timeout (e.g. 30s, 5m).")
+@click.pass_obj
+@handle_errors
+def exec_cmd(
+    obj: ClientContext,
+    sandbox_id: str,
+    command: tuple[str, ...],
+    background: bool,
+    workdir: str | None,
+    timeout: timedelta | None,
+) -> None:
+    """🚀 Execute a command in a sandbox (shortcut for 'command run')."""
+    _run_command(obj, sandbox_id, command, background, workdir, timeout)

opensandbox_cli/commands/config_cmd.py

@@ -0,0 +1,145 @@
+# Copyright 2026 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Config management commands: init, show, set."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from opensandbox_cli.client import ClientContext
+from opensandbox_cli.config import DEFAULT_CONFIG_PATH, init_config_file
+from opensandbox_cli.utils import handle_errors
+
+
+@click.group("config", invoke_without_command=True)
+@click.pass_context
+def config_group(ctx: click.Context) -> None:
+    """⚙️  Manage CLI configuration."""
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+# ---- init -----------------------------------------------------------------
+
+@config_group.command("init")
+@click.option("--force", is_flag=True, default=False, help="Overwrite existing config file.")
+@click.option("--path", "config_path", type=click.Path(path_type=Path), default=None, help="Config file path.")
+@handle_errors
+def config_init(force: bool, config_path: Path | None) -> None:
+    """Create a default configuration file."""
+    # config_init doesn't have @click.pass_obj, get formatter from context
+    ctx = click.get_current_context(silent=True)
+    obj = getattr(ctx, "obj", None) if ctx else None
+    output = getattr(obj, "output", None) if obj else None
+
+    try:
+        path = init_config_file(config_path, force=force)
+        if output:
+            output.success(f"Config file created: {path}")
+        else:
+            click.echo(f"Config file created: {path}")
+    except FileExistsError as exc:
+        if output:
+            output.warning(str(exc))
+        else:
+            click.secho(str(exc), fg="yellow", err=True)
+
+
+# ---- show -----------------------------------------------------------------
+
+@config_group.command("show")
+@click.pass_obj
+@handle_errors
+def config_show(obj: ClientContext) -> None:
+    """Show the resolved configuration."""
+    obj.output.print_dict(obj.resolved_config, title="Resolved Configuration")
+
+
+# ---- set ------------------------------------------------------------------
+
+@config_group.command("set")
+@click.argument("key")
+@click.argument("value")
+@click.option("--path", "config_path", type=click.Path(path_type=Path), default=None, help="Config file path.")
+@handle_errors
+def config_set(key: str, value: str, config_path: Path | None) -> None:
+    """Set a configuration value (e.g. 'connection.domain' 'localhost:9090')."""
+    path = config_path or DEFAULT_CONFIG_PATH
+    if not path.exists():
+        click.secho(f"Config file not found: {path}. Run 'osb config init' first.", fg="red", err=True)
+        return
+
+    content = path.read_text()
+
+    # Simple key replacement in TOML
+    # Supports dotted keys like connection.domain
+    parts = key.split(".", 1)
+    if len(parts) == 2:
+        section, field = parts
+        # Try to find and update existing value
+        import re
+
+        section_pattern = rf"(\[{re.escape(section)}\].*?)(?=\n\[|\Z)"
+        section_match = re.search(section_pattern, content, re.DOTALL)
+
+        # Infer TOML value type: bool > int > float > string
+        def _toml_value(raw: str) -> str:
+            if raw.lower() in ("true", "false"):
+                return raw.lower()
+            try:
+                int(raw)
+                return raw
+            except ValueError:
+                pass
+            try:
+                float(raw)
+                return raw
+            except ValueError:
+                pass
+            return f'"{raw}"'
+
+        toml_val = _toml_value(value)
+
+        if section_match:
+            section_text = section_match.group(1)
+            field_pattern = rf'^(#?\s*{re.escape(field)}\s*=\s*).*$'
+            field_match = re.search(field_pattern, section_text, re.MULTILINE)
+            if field_match:
+                new_line = f'{field} = {toml_val}'
+                new_section = section_text[:field_match.start()] + new_line + section_text[field_match.end():]
+                content = content[:section_match.start()] + new_section + content[section_match.end():]
+            else:
+                # Add field to section
+                insert_pos = section_match.end()
+                content = content[:insert_pos] + f'\n{field} = {toml_val}' + content[insert_pos:]
+        else:
+            # Add new section
+            content += f'\n[{section}]\n{field} = {toml_val}\n'
+    else:
+        click.secho("Key must be in 'section.field' format (e.g. connection.domain).", fg="red", err=True)
+        return
+
+    path.write_text(content)
+
+    # config_set doesn't have @click.pass_obj, get formatter from context
+    ctx = click.get_current_context(silent=True)
+    obj = getattr(ctx, "obj", None) if ctx else None
+    output = getattr(obj, "output", None) if obj else None
+    if output:
+        output.success(f"Set {key} = {value}")
+    else:
+        click.echo(f"Set {key} = {value}")