orca-cli-sdk 0.1.0__py3-none-any.whl

orca_cli_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.5
+Name: orca-cli-sdk
+Version: 0.1.0
+Summary: Typed Python SDK (sync and asyncio) for the Orca CLI
+Project-URL: Homepage, https://github.com/batprem/orca-sdk-python
+Project-URL: Repository, https://github.com/batprem/orca-sdk-python
+Project-URL: Issues, https://github.com/batprem/orca-sdk-python/issues
+Author: Prem Chotepanit
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,cli,orca,sdk,worktrees
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# orca-cli-sdk
+
+A typed Python SDK for the Orca CLI, with both sync and `asyncio` clients.
+
+- **Covers every command.** All 287 commands in Orca CLI 1.4.237 are wrapped, generated from the CLI's own schema (`orca agent-context --json`).
+- **Mirrors the CLI.** `orca worktree list --limit 5` becomes `client.worktree.list(limit=5)`.
+- **Uses the JSON envelope.** Commands run with `--json`, the SDK parses the `{ok, result, error}` envelope, and you get `result` back.
+- **Typed exceptions.** Covers a missing binary, CLI errors (with `code`/`message`/`data`), timeouts and bad JSON.
+- **No runtime dependencies.** Needs Python 3.10+.
+
+```bash
+uv add orca-cli-sdk        # or: pip install orca-cli-sdk
+# import name: orca_sdk
+```
+
+## Quick start
+
+```python
+from orca_sdk import Orca
+
+orca = Orca()
+
+status = orca.status()
+print(status["runtime"]["state"])            # "ready"
+
+for project in orca.project.list()["projects"]:
+    print(project["id"], project["displayName"])
+
+repos = orca.repo.list()
+worktrees = orca.worktree.list(repo="name:orca", limit=10)
+```
+
+### Async
+
+```python
+import asyncio
+from orca_sdk import AsyncOrca
+
+async def main() -> None:
+    async with AsyncOrca() as orca:
+        status, projects = await asyncio.gather(orca.status(), orca.project.list())
+        print(status["graph"]["state"], len(projects["projects"]))
+
+asyncio.run(main())
+```
+
+`AsyncOrca` has the same methods and signatures as `Orca`, but each command must be awaited. It runs the CLI with `asyncio.create_subprocess_exec`. If a command times out or is cancelled, the SDK kills the CLI process.
+
+## Finding the `orca` binary
+
+The binary is located the first time it is needed, checking in this order:
+
+1. `Orca(binary="/path/to/orca")`
+2. the `ORCA_BIN` environment variable
+3. `orca` on `PATH`
+4. `/home/box/Applications/bin/orca`
+
+If none of these is an executable file, the SDK raises `OrcaBinaryNotFoundError`. `orca_sdk.find_binary()` runs the same lookup.
+
+## Mapping CLI commands to methods
+
+| CLI | Python |
+| --- | --- |
+| `orca status` | `orca.status()` |
+| `orca worktree create --name t --agent codex --prompt "hi"` | `orca.worktree.create(name="t", agent="codex", prompt="hi")` |
+| `orca worktree rm --worktree active --force` | `orca.worktree.rm(worktree="active", force=True)` |
+| `orca terminal wait --terminal t1 --for exit --timeout-ms 60000` | `orca.terminal.wait(terminal="t1", for_="exit", timeout_ms=60000)` |
+| `orca reference add <url> <url> --worktree active` | `orca.reference.add(["https://…", "https://…"], worktree="active")` |
+| `orca agent hooks status` | `orca.agent.hooks.status()` |
+| `orca linear team list` | `orca.linear.team.list()` |
+| `orca terminal-daemon status` | `orca.terminal_daemon.status()` |
+| `orca serve service status` | `orca.serve.service.status()` (`orca.serve(...)` runs `serve` itself) |
+
+Naming rules:
+
+- Hyphens become underscores (`setup-clone` → `setup_clone`).
+- Python keywords get a trailing `_` (`--for` → `for_`, `orca is` → `orca.is_`).
+- Positional arguments are positional parameters.
+- Flags are keyword-only parameters.
+- Flags the usage string marks as required are required keywords.
+
+How values become arguments:
+
+- Boolean flags take `True`.
+- Repeatable flags (`--reference`, `--label`, …) take a list.
+- `None`/`False` leaves the flag out.
+
+Every method's docstring holds the CLI usage, notes and examples, so `help(orca.worktree.create)` shows what `orca worktree create --help` would.
+
+The CLI's groups are all available, including:
+
+- `project`, `repo`, `worktree`, `agent`, `terminal`
+- `automations`, `host`, `environment`, `skills`, `reference`, `account`
+- `orchestration`, `artifacts`, `file`, `tab`, `linear`, `jira`, `computer`, `emulator`, `storage`, `serve`
+
+Top-level commands are methods on the client: `status`, `search`, `open`, `agent_context`, `snapshot`, `goto`, `click`, and the rest.
+
+## Options: timeouts, env vars, remote runtimes
+
+```python
+orca = Orca(
+    timeout=120,                 # seconds per command (default 60, None = no limit)
+    env={"NO_COLOR": "1"},       # extra env vars for the subprocess
+    inherit_env=True,            # start from os.environ (default)
+    cwd="/path/to/worktree",     # Orca infers the current worktree from cwd
+)
+
+# Route every command to a saved remote Orca server (adds --environment <name>)
+remote = Orca(environment="build-box")
+
+# ...or to one reached by a pairing code (passed as $ORCA_PAIRING_CODE so it
+# does not appear in the process list)
+paired = Orca(pairing_code="orca://pair?...")
+
+# Derive a client with different options; the original is unchanged
+slow = orca.with_options(timeout=600)
+slow.terminal.wait(terminal="term_123", for_="exit", timeout_ms=600_000)
+local = remote.with_options(environment=None)
+```
+
+Some commands only run on the local host and reject routing: `account list`, `host list` and `environment list`. The `environment …` management commands also take `--environment` as a *selector* (which server to act on), not as routing. Calling any of these on a client that has `environment` or `pairing_code` set raises `OrcaUsageError` before running anything. Use `with_options(environment=None, pairing_code=None)` to call them.
+
+```python
+orca.environment.show(environment="build-box")   # selector, not routing
+```
+
+## Errors
+
+```python
+from orca_sdk import (
+    OrcaError,                # base class
+    OrcaBinaryNotFoundError,  # no orca executable
+    OrcaCommandError,         # the CLI reported ok=false or exited non-zero
+    OrcaTimeoutError,         # killed after the timeout
+    OrcaJSONDecodeError,      # --json output was not valid JSON
+    OrcaUsageError,           # e.g. routing a host-local command
+)
+
+try:
+    orca.repo.show(repo="name:missing")
+except OrcaCommandError as err:
+    print(err.code)        # "repo_not_found"
+    print(err.message)
+    print(err.data)        # error.data from the envelope, if any
+    print(err.next_steps)  # the CLI's suggested next steps
+    print(err.returncode, err.argv, err.stderr)
+```
+
+If the CLI fails without printing a JSON envelope, you still get an `OrcaCommandError`, with `code == "process_error"` and the message taken from stderr.
+
+## Raw access
+
+`run_command` runs any argument list. It returns the full `OrcaResponse`: `ok`, `result`, `error`, `id`, `meta`, `stdout`, `stderr`, `returncode` and `argv`.
+
+```python
+resp = orca.run_command(["worktree", "ps", "--limit", "3"])
+print(resp.meta["runtimeId"], resp.result)
+
+resp = orca.run_command(["repo", "show", "--repo", "x"], check=False)  # don't raise
+if not resp.ok:
+    print(resp.error["code"])
+
+orca.run_command(["claude-teams", "--help"], json=False)  # plain-text commands
+```
+
+To feed stdin, pass `stdin=` to `run_command` or to the generated methods that read stdin (for example `orca.speech.openai_key.set(stdin=key)` or `--text-stdin` commands).
+
+The bundled schema is available at runtime:
+
+```python
+from orca_sdk.schema import load_schema, get_command, command_names
+get_command("worktree create")["notes"]
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest                        # unit tests (subprocess is mocked)
+ORCA_INTEGRATION=1 uv run pytest     # also run read-only tests against the real orca
+uv build
+```
+
+The integration tests only run read-only commands: `status`, `project list`, `repo list`, `worktree list`, `host list`, `environment list`, `skills list`, `agent-context` and a `repo show` that is expected to fail.
+
+### Regenerating the wrappers
+
+`src/orca_sdk/_generated.py` is generated, so don't edit it by hand. To regenerate it after an Orca upgrade:
+
+```bash
+orca agent-context --json > src/orca_sdk/data/agent-context.json
+# optional, improves flag typing: a dump of `orca <cmd> --help` for every command,
+# each section headed by a line `== orca <cmd> --help`
+python scripts/generate.py --help-dump /path/to/orca-cli-help.txt -v
+uv run pytest
+```
+
+The schema lists each command's flag names but not whether a flag takes a value. The generator works that out from the usage string, then from the `--help` text, which it caches in `data/flag-types.json`. If neither settles it, the generator uses how the same flag is written in other commands. `-v` lists the flags typed that way. `tests/test_generated.py` checks that the generated file is up to date and that every command builds its expected argv.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

orca_cli_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+orca_sdk/__init__.py,sha256=ohBz6dS2WD8IWS-75LLMbia3rRHwlo93mWLohSLIgic,899
+orca_sdk/_async_client.py,sha256=R5SpUfcEM9ivUU94wALfPwkaXqvoms-obHuPm6dMm6g,5629
+orca_sdk/_client.py,sha256=FQ6M2ZG_7eOopnp8bcM-7BjVKjY6vrCNFIR-UBbZIAU,6605
+orca_sdk/_core.py,sha256=XHELsfhuyYfAsoE1kEdLpajSIohuOvsx8njbW3RYcpM,9237
+orca_sdk/_exceptions.py,sha256=1LwZ_b59Aid4nOL4DFUeNfPfUWuYq-09mLfgPtpy9qM,2914
+orca_sdk/_generated.py,sha256=nZdXuNKkZ0IBpgF-fBVvxTteUUgY0OWumDICfDwRaec,518171
+orca_sdk/_resource.py,sha256=jbnvl-vX6dDHTVJ-aybKtYN7Ll19Hq2CaGM0Uo3Jo70,2268
+orca_sdk/_version.py,sha256=DXl7Me4wOFvKowSwVDKR8H7K8YhAeI5Rd9FrofOSKow,126
+orca_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+orca_sdk/schema.py,sha256=Bnf2DlCGpE6mWuv6i7PWs-J1b-j-YW791qjcc6JjwfQ,1063
+orca_sdk/data/agent-context.json,sha256=4srThmqaiHWG9ZxM9YNS9OaTHQGiNwetghWorq3-6og,234529
+orca_sdk/data/flag-types.json,sha256=PD04unlB49w6iGPt5_DiH9VGU82nMXdj7GH8YfmNMHE,42443
+orca_cli_sdk-0.1.0.dist-info/METADATA,sha256=W3h29s8vKSZOl6KwMqxhA4vJoEahpIQS8W65GD625uQ,9365
+orca_cli_sdk-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+orca_cli_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=CiAnvUq7WtvLsARjQc88u2xrII5O5lZaE-zK9bWbZqs,1061
+orca_cli_sdk-0.1.0.dist-info/RECORD,,

orca_cli_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

orca_cli_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orca_sdk/__init__.py

@@ -0,0 +1,41 @@
+"""Python SDK for the Orca CLI.
+
+>>> from orca_sdk import Orca
+>>> client = Orca()
+>>> client.status()["runtime"]["state"]
+'ready'
+"""
+
+from __future__ import annotations
+
+from ._async_client import AsyncOrca
+from ._client import Orca
+from ._core import BINARY_ENV_VAR, DEFAULT_BINARY, DEFAULT_TIMEOUT, NOT_GIVEN, OrcaResponse, find_binary
+from ._exceptions import (
+    OrcaBinaryNotFoundError,
+    OrcaCommandError,
+    OrcaError,
+    OrcaJSONDecodeError,
+    OrcaTimeoutError,
+    OrcaUsageError,
+)
+from ._version import CLI_VERSION, __version__
+
+__all__ = [
+    "BINARY_ENV_VAR",
+    "CLI_VERSION",
+    "DEFAULT_BINARY",
+    "DEFAULT_TIMEOUT",
+    "NOT_GIVEN",
+    "AsyncOrca",
+    "Orca",
+    "OrcaBinaryNotFoundError",
+    "OrcaCommandError",
+    "OrcaError",
+    "OrcaJSONDecodeError",
+    "OrcaResponse",
+    "OrcaTimeoutError",
+    "OrcaUsageError",
+    "__version__",
+    "find_binary",
+]

orca_sdk/_async_client.py

@@ -0,0 +1,171 @@
+"""Asynchronous Orca client built on :mod:`asyncio` subprocesses."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import subprocess
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from ._core import (
+    DEFAULT_TIMEOUT,
+    NOT_GIVEN,
+    ClientConfig,
+    OrcaResponse,
+    PathLike,
+    PreparedCall,
+    find_binary,
+    make_config,
+    parse_output,
+    prepare,
+    prepare_invoke,
+)
+from ._exceptions import OrcaBinaryNotFoundError, OrcaTimeoutError
+from ._generated import AsyncOrcaCommands
+from ._resource import FlagValue
+
+__all__ = ["AsyncOrca"]
+
+
+class AsyncOrca(AsyncOrcaCommands):
+    """Async counterpart of :class:`~orca_sdk.Orca`; every command is awaitable.
+
+    >>> async with AsyncOrca() as client:
+    ...     status = await client.status()
+
+    Accepts the same options as :class:`~orca_sdk.Orca`.
+    """
+
+    def __init__(
+        self,
+        *,
+        binary: PathLike | None = None,
+        timeout: float | None = DEFAULT_TIMEOUT,
+        environment: str | None = None,
+        pairing_code: str | None = None,
+        env: Mapping[str, str] | None = None,
+        inherit_env: bool = True,
+        cwd: PathLike | None = None,
+    ) -> None:
+        super().__init__()
+        self._config = make_config(binary, timeout, environment, pairing_code, env, inherit_env, cwd)
+        self._binary: str | None = None
+
+    @classmethod
+    def _from_config(cls, config: ClientConfig) -> AsyncOrca:
+        client = cls.__new__(cls)
+        AsyncOrcaCommands.__init__(client)
+        client._config = config
+        client._binary = None
+        return client
+
+    @property
+    def binary(self) -> str:
+        """Resolved path of the ``orca`` executable (located lazily)."""
+        if self._binary is None:
+            self._binary = find_binary(self._config.binary)
+        return self._binary
+
+    @property
+    def config(self) -> ClientConfig:
+        """The options this client runs commands with (timeout, environment, ...)."""
+        return self._config
+
+    def with_options(
+        self,
+        *,
+        binary: PathLike | None = NOT_GIVEN,
+        timeout: float | None = NOT_GIVEN,
+        environment: str | None = NOT_GIVEN,
+        pairing_code: str | None = NOT_GIVEN,
+        env: Mapping[str, str] | None = NOT_GIVEN,
+        inherit_env: bool = NOT_GIVEN,
+        cwd: PathLike | None = NOT_GIVEN,
+    ) -> AsyncOrca:
+        """Return a copy of this client with some options changed."""
+        config = self._config.updated(
+            binary=binary,
+            timeout=timeout,
+            environment=environment,
+            pairing_code=pairing_code,
+            env=env,
+            inherit_env=inherit_env,
+            cwd=cwd,
+        )
+        return self._from_config(make_config(**vars(config)))
+
+    async def run_command(
+        self,
+        args: Sequence[str],
+        *,
+        json: bool = True,
+        remote: bool = True,
+        stdin: str | bytes | None = None,
+        timeout: float | None = NOT_GIVEN,
+        check: bool = True,
+    ) -> OrcaResponse:
+        """Run ``orca <args...>``; see :meth:`orca_sdk.Orca.run_command`."""
+        call = prepare(
+            self._config, self.binary, list(args), json=json, remote=remote, stdin=stdin, timeout=timeout
+        )
+        return await self._execute(call, check=check)
+
+    async def _invoke(
+        self,
+        command: str,
+        positionals: Sequence[Any],
+        flags: Sequence[tuple[str, FlagValue]],
+        *,
+        json: bool,
+        remote: bool,
+        stdin: str | bytes | None = None,
+    ) -> Any:
+        call = prepare_invoke(
+            self._config, self.binary, command, positionals, flags, json=json, remote=remote, stdin=stdin
+        )
+        return (await self._execute(call)).result
+
+    async def _execute(self, call: PreparedCall, *, check: bool = True) -> OrcaResponse:
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *call.argv,
+                stdin=subprocess.PIPE if call.stdin is not None else subprocess.DEVNULL,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                env=call.env,
+                cwd=call.cwd,
+            )
+        except FileNotFoundError as exc:
+            if exc.filename == call.argv[0]:
+                raise OrcaBinaryNotFoundError(
+                    f"orca binary not found: {call.argv[0]}", [call.argv[0]]
+                ) from exc
+            raise
+        try:
+            stdout, stderr = await asyncio.wait_for(proc.communicate(call.stdin), timeout=call.timeout)
+        except asyncio.TimeoutError as exc:
+            with contextlib.suppress(ProcessLookupError):
+                proc.kill()
+            with contextlib.suppress(Exception):
+                await proc.wait()
+            raise OrcaTimeoutError(call.timeout or 0.0, call.argv) from exc
+        except BaseException:
+            # Cancellation: don't leave the CLI running.
+            with contextlib.suppress(ProcessLookupError):
+                proc.kill()
+            raise
+        assert proc.returncode is not None
+        return parse_output(call, proc.returncode, stdout, stderr, check=check)
+
+    async def aclose(self) -> None:
+        """No-op; present so the client can be used as an async context manager."""
+
+    async def __aenter__(self) -> AsyncOrca:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    def __repr__(self) -> str:
+        return f"AsyncOrca(binary={self._config.binary or self._binary!r}, environment={self._config.environment!r})"

orca_sdk/_client.py

@@ -0,0 +1,195 @@
+"""Synchronous Orca client."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from ._core import (
+    DEFAULT_TIMEOUT,
+    NOT_GIVEN,
+    ClientConfig,
+    OrcaResponse,
+    PathLike,
+    PreparedCall,
+    find_binary,
+    make_config,
+    parse_output,
+    prepare,
+    prepare_invoke,
+)
+from ._exceptions import OrcaBinaryNotFoundError, OrcaTimeoutError
+from ._generated import OrcaCommands
+from ._resource import FlagValue
+
+__all__ = ["Orca"]
+
+
+class Orca(OrcaCommands):
+    """Run Orca CLI commands from Python.
+
+    Every CLI command is available as a method mirroring its path, e.g.
+    ``orca worktree list --limit 5`` is ``client.worktree.list(limit=5)`` and
+    ``orca status`` is ``client.status()``. JSON-capable commands return the
+    ``result`` from the CLI's ``{ok, result, error}`` envelope; failures raise
+    :class:`~orca_sdk.OrcaCommandError`.
+
+    Args:
+        binary: Path to the ``orca`` executable. Defaults to ``$ORCA_BIN``,
+            then ``orca`` on ``$PATH``, then ``/home/box/Applications/bin/orca``.
+        timeout: Seconds before a command is killed (``None`` waits forever).
+        environment: Saved remote Orca server (id or name) passed as
+            ``--environment`` to every command that accepts it.
+        pairing_code: ``orca://pair?...`` code for a remote runtime, passed to
+            the CLI through ``$ORCA_PAIRING_CODE``.
+        env: Extra environment variables for the subprocess.
+        inherit_env: Start from ``os.environ`` (default) or an empty environment.
+        cwd: Working directory for the subprocess; Orca infers the current
+            worktree from it.
+    """
+
+    def __init__(
+        self,
+        *,
+        binary: PathLike | None = None,
+        timeout: float | None = DEFAULT_TIMEOUT,
+        environment: str | None = None,
+        pairing_code: str | None = None,
+        env: Mapping[str, str] | None = None,
+        inherit_env: bool = True,
+        cwd: PathLike | None = None,
+    ) -> None:
+        super().__init__()
+        self._config = make_config(binary, timeout, environment, pairing_code, env, inherit_env, cwd)
+        self._binary: str | None = None
+
+    @classmethod
+    def _from_config(cls, config: ClientConfig) -> Orca:
+        client = cls.__new__(cls)
+        OrcaCommands.__init__(client)
+        client._config = config
+        client._binary = None
+        return client
+
+    @property
+    def binary(self) -> str:
+        """Resolved path of the ``orca`` executable (located lazily)."""
+        if self._binary is None:
+            self._binary = find_binary(self._config.binary)
+        return self._binary
+
+    @property
+    def config(self) -> ClientConfig:
+        """The options this client runs commands with (timeout, environment, ...)."""
+        return self._config
+
+    def with_options(
+        self,
+        *,
+        binary: PathLike | None = NOT_GIVEN,
+        timeout: float | None = NOT_GIVEN,
+        environment: str | None = NOT_GIVEN,
+        pairing_code: str | None = NOT_GIVEN,
+        env: Mapping[str, str] | None = NOT_GIVEN,
+        inherit_env: bool = NOT_GIVEN,
+        cwd: PathLike | None = NOT_GIVEN,
+    ) -> Orca:
+        """Return a copy of this client with some options changed.
+
+        >>> client.with_options(timeout=300).terminal.wait(terminal="term_1", for_="exit")
+        """
+        config = self._config.updated(
+            binary=binary,
+            timeout=timeout,
+            environment=environment,
+            pairing_code=pairing_code,
+            env=env,
+            inherit_env=inherit_env,
+            cwd=cwd,
+        )
+        return self._from_config(make_config(**vars(config)))
+
+    def run_command(
+        self,
+        args: Sequence[str],
+        *,
+        json: bool = True,
+        remote: bool = True,
+        stdin: str | bytes | None = None,
+        timeout: float | None = NOT_GIVEN,
+        check: bool = True,
+    ) -> OrcaResponse:
+        """Run ``orca <args...>`` and return the parsed response.
+
+        Use this for commands or flags the generated wrappers do not cover.
+        ``--json`` is appended when ``json`` is true; ``remote`` controls
+        whether the client's ``environment``/``pairing_code`` are applied.
+        With ``check=False`` a failing envelope is returned instead of raised.
+        """
+        call = prepare(
+            self._config, self.binary, list(args), json=json, remote=remote, stdin=stdin, timeout=timeout
+        )
+        return self._execute(call, check=check)
+
+    def _invoke(
+        self,
+        command: str,
+        positionals: Sequence[Any],
+        flags: Sequence[tuple[str, FlagValue]],
+        *,
+        json: bool,
+        remote: bool,
+        stdin: str | bytes | None = None,
+    ) -> Any:
+        call = prepare_invoke(
+            self._config, self.binary, command, positionals, flags, json=json, remote=remote, stdin=stdin
+        )
+        return self._execute(call).result
+
+    def _execute(self, call: PreparedCall, *, check: bool = True) -> OrcaResponse:
+        try:
+            proc = subprocess.run(
+                call.argv,
+                input=call.stdin,
+                stdin=None if call.stdin is not None else subprocess.DEVNULL,
+                capture_output=True,
+                env=call.env,
+                cwd=call.cwd,
+                timeout=call.timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise OrcaTimeoutError(
+                call.timeout or 0.0,
+                call.argv,
+                stdout=_text(exc.stdout),
+                stderr=_text(exc.stderr),
+            ) from exc
+        except FileNotFoundError as exc:
+            if exc.filename == call.argv[0]:
+                raise OrcaBinaryNotFoundError(
+                    f"orca binary not found: {call.argv[0]}", [call.argv[0]]
+                ) from exc
+            raise
+        return parse_output(call, proc.returncode, proc.stdout, proc.stderr, check=check)
+
+    def close(self) -> None:
+        """No-op; present so the client can be used as a context manager."""
+
+    def __enter__(self) -> Orca:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return (
+            f"Orca(binary={self._config.binary or self._binary!r}, environment={self._config.environment!r})"
+        )
+
+
+def _text(data: bytes | str | None) -> str:
+    if isinstance(data, bytes):
+        return data.decode("utf-8", errors="replace")
+    return data or ""