opensandbox-cli 1.1.0__tar.gz → 1.1.2.dev20261020__tar.gz

{opensandbox_cli-1.1.0 → opensandbox_cli-1.1.2.dev20261020}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opensandbox-cli
-Version: 1.1.0
+Version: 1.1.2.dev20261020
 Summary: OpenSandbox CLI - Command-line interface for managing sandboxes
 Project-URL: Homepage, https://open-sandbox.ai
 Project-URL: Repository, https://github.com/opensandbox-group/OpenSandbox
@@ -224,10 +224,11 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: click<9.0,>=8.1.0
-Requires-Dist: opensandbox<2.0.0,>=1.1.0
+Requires-Dist: opensandbox<2.0.0,>=1.1.1
 Requires-Dist: pyyaml<7.0,>=6.0
 Requires-Dist: rich<14.0,>=13.0.0
 Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: tomlkit<1.0,>=0.13.0
 Description-Content-Type: text/markdown
 
 # OpenSandbox CLI
@@ -235,6 +236,7 @@ Description-Content-Type: text/markdown
 `osb` is the command-line interface for OpenSandbox. It is built for the common day-to-day flows:
 
 - create and manage sandboxes
+- build golden-image templates and create sandboxes from templates or snapshots
 - run commands inside a sandbox
 - read and modify sandbox files
 - inspect runtime egress policy
@@ -387,6 +389,84 @@ Create with Credential Vault proxy enabled:
 osb sandbox create --image python:3.12 --network-policy-file network-policy.json --credential-proxy -o json
 ```
 
+Create from a template (golden image):
+
+```bash
+osb sandbox create --template <template-id> --timeout 30m -o json
+```
+
+Template mode fixes the workload shape on the server: `--image`, `--env`, `--resource`, `--entrypoint`, `--volumes-file`, and `--credential-proxy` cannot be combined with `--template`. Only `--timeout` (required), `--metadata`, `--extension`, and `--network-policy-file` may accompany it. Only templates in the `Succeeded` phase can be used. See [Manage templates](#manage-templates).
+
+Create from a snapshot:
+
+```bash
+osb sandbox create --snapshot-id <snapshot-id> --timeout 30m -o json
+```
+
+`--image`, `--template`, and `--snapshot-id` are mutually exclusive.
+
+Create from a request file (`-f`, like `kubectl apply -f`):
+
+```bash
+osb sandbox create -f sandbox-request.json -o json
+```
+
+`sandbox-request.json` uses the public `CreateSandboxRequest` JSON format (camelCase keys):
+
+```json
+{
+  "image": "python:3.12",
+  "timeout": 1800,
+  "resourceLimits": { "cpu": "1", "memory": "2Gi" },
+  "entrypoint": ["python", "-m", "http.server"],
+  "networkPolicy": {
+    "defaultAction": "deny",
+    "egress": [{ "action": "allow", "target": "pypi.org" }]
+  }
+}
+```
+
+- Exactly one of `image` (string or `{ "uri": ..., "auth": { "username": ..., "password": ... } }`), `templateId`, or `snapshotId` is required; `timeout` is integer seconds, or `null` for manual cleanup.
+- Supported fields: `image`, `templateId`, `snapshotId`, `platform`, `timeout`, `resourceLimits`, `resourceRequests`, `env`, `metadata`, `extensions`, `entrypoint`, `networkPolicy`, `credentialProxy`, `secureAccess`, `volumes`, `lifecycle`.
+- `-f` cannot be combined with request-building flags; `--skip-health-check`, `--ready-timeout`, and `-o` still apply. In template mode the file may only set `timeout`, `metadata`, `extensions`, and `networkPolicy` alongside `templateId` (a finite `timeout` is required).
+
+### Manage templates
+
+Templates are golden-image builds; the build runs asynchronously, so poll `template get` until the status phase is `Succeeded`. Template management requires a Kubernetes-backed runtime.
+
+```bash
+osb template create --image python:3.12 --publish s3://bucket/publish -o json
+osb template get <template-id> -o json
+osb template list -o json
+osb template delete <template-id> -o json
+```
+
+`template create` also accepts `--resource cpu=1 memory=512Mi disk=2Gi`, `--entrypoint` (repeat per argv item), `--env KEY=VALUE`, `--metadata KEY=VALUE`, `--format native|overlaybd`, `--readiness-probe`, and `--warmup-seconds`. Or pass a request file in the public `CreateTemplateRequest` JSON format:
+
+```bash
+osb template create -f template-request.json -o json
+```
+
+```json
+{
+  "image": "python:3.12",
+  "publish": "s3://bucket/publish",
+  "resourceLimits": { "cpu": "1", "memory": "512Mi" },
+  "readiness": { "probe": "tcp://127.0.0.1:44772", "warmupSeconds": 60 }
+}
+```
+
+### Manage snapshots
+
+Snapshots capture a sandbox's state and can back new sandboxes.
+
+```bash
+osb snapshot create <sandbox-id> --name golden -o json
+osb snapshot get <snapshot-id> -o json
+osb snapshot list --sandbox-id <sandbox-id> -o json
+osb snapshot delete <snapshot-id> -o json
+```
+
 ### List and inspect sandboxes
 
 ```bash
@@ -400,9 +480,7 @@ osb sandbox metrics <sandbox-id> --watch -o raw
 
 ### Pause a sandbox
 
-Pause is asynchronous. `Pause request accepted` confirms that the server accepted
-the request, not that the sandbox has reached the `Paused` state. Poll the sandbox
-until the transition finishes:
+Pause is asynchronous. `Pause request accepted` confirms that the server accepted the request, not that the sandbox has reached the `Paused` state. Poll the sandbox until the transition finishes:
 
 ```bash
 osb sandbox pause <sandbox-id>
@@ -431,12 +509,9 @@ osb command status <sandbox-id> <execution-id> -o json
 osb command logs <sandbox-id> <execution-id> -o json
 ```
 
-By default the payload after `--` is joined into one shell command string, so
-pipelines, redirection, and `$VAR` expansion work as in a terminal. Add `--argv`
-to pass the arguments to the executable as a literal argv list (no shell) when
-values such as `$HOME`, quotes, embedded spaces, or empty strings must reach the
-process unchanged. `--argv` needs a sandbox image whose execd accepts argv
-requests:
+Background start errors or a stream ending before startup confirmation make the CLI exit non-zero without success metadata. After a successful start, use `command status` and `command logs` to check the process's eventual result.
+
+By default the payload after `--` is joined into one shell command string, so pipelines, redirection, and `$VAR` expansion work as in a terminal. Add `--argv` to pass the arguments to the executable as a literal argv list (no shell) when values such as `$HOME`, quotes, embedded spaces, or empty strings must reach the process unchanged. `--argv` needs a sandbox image whose execd accepts argv requests:
 
 ```bash
 osb command run <sandbox-id> -o raw --argv -- python3 -c "import sys; print(sys.argv[1:])" "a b" '$HOME' "x'y" ""
@@ -463,10 +538,7 @@ osb file replace <sandbox-id> /workspace/app.py --old old --new new -o json
 osb file chmod <sandbox-id> /workspace/script.sh --mode 755 -o json
 ```
 
-Downloads replace regular files only on success; a failed or interrupted
-download preserves any existing regular file. Existing devices and named pipes
-receive data directly. Stdout aliases (such as `/dev/stdout`) stream only the file
-bytes, without a success message. See the [CLI guide](../docs/cli/index.md#work-with-files).
+Downloads replace regular files only on success; a failed or interrupted download preserves any existing regular file. Existing devices and named pipes receive data directly. Stdout aliases (such as `/dev/stdout`) stream only the file bytes, without a success message. See the [CLI guide](../docs/cli/index.md#work-with-files).
 
 ### Manage runtime egress policy
 
@@ -490,9 +562,7 @@ osb command run <sandbox-id> -o raw -- curl -I https://pypi.org
 
 ### Manage Credential Vault
 
-Credential Vault operations call the sandbox egress sidecar through the Python SDK.
-Create the sandbox with `--credential-proxy` and an explicit network policy before
-writing vault state.
+Credential Vault operations call the sandbox egress sidecar through the Python SDK. Create the sandbox with `--credential-proxy` and an explicit network policy before writing vault state.
 
 ```bash
 osb credential-vault create <sandbox-id> --file vault.yaml -o json
@@ -503,14 +573,14 @@ osb credential-vault binding list <sandbox-id> -o json
 osb credential-vault delete <sandbox-id> -o json
 ```
 
-Use `--file -` to read a JSON/YAML payload from stdin. Do not pass plaintext
-credential values as command-line flags; keep them in the payload stream or file.
+Use `--file -` to read a JSON/YAML payload from stdin. Do not pass plaintext credential values as command-line flags; keep them in the payload stream or file.
 
 ### Collect diagnostics
 
-Use the stable diagnostics commands for API-backed log and event descriptors.
+Use context to identify the runtime backend, then collect log and event descriptors.
 
 ```bash
+osb diagnostics context <sandbox-id> -o json
 osb diagnostics events <sandbox-id> --scope runtime -o raw
 osb diagnostics events <sandbox-id> --scope all -o raw
 osb diagnostics logs <sandbox-id> --scope container -o raw
@@ -519,7 +589,9 @@ osb diagnostics events <sandbox-id> --scope runtime -o json
 osb diagnostics logs <sandbox-id> --scope container -o yaml
 ```
 
-`--scope` is required for stable diagnostics. The built-in server supports
+`context` returns backend routing information without connecting to execd and
+supports table, JSON, and YAML output. `--scope` is required for logs/events.
+The built-in server supports
 `container` and `all` for logs, and `runtime` and `all` for events. It returns
 `DIAGNOSTICS_SCOPE_UNSUPPORTED` for unavailable scopes, including lifecycle events.
 Best-effort scopes may include a `warnings` field when the backend can only
@@ -529,8 +601,7 @@ temporary URL. Structured CLI output follows the SDK/Python field style, for
 example `content_url`, `content_length`, and `expires_at`. Older server builds
 may still return `DIAGNOSTICS_NOT_IMPLEMENTED` for scoped diagnostics.
 
-Legacy DevOps diagnostics remain experimental. Prefer `osb diagnostics logs/events`
-for stable API-backed log and event collection.
+Legacy DevOps diagnostics remain experimental. Prefer `osb diagnostics logs/events` for stable API-backed log and event collection.
 
 ```bash
 osb devops inspect <sandbox-id> -o raw
@@ -561,6 +632,8 @@ Not every command supports every format. Use `--help` on the specific command wh
 The main command groups are:
 
 - `osb sandbox`: lifecycle management
+- `osb template`: golden-image template builds
+- `osb snapshot`: snapshot management
 - `osb command`: command execution and persistent sessions
 - `osb file`: file and directory operations
 - `osb egress`: runtime egress policy
@@ -573,6 +646,8 @@ Explore them directly:
 
 ```bash
 osb sandbox --help
+osb template --help
+osb snapshot --help
 osb command --help
 osb file --help
 osb skills --help
@@ -594,12 +669,12 @@ Supported targets:
 
 | Target | Install location |
 | --- | --- |
-| `claude` | `./.claude/skills/` or `~/.claude/skills/` |
+| `claude` | `./.claude/skills/<name>/SKILL.md` or `~/.claude/skills/<name>/SKILL.md` |
 | `cursor` | `./.cursor/rules/` or `~/.cursor/rules/` |
 | `codex` | `./.codex/skills/<name>/SKILL.md` or `~/.codex/skills/<name>/SKILL.md` |
-| `copilot` | `./.github/copilot-instructions.md` or `~/.github/copilot-instructions.md` |
+| `copilot` | `./.github/copilot-instructions.md` or `~/.copilot/copilot-instructions.md` |
 | `windsurf` | `./.windsurfrules` or `~/.windsurfrules` |
-| `cline` | `./.clinerules` or `~/.clinerules` |
+| `cline` | `./.clinerules` or `~/.cline/rules/opensandbox-<name>.md` |
 | `opencode` | `./.agents/skills/<name>/SKILL.md` or `~/.agents/skills/<name>/SKILL.md` |
 
 Common flows:

{opensandbox_cli-1.1.0 → opensandbox_cli-1.1.2.dev20261020}/README.md

@@ -3,6 +3,7 @@
 `osb` is the command-line interface for OpenSandbox. It is built for the common day-to-day flows:
 
 - create and manage sandboxes
+- build golden-image templates and create sandboxes from templates or snapshots
 - run commands inside a sandbox
 - read and modify sandbox files
 - inspect runtime egress policy
@@ -155,6 +156,84 @@ Create with Credential Vault proxy enabled:
 osb sandbox create --image python:3.12 --network-policy-file network-policy.json --credential-proxy -o json
 ```
 
+Create from a template (golden image):
+
+```bash
+osb sandbox create --template <template-id> --timeout 30m -o json
+```
+
+Template mode fixes the workload shape on the server: `--image`, `--env`, `--resource`, `--entrypoint`, `--volumes-file`, and `--credential-proxy` cannot be combined with `--template`. Only `--timeout` (required), `--metadata`, `--extension`, and `--network-policy-file` may accompany it. Only templates in the `Succeeded` phase can be used. See [Manage templates](#manage-templates).
+
+Create from a snapshot:
+
+```bash
+osb sandbox create --snapshot-id <snapshot-id> --timeout 30m -o json
+```
+
+`--image`, `--template`, and `--snapshot-id` are mutually exclusive.
+
+Create from a request file (`-f`, like `kubectl apply -f`):
+
+```bash
+osb sandbox create -f sandbox-request.json -o json
+```
+
+`sandbox-request.json` uses the public `CreateSandboxRequest` JSON format (camelCase keys):
+
+```json
+{
+  "image": "python:3.12",
+  "timeout": 1800,
+  "resourceLimits": { "cpu": "1", "memory": "2Gi" },
+  "entrypoint": ["python", "-m", "http.server"],
+  "networkPolicy": {
+    "defaultAction": "deny",
+    "egress": [{ "action": "allow", "target": "pypi.org" }]
+  }
+}
+```
+
+- Exactly one of `image` (string or `{ "uri": ..., "auth": { "username": ..., "password": ... } }`), `templateId`, or `snapshotId` is required; `timeout` is integer seconds, or `null` for manual cleanup.
+- Supported fields: `image`, `templateId`, `snapshotId`, `platform`, `timeout`, `resourceLimits`, `resourceRequests`, `env`, `metadata`, `extensions`, `entrypoint`, `networkPolicy`, `credentialProxy`, `secureAccess`, `volumes`, `lifecycle`.
+- `-f` cannot be combined with request-building flags; `--skip-health-check`, `--ready-timeout`, and `-o` still apply. In template mode the file may only set `timeout`, `metadata`, `extensions`, and `networkPolicy` alongside `templateId` (a finite `timeout` is required).
+
+### Manage templates
+
+Templates are golden-image builds; the build runs asynchronously, so poll `template get` until the status phase is `Succeeded`. Template management requires a Kubernetes-backed runtime.
+
+```bash
+osb template create --image python:3.12 --publish s3://bucket/publish -o json
+osb template get <template-id> -o json
+osb template list -o json
+osb template delete <template-id> -o json
+```
+
+`template create` also accepts `--resource cpu=1 memory=512Mi disk=2Gi`, `--entrypoint` (repeat per argv item), `--env KEY=VALUE`, `--metadata KEY=VALUE`, `--format native|overlaybd`, `--readiness-probe`, and `--warmup-seconds`. Or pass a request file in the public `CreateTemplateRequest` JSON format:
+
+```bash
+osb template create -f template-request.json -o json
+```
+
+```json
+{
+  "image": "python:3.12",
+  "publish": "s3://bucket/publish",
+  "resourceLimits": { "cpu": "1", "memory": "512Mi" },
+  "readiness": { "probe": "tcp://127.0.0.1:44772", "warmupSeconds": 60 }
+}
+```
+
+### Manage snapshots
+
+Snapshots capture a sandbox's state and can back new sandboxes.
+
+```bash
+osb snapshot create <sandbox-id> --name golden -o json
+osb snapshot get <snapshot-id> -o json
+osb snapshot list --sandbox-id <sandbox-id> -o json
+osb snapshot delete <snapshot-id> -o json
+```
+
 ### List and inspect sandboxes
 
 ```bash
@@ -168,9 +247,7 @@ osb sandbox metrics <sandbox-id> --watch -o raw
 
 ### Pause a sandbox
 
-Pause is asynchronous. `Pause request accepted` confirms that the server accepted
-the request, not that the sandbox has reached the `Paused` state. Poll the sandbox
-until the transition finishes:
+Pause is asynchronous. `Pause request accepted` confirms that the server accepted the request, not that the sandbox has reached the `Paused` state. Poll the sandbox until the transition finishes:
 
 ```bash
 osb sandbox pause <sandbox-id>
@@ -199,12 +276,9 @@ osb command status <sandbox-id> <execution-id> -o json
 osb command logs <sandbox-id> <execution-id> -o json
 ```
 
-By default the payload after `--` is joined into one shell command string, so
-pipelines, redirection, and `$VAR` expansion work as in a terminal. Add `--argv`
-to pass the arguments to the executable as a literal argv list (no shell) when
-values such as `$HOME`, quotes, embedded spaces, or empty strings must reach the
-process unchanged. `--argv` needs a sandbox image whose execd accepts argv
-requests:
+Background start errors or a stream ending before startup confirmation make the CLI exit non-zero without success metadata. After a successful start, use `command status` and `command logs` to check the process's eventual result.
+
+By default the payload after `--` is joined into one shell command string, so pipelines, redirection, and `$VAR` expansion work as in a terminal. Add `--argv` to pass the arguments to the executable as a literal argv list (no shell) when values such as `$HOME`, quotes, embedded spaces, or empty strings must reach the process unchanged. `--argv` needs a sandbox image whose execd accepts argv requests:
 
 ```bash
 osb command run <sandbox-id> -o raw --argv -- python3 -c "import sys; print(sys.argv[1:])" "a b" '$HOME' "x'y" ""
@@ -231,10 +305,7 @@ osb file replace <sandbox-id> /workspace/app.py --old old --new new -o json
 osb file chmod <sandbox-id> /workspace/script.sh --mode 755 -o json
 ```
 
-Downloads replace regular files only on success; a failed or interrupted
-download preserves any existing regular file. Existing devices and named pipes
-receive data directly. Stdout aliases (such as `/dev/stdout`) stream only the file
-bytes, without a success message. See the [CLI guide](../docs/cli/index.md#work-with-files).
+Downloads replace regular files only on success; a failed or interrupted download preserves any existing regular file. Existing devices and named pipes receive data directly. Stdout aliases (such as `/dev/stdout`) stream only the file bytes, without a success message. See the [CLI guide](../docs/cli/index.md#work-with-files).
 
 ### Manage runtime egress policy
 
@@ -258,9 +329,7 @@ osb command run <sandbox-id> -o raw -- curl -I https://pypi.org
 
 ### Manage Credential Vault
 
-Credential Vault operations call the sandbox egress sidecar through the Python SDK.
-Create the sandbox with `--credential-proxy` and an explicit network policy before
-writing vault state.
+Credential Vault operations call the sandbox egress sidecar through the Python SDK. Create the sandbox with `--credential-proxy` and an explicit network policy before writing vault state.
 
 ```bash
 osb credential-vault create <sandbox-id> --file vault.yaml -o json
@@ -271,14 +340,14 @@ osb credential-vault binding list <sandbox-id> -o json
 osb credential-vault delete <sandbox-id> -o json
 ```
 
-Use `--file -` to read a JSON/YAML payload from stdin. Do not pass plaintext
-credential values as command-line flags; keep them in the payload stream or file.
+Use `--file -` to read a JSON/YAML payload from stdin. Do not pass plaintext credential values as command-line flags; keep them in the payload stream or file.
 
 ### Collect diagnostics
 
-Use the stable diagnostics commands for API-backed log and event descriptors.
+Use context to identify the runtime backend, then collect log and event descriptors.
 
 ```bash
+osb diagnostics context <sandbox-id> -o json
 osb diagnostics events <sandbox-id> --scope runtime -o raw
 osb diagnostics events <sandbox-id> --scope all -o raw
 osb diagnostics logs <sandbox-id> --scope container -o raw
@@ -287,7 +356,9 @@ osb diagnostics events <sandbox-id> --scope runtime -o json
 osb diagnostics logs <sandbox-id> --scope container -o yaml
 ```
 
-`--scope` is required for stable diagnostics. The built-in server supports
+`context` returns backend routing information without connecting to execd and
+supports table, JSON, and YAML output. `--scope` is required for logs/events.
+The built-in server supports
 `container` and `all` for logs, and `runtime` and `all` for events. It returns
 `DIAGNOSTICS_SCOPE_UNSUPPORTED` for unavailable scopes, including lifecycle events.
 Best-effort scopes may include a `warnings` field when the backend can only
@@ -297,8 +368,7 @@ temporary URL. Structured CLI output follows the SDK/Python field style, for
 example `content_url`, `content_length`, and `expires_at`. Older server builds
 may still return `DIAGNOSTICS_NOT_IMPLEMENTED` for scoped diagnostics.
 
-Legacy DevOps diagnostics remain experimental. Prefer `osb diagnostics logs/events`
-for stable API-backed log and event collection.
+Legacy DevOps diagnostics remain experimental. Prefer `osb diagnostics logs/events` for stable API-backed log and event collection.
 
 ```bash
 osb devops inspect <sandbox-id> -o raw
@@ -329,6 +399,8 @@ Not every command supports every format. Use `--help` on the specific command wh
 The main command groups are:
 
 - `osb sandbox`: lifecycle management
+- `osb template`: golden-image template builds
+- `osb snapshot`: snapshot management
 - `osb command`: command execution and persistent sessions
 - `osb file`: file and directory operations
 - `osb egress`: runtime egress policy
@@ -341,6 +413,8 @@ Explore them directly:
 
 ```bash
 osb sandbox --help
+osb template --help
+osb snapshot --help
 osb command --help
 osb file --help
 osb skills --help
@@ -362,12 +436,12 @@ Supported targets:
 
 | Target | Install location |
 | --- | --- |
-| `claude` | `./.claude/skills/` or `~/.claude/skills/` |
+| `claude` | `./.claude/skills/<name>/SKILL.md` or `~/.claude/skills/<name>/SKILL.md` |
 | `cursor` | `./.cursor/rules/` or `~/.cursor/rules/` |
 | `codex` | `./.codex/skills/<name>/SKILL.md` or `~/.codex/skills/<name>/SKILL.md` |
-| `copilot` | `./.github/copilot-instructions.md` or `~/.github/copilot-instructions.md` |
+| `copilot` | `./.github/copilot-instructions.md` or `~/.copilot/copilot-instructions.md` |
 | `windsurf` | `./.windsurfrules` or `~/.windsurfrules` |
-| `cline` | `./.clinerules` or `~/.clinerules` |
+| `cline` | `./.clinerules` or `~/.cline/rules/opensandbox-<name>.md` |
 | `opencode` | `./.agents/skills/<name>/SKILL.md` or `~/.agents/skills/<name>/SKILL.md` |
 
 Common flows:

{opensandbox_cli-1.1.0 → opensandbox_cli-1.1.2.dev20261020}/pyproject.toml

@@ -44,10 +44,11 @@ classifiers = [
 dependencies = [
     # `command run --argv` passes a list to commands.run; the SDK accepts a
     # list there from 0.1.17. Release the CLI only after that SDK is published.
-    "opensandbox>=1.1.0,<2.0.0",
+    "opensandbox>=1.1.1,<2.0.0",
     "click>=8.1.0,<9.0",
     "rich>=13.0.0,<14.0",
     "pyyaml>=6.0,<7.0",
+    "tomlkit>=0.13.0,<1.0",
     "tomli>=2.0.0; python_version < '3.11'",
 ]
 

{opensandbox_cli-1.1.0 → opensandbox_cli-1.1.2.dev20261020}/src/opensandbox_cli/client.py

@@ -90,15 +90,10 @@ class ClientContext:
             self._manager = SandboxManagerSync.create(self.connection_config)
         return self._manager
 
-    def resolve_sandbox_id(self, sandbox_id: str) -> str:
-        """Return the sandbox ID exactly as provided by the user."""
-        return sandbox_id
-
     def connect_sandbox(
         self, sandbox_id: str, *, skip_health_check: bool = True
     ) -> SandboxSync:
         """Connect to an existing sandbox by ID."""
-        sandbox_id = self.resolve_sandbox_id(sandbox_id)
         return SandboxSync.connect(
             sandbox_id,
             connection_config=self.connection_config,

{opensandbox_cli-1.1.0 → opensandbox_cli-1.1.2.dev20261020}/src/opensandbox_cli/commands/command.py

@@ -18,10 +18,11 @@ from __future__ import annotations
 
 import shlex
 import sys
+from collections.abc import Callable
 from datetime import timedelta
 
 import click
-from opensandbox.models.execd import OutputMessage, RunCommandOpts
+from opensandbox.models.execd import Execution, OutputMessage, RunCommandOpts
 from opensandbox.models.execd_sync import ExecutionHandlersSync
 
 from opensandbox_cli.client import ClientContext
@@ -41,7 +42,29 @@ def command_group(ctx: click.Context) -> None:
         click.echo(ctx.get_help())
 
 
-# ---- run ------------------------------------------------------------------
+def _stream_handlers() -> tuple[ExecutionHandlersSync, Callable[[], None]]:
+    """Create stdout/stderr streaming handlers and a trailing-newline flusher."""
+    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()
+
+    def flush_newline() -> None:
+        if last_text and not last_text.endswith("\n"):
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+
+    return ExecutionHandlersSync(on_stdout=on_stdout, on_stderr=on_stderr), flush_newline
+
 
 def _run_command(
     obj: ClientContext,
@@ -55,15 +78,10 @@ def _run_command(
 ) -> None:
     """Shared implementation for ``command run``.
 
-    Mode contract:
-    - foreground (default): stream output directly, allow only ``-o raw``
-    - background (``--background``): return a tracked execution object, allow structured output
-
-    Payload contract:
-    - default: join the arguments into one shell command string (works against
-      every deployed execd)
-    - ``--argv``: send the arguments as a literal argv list, no shell; needs an
-      execd that accepts the ``argv`` request field
+    Foreground mode streams output and allows only ``-o raw``; background mode
+    returns a tracked execution object and allows structured output. The payload
+    is joined into one shell command string unless ``argv`` sends it as a
+    literal argv list (needs an argv-capable execd).
     """
     allowed = ("table", "json", "yaml") if background else ("raw",)
     fallback = "table" if background else "raw"
@@ -84,6 +102,7 @@ def _run_command(
 
         if background:
             execution = sandbox.commands.run(payload, opts=opts)
+            _handle_execution_error(obj, execution, background=True)
             obj.output.success_panel(
                 {
                     "execution_id": execution.id,
@@ -94,42 +113,33 @@ def _run_command(
             )
             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)
+        handlers, flush_newline = _stream_handlers()
         execution = sandbox.commands.run(payload, 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()
-
+        flush_newline()
         _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."""
+def _handle_execution_error(
+    obj: ClientContext, execution: Execution, *, background: bool = False
+) -> None:
+    """Exit non-zero on execution errors or missing completion/startup confirmation."""
     if execution.error:
         obj.output.error_panel(
             f"{execution.error.name}: {execution.error.value}",
             title="Execution Error",
         )
         sys.exit(1)
+    if execution.complete is None:
+        confirmation = (
+            "background command startup was confirmed" if background else "the command finished"
+        )
+        obj.output.error_panel(
+            f"The output stream ended before {confirmation}, so its result is unknown.",
+            title="Execution Incomplete",
+        )
+        sys.exit(1)
 
 
 @command_group.command(
@@ -185,8 +195,6 @@ def command_run(
     )
 
 
-# ---- status ---------------------------------------------------------------
-
 @command_group.command("status")
 @click.argument("sandbox_id")
 @click.argument("execution_id")
@@ -209,8 +217,6 @@ def command_status(
         sandbox.close()
 
 
-# ---- logs -----------------------------------------------------------------
-
 @command_group.command("logs")
 @click.argument("sandbox_id")
 @click.argument("execution_id")
@@ -242,8 +248,6 @@ def command_logs(
         sandbox.close()
 
 
-# ---- interrupt ------------------------------------------------------------
-
 @command_group.command("interrupt")
 @click.argument("sandbox_id")
 @click.argument("execution_id")
@@ -330,21 +334,7 @@ def session_run(
     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)
+        handlers, flush_newline = _stream_handlers()
         execution = sandbox.commands.run_in_session(
             session_id,
             cmd_str,
@@ -352,11 +342,7 @@ def session_run(
             timeout=timeout,
             handlers=handlers,
         )
-
-        if last_text and not last_text.endswith("\n"):
-            sys.stdout.write("\n")
-            sys.stdout.flush()
-
+        flush_newline()
         _handle_execution_error(obj, execution)
     finally:
         sandbox.close()