feat(cli): Add exec command

Running a command in a sandbox requires a Python script that
creates a Process, drains its output, and handles the exit code.

Add `aviato exec` to run a command and stream its stdout/stderr
to the terminal. Supports --cwd and --timeout. Exits with the
command's return code.

Author: iiilisan

AGENTS.md

@@ -296,9 +296,12 @@ Commands:
 
 | Command | File | Description |
 |---------|------|-------------|
+| `aviato exec` | `cli/exec.py` | Execute a command in a sandbox (`--cwd`, `--timeout`) |
 | `aviato list` | `cli/list.py` | List sandboxes with optional filters (`--status`, `--tag`, `--runway-id`, `--tower-id`) |
 
 ```bash
+aviato exec <sandbox-id> echo hello             # Run a command
+aviato exec <sandbox-id> --cwd /app ls -la     # Run with working directory
 aviato list                                    # List all sandboxes
 aviato list --status running --tag my-project  # Filter by status and tag
 ```

DEVELOPMENT.md

@@ -150,6 +150,7 @@ aviato --help                              # Show available commands
 aviato --version                           # Show SDK version
 aviato list                                # List sandboxes
 aviato list --status running --tag dev     # Filter sandboxes
+aviato exec <sandbox-id> echo hello        # Run a command in a sandbox
 ```
 
 You can also invoke it as a Python module:

docs/guides/execution.md

@@ -301,6 +301,18 @@ for p in pending:
     print(p.result().stdout)
 ```
 
+## CLI
+
+The `aviato exec` command runs a one-off command in a sandbox from the terminal:
+
+```bash
+aviato exec <sandbox-id> echo hello
+aviato exec <sandbox-id> --cwd /app ls -la
+aviato exec <sandbox-id> --timeout 30 python script.py
+```
+
+Exits with the command's return code.
+
 ## Process Control
 
 The `Process` object provides methods for monitoring and control:

src/aviato/cli/__init__.py

@@ -21,6 +21,7 @@
         ) from e
     raise
 
+from aviato.cli.exec import exec_command
 from aviato.cli.list import list_sandboxes
 from aviato.exceptions import AviatoError
 
@@ -45,4 +46,5 @@ def cli() -> None:
     """Aviato sandbox CLI."""
 
 
+cli.add_command(exec_command, "exec")
 cli.add_command(list_sandboxes)

src/aviato/cli/exec.py

@@ -0,0 +1,79 @@
+# SPDX-FileCopyrightText: 2025 CoreWeave, Inc.
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-PackageName: aviato-client
+
+"""aviato exec — execute a command in a sandbox."""
+
+from __future__ import annotations
+
+import sys
+import threading
+
+import click
+
+from aviato import Sandbox
+
+
+@click.command(context_settings={"ignore_unknown_options": True})
+@click.argument("sandbox_id")
+@click.argument("command", nargs=-1, required=True, type=click.UNPROCESSED)
+@click.option(
+    "--cwd",
+    default=None,
+    help="Working directory for the command.",
+)
+@click.option(
+    "--timeout",
+    "timeout_seconds",
+    type=click.FloatRange(min=0),
+    default=None,
+    help="Timeout in seconds.",
+)
+def exec_command(
+    sandbox_id: str,
+    command: tuple[str, ...],
+    cwd: str | None,
+    timeout_seconds: float | None,
+) -> None:
+    """Execute a command in a sandbox.
+
+    SANDBOX_ID is the ID of the sandbox to run the command in.
+
+    Examples:
+
+        aviato exec <sandbox-id> echo hello
+
+        aviato exec <sandbox-id> sh -c "echo hello > /tmp/file"
+
+        aviato exec <sandbox-id> --cwd /app python script.py
+    """
+    sandbox = Sandbox.from_id(sandbox_id).result()
+
+    try:
+        process = sandbox.exec(
+            list(command),
+            cwd=cwd,
+            timeout_seconds=timeout_seconds,
+        )
+
+        def _drain_stderr() -> None:
+            try:
+                for chunk in process.stderr:
+                    click.echo(chunk, nl=False, err=True)
+            except BrokenPipeError:
+                pass
+
+        stderr_thread = threading.Thread(target=_drain_stderr)
+        stderr_thread.start()
+
+        for line in process.stdout:
+            click.echo(line, nl=False)
+
+        result = process.result()
+        stderr_thread.join()
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except BrokenPipeError:
+        pass  # Piped to head/etc — exit cleanly
+    else:
+        sys.exit(result.returncode)

tests/AGENTS.md

@@ -111,6 +111,7 @@ Tests skip gracefully with clear messages when no auth is configured. The `requi
 | `test_utilities.py` | aviato.result(), aviato.wait() utilities |
 | `test_cli_main.py` | `__main__` entry point, --help, --version, ImportError fallback |
 | `test_cli_list.py` | CLI list command, filters, empty state, API errors |
+| `test_cli_exec.py` | CLI exec command, stdout, stderr, returncode, cwd, timeout, not-found error |
 
 ### Integration Test Files (`tests/integration/aviato/`)
 

tests/unit/aviato/conftest.py

@@ -18,6 +18,9 @@
 
 T = TypeVar("T")
 
+# Event loops created by _make_reader, closed after each test.
+_test_loops: list[asyncio.AbstractEventLoop] = []
+
 # Environment variables that affect authentication behavior.
 # These are cleared before each test to ensure isolation.
 AUTH_ENV_VARS = (
@@ -42,6 +45,14 @@ def clean_auth_env(monkeypatch: pytest.MonkeyPatch) -> None:
         monkeypatch.delenv(var, raising=False)
 
 
+@pytest.fixture(autouse=True)
+def _cleanup_test_loops() -> None:
+    """Close event loops created by _make_reader after each test."""
+    yield  # type: ignore[misc]
+    while _test_loops:
+        _test_loops.pop().close()
+
+
 @pytest.fixture
 def mock_aviato_api_key(monkeypatch: pytest.MonkeyPatch) -> str:
     """Set a mock AVIATO_API_KEY for the test."""
@@ -119,8 +130,18 @@ def make_process(
     if stderr:
         stderr_queue.put_nowait(None)  # Sentinel
 
-    mock_lm = MagicMock()
-    stdout_reader = StreamReader(stdout_queue, mock_lm)
-    stderr_reader = StreamReader(stderr_queue, mock_lm)
+    # Each StreamReader gets its own mock _LoopManager with a dedicated event
+    # loop so that run_sync actually executes the asyncio.Queue.get() coroutine.
+    # Separate loops are needed because the CLI drains stdout and stderr on
+    # different threads; a shared loop would hit "already running" errors.
+    def _make_reader(queue: asyncio.Queue[str | None]) -> StreamReader[str]:
+        loop = asyncio.new_event_loop()
+        _test_loops.append(loop)
+        lm = MagicMock()
+        lm.run_sync.side_effect = loop.run_until_complete
+        return StreamReader(queue, lm)
+
+    stdout_reader = _make_reader(stdout_queue)
+    stderr_reader = _make_reader(stderr_queue)
 
     return Process(future, command or [], stdout_reader, stderr_reader)

tests/unit/aviato/test_cli_exec.py

@@ -0,0 +1,164 @@
+# SPDX-FileCopyrightText: 2025 CoreWeave, Inc.
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-PackageName: aviato-client
+
+"""Tests for aviato exec CLI command."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from click.testing import CliRunner
+
+from aviato.cli import cli
+from aviato.exceptions import SandboxNotFoundError
+from tests.unit.aviato.conftest import make_operation_ref, make_process
+
+
+def _patch_sandbox(process):
+    """Patch aviato.cli.exec.Sandbox.from_id to return a sandbox whose exec() returns *process*.
+
+    Returns a context manager that patches the Sandbox class.
+    """
+    mock_sandbox = MagicMock()
+    mock_sandbox.exec.return_value = process
+    return patch(
+        "aviato.cli.exec.Sandbox",
+        **{"from_id.return_value": make_operation_ref(mock_sandbox)},
+    )
+
+
+class TestExecCommand:
+    """Tests for the aviato exec CLI command."""
+
+    def test_exec_prints_stdout(self) -> None:
+        """aviato exec prints command stdout and exits with returncode."""
+        process = make_process(stdout="hello world\n", command=["echo", "hello"])
+
+        with _patch_sandbox(process) as mock_cls:
+            mock_sandbox = mock_cls.from_id.return_value.result()
+            runner = CliRunner()
+            result = runner.invoke(cli, ["exec", "test-sandbox-id", "echo", "hello"])
+
+        assert result.exit_code == 0
+        assert "hello world\n" in result.output
+        mock_sandbox.exec.assert_called_once_with(
+            ["echo", "hello"],
+            cwd=None,
+            timeout_seconds=None,
+        )
+
+    def test_exec_nonzero_returncode(self) -> None:
+        """aviato exec exits with the process returncode."""
+        process = make_process(returncode=1, command=["false"])
+
+        with _patch_sandbox(process):
+            runner = CliRunner()
+            result = runner.invoke(cli, ["exec", "test-sandbox-id", "false"])
+
+        assert result.exit_code == 1
+
+    def test_exec_with_cwd(self) -> None:
+        """aviato exec --cwd passes cwd to sandbox.exec."""
+        process = make_process(command=["ls"])
+
+        with _patch_sandbox(process) as mock_cls:
+            mock_sandbox = mock_cls.from_id.return_value.result()
+            runner = CliRunner()
+            result = runner.invoke(cli, ["exec", "test-sandbox-id", "--cwd", "/app", "ls"])
+
+        assert result.exit_code == 0
+        mock_sandbox.exec.assert_called_once_with(
+            ["ls"],
+            cwd="/app",
+            timeout_seconds=None,
+        )
+
+    def test_exec_with_timeout(self) -> None:
+        """aviato exec --timeout passes timeout_seconds to sandbox.exec."""
+        process = make_process(command=["sleep", "10"])
+
+        with _patch_sandbox(process) as mock_cls:
+            mock_sandbox = mock_cls.from_id.return_value.result()
+            runner = CliRunner()
+            result = runner.invoke(
+                cli, ["exec", "test-sandbox-id", "--timeout", "30", "sleep", "10"]
+            )
+
+        assert result.exit_code == 0
+        mock_sandbox.exec.assert_called_once_with(
+            ["sleep", "10"],
+            cwd=None,
+            timeout_seconds=30.0,
+        )
+
+    def test_exec_concurrent_stdout_stderr(self) -> None:
+        """aviato exec drains stdout and stderr concurrently on separate threads."""
+        process = make_process(
+            stdout="out line 1\nout line 2\n",
+            stderr="err line 1\nerr line 2\n",
+            returncode=0,
+            command=["some-cmd"],
+        )
+
+        with _patch_sandbox(process):
+            runner = CliRunner(mix_stderr=False)
+            result = runner.invoke(cli, ["exec", "test-sandbox-id", "some-cmd"])
+
+        assert result.exit_code == 0
+        assert "out line 1" in result.output
+        assert "out line 2" in result.output
+        assert "err line 1" in result.stderr
+        assert "err line 2" in result.stderr
+
+    def test_exec_prints_stderr(self) -> None:
+        """aviato exec prints command stderr to stderr."""
+        process = make_process(
+            stderr="error: something went wrong\n",
+            returncode=1,
+            command=["bad-cmd"],
+        )
+
+        with _patch_sandbox(process):
+            runner = CliRunner(mix_stderr=False)
+            result = runner.invoke(cli, ["exec", "test-sandbox-id", "bad-cmd"])
+
+        assert result.exit_code == 1
+        assert "error: something went wrong" in result.stderr
+
+    def test_exec_sandbox_not_found(self) -> None:
+        """aviato exec shows clean error for SandboxNotFoundError."""
+        mock_op_ref = MagicMock()
+        mock_op_ref.result.side_effect = SandboxNotFoundError("not found", sandbox_id="bad-id")
+
+        with patch("aviato.cli.exec.Sandbox") as mock_sandbox_cls:
+            mock_sandbox_cls.from_id.return_value = mock_op_ref
+
+            runner = CliRunner()
+            result = runner.invoke(cli, ["exec", "bad-id", "echo", "hello"])
+
+        assert result.exit_code == 1
+        assert "not found" in result.output
+
+    def test_exec_keyboard_interrupt(self) -> None:
+        """aviato exec exits 130 on KeyboardInterrupt."""
+        mock_process = MagicMock()
+        mock_process.stdout = iter([])
+        mock_process.result.side_effect = KeyboardInterrupt
+
+        with _patch_sandbox(mock_process):
+            runner = CliRunner()
+            result = runner.invoke(cli, ["exec", "test-sandbox-id", "sleep", "100"])
+
+        assert result.exit_code == 130
+
+    def test_exec_broken_pipe(self) -> None:
+        """aviato exec exits 0 on BrokenPipeError (piped to head/etc)."""
+        mock_process = MagicMock()
+        mock_process.stdout.__iter__ = MagicMock(side_effect=BrokenPipeError)
+
+        with _patch_sandbox(mock_process):
+            runner = CliRunner()
+            result = runner.invoke(cli, ["exec", "test-sandbox-id", "echo", "hello"])
+
+        assert result.exit_code == 0