runloop-api-client 1.10.3__tar.gz → 1.12.0__tar.gz

runloop_api_client-1.12.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.12.0"
+}

{runloop_api_client-1.10.3 → runloop_api_client-1.12.0}/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 1.12.0 (2026-03-18)
+
+Full Changelog: [v1.11.0...v1.12.0](https://github.com/runloopai/api-client-python/compare/v1.11.0...v1.12.0)
+
+### Features
+
+* add secrets to oo-sdk ([#756](https://github.com/runloopai/api-client-python/issues/756)) ([09c4997](https://github.com/runloopai/api-client-python/commit/09c4997908ca7ec2ab9a45173d4d0bcf33ad2ca2))
+
+
+### Bug Fixes
+
+* **deps:** bump minimum typing-extensions version ([a873aad](https://github.com/runloopai/api-client-python/commit/a873aada5cbf8d29600374039f4d65bd321fa6bb))
+* **pydantic:** do not pass `by_alias` unless set ([baf3a9a](https://github.com/runloopai/api-client-python/commit/baf3a9a8fe64e14f92f31387781f95dc6c7753de))
+
+
+### Chores
+
+* configure new SDK language ([13d3ada](https://github.com/runloopai/api-client-python/commit/13d3adaa20a78b6d02db41369505f28aed92e1f5))
+* **internal:** tweak CI branches ([b374486](https://github.com/runloopai/api-client-python/commit/b374486156c36b01c55135e4a0c1871b78360176))
+
+## 1.11.0 (2026-03-10)
+
+Full Changelog: [v1.10.3...v1.11.0](https://github.com/runloopai/api-client-python/compare/v1.10.3...v1.11.0)
+
+### Features
+
+* add snapshots example ([#753](https://github.com/runloopai/api-client-python/issues/753)) ([f13916a](https://github.com/runloopai/api-client-python/commit/f13916a570fe708aef56c6fbfd5c06b9e0dc158e))
+* **documentation:** added llms.txt, examples and referenced these artifacts via README ([#748](https://github.com/runloopai/api-client-python/issues/748)) ([bceb953](https://github.com/runloopai/api-client-python/commit/bceb953c8486bec6bbe5bca1276ed54d625eda5d))
+
+
+### Bug Fixes
+
+* add logs to devboxes, smoke tests & examples ([#755](https://github.com/runloopai/api-client-python/issues/755)) ([da5faa4](https://github.com/runloopai/api-client-python/commit/da5faa4e69348dd6f034a538046ab9ff2ff4831b))
+
+
+### Chores
+
+* **ci:** skip uploading artifacts on stainless-internal branches ([6874252](https://github.com/runloopai/api-client-python/commit/6874252fe355ac8a44be6bc57cd6bb15a3f035be))
+* **documentation:** correct exec advice ([#752](https://github.com/runloopai/api-client-python/issues/752)) ([fa16c1d](https://github.com/runloopai/api-client-python/commit/fa16c1d602ec301200e82a48fe23c2218ae82a08))
+* **test:** do not count install time for mock server timeout ([f6fde05](https://github.com/runloopai/api-client-python/commit/f6fde050a5f4b985c01003cd7593c1619ede028f))
+* update placeholder string ([5dfcd93](https://github.com/runloopai/api-client-python/commit/5dfcd93bb05cda783901377ee7fc03a6acffe0ae))
+
 ## 1.10.3 (2026-02-27)
 
 Full Changelog: [v1.10.2...v1.10.3](https://github.com/runloopai/api-client-python/compare/v1.10.2...v1.10.3)

runloop_api_client-1.12.0/EXAMPLES.md

@@ -0,0 +1,169 @@
+# Examples
+
+> This file is auto-generated from metadata in `examples/*.py`.
+> Do not edit this file manually. Run `uv run python scripts/generate_examples_md.py` instead.
+
+Runnable examples live in [`examples/`](./examples).
+
+## Table of Contents
+
+- [Blueprint with Build Context](#blueprint-with-build-context)
+- [Devbox From Blueprint (Run Command, Shutdown)](#devbox-from-blueprint-lifecycle)
+- [Devbox Snapshot and Resume](#devbox-snapshot-resume)
+- [MCP Hub + Claude Code + GitHub](#mcp-github-tools)
+- [Secrets with Devbox (Create, Inject, Verify, Delete)](#secrets-with-devbox)
+
+<a id="blueprint-with-build-context"></a>
+## Blueprint with Build Context
+
+**Use case:** Create a blueprint using the object store to provide docker build context files, then verify files are copied into the image. Uses the async SDK.
+
+**Tags:** `blueprint`, `object-store`, `build-context`, `devbox`, `cleanup`, `async`
+
+### Workflow
+- Create a temporary directory with sample application files
+- Upload the directory to object storage as build context
+- Create a blueprint with a Dockerfile that copies the context files
+- Create a devbox from the blueprint
+- Verify the files were copied into the image
+- Shutdown devbox and delete blueprint and storage object
+
+### Prerequisites
+- `RUNLOOP_API_KEY`
+
+### Run
+```sh
+uv run python -m examples.blueprint_with_build_context
+```
+
+### Test
+```sh
+uv run pytest -m smoketest tests/smoketests/examples/
+```
+
+**Source:** [`examples/blueprint_with_build_context.py`](./examples/blueprint_with_build_context.py)
+
+<a id="devbox-from-blueprint-lifecycle"></a>
+## Devbox From Blueprint (Run Command, Shutdown)
+
+**Use case:** Create a devbox from a blueprint, run a command, fetch logs, validate output, and cleanly tear everything down.
+
+**Tags:** `devbox`, `blueprint`, `commands`, `logs`, `cleanup`
+
+### Workflow
+- Create a blueprint
+- Fetch blueprint build logs
+- Create a devbox from the blueprint
+- Execute a command in the devbox
+- Fetch devbox logs
+- Validate exit code, stdout, and logs
+- Shutdown devbox and delete blueprint
+
+### Prerequisites
+- `RUNLOOP_API_KEY`
+
+### Run
+```sh
+uv run python -m examples.devbox_from_blueprint_lifecycle
+```
+
+### Test
+```sh
+uv run pytest -m smoketest tests/smoketests/examples/
+```
+
+**Source:** [`examples/devbox_from_blueprint_lifecycle.py`](./examples/devbox_from_blueprint_lifecycle.py)
+
+<a id="devbox-snapshot-resume"></a>
+## Devbox Snapshot and Resume
+
+**Use case:** Create a devbox, snapshot its disk, resume from the snapshot, and demonstrate that changes in the original devbox do not affect the clone. Uses the async SDK.
+
+**Tags:** `devbox`, `snapshot`, `resume`, `cleanup`, `async`
+
+### Workflow
+- Create a devbox
+- Write a file to the devbox
+- Create a disk snapshot
+- Create a new devbox from the snapshot
+- Modify the file on the original devbox
+- Verify the clone has the original content
+- Shutdown both devboxes and delete the snapshot
+
+### Prerequisites
+- `RUNLOOP_API_KEY`
+
+### Run
+```sh
+uv run python -m examples.devbox_snapshot_resume
+```
+
+### Test
+```sh
+uv run pytest -m smoketest tests/smoketests/examples/
+```
+
+**Source:** [`examples/devbox_snapshot_resume.py`](./examples/devbox_snapshot_resume.py)
+
+<a id="mcp-github-tools"></a>
+## MCP Hub + Claude Code + GitHub
+
+**Use case:** Connect Claude Code running in a devbox to GitHub tools through MCP Hub without exposing raw GitHub credentials to the devbox.
+
+**Tags:** `mcp`, `devbox`, `github`, `commands`, `cleanup`
+
+### Workflow
+- Create an MCP config for GitHub
+- Store GitHub token as a Runloop secret
+- Launch a devbox with MCP Hub wiring
+- Install Claude Code and register MCP endpoint
+- Run a Claude prompt through MCP tools
+- Shutdown devbox and clean up cloud resources
+
+### Prerequisites
+- `RUNLOOP_API_KEY`
+- `GITHUB_TOKEN (GitHub PAT with repo scope)`
+- `ANTHROPIC_API_KEY`
+
+### Run
+```sh
+GITHUB_TOKEN=ghp_xxx ANTHROPIC_API_KEY=sk-ant-xxx uv run python -m examples.mcp_github_tools
+```
+
+### Test
+```sh
+uv run pytest -m smoketest tests/smoketests/examples/
+```
+
+**Source:** [`examples/mcp_github_tools.py`](./examples/mcp_github_tools.py)
+
+<a id="secrets-with-devbox"></a>
+## Secrets with Devbox (Create, Inject, Verify, Delete)
+
+**Use case:** Create a secret, inject it into a devbox as an environment variable, verify access, and clean up.
+
+**Tags:** `secrets`, `devbox`, `environment-variables`, `cleanup`
+
+### Workflow
+- Create a secret with a test value
+- Create a devbox with the secret mapped to an env var
+- Execute a command that reads the secret from the environment
+- Verify the value matches
+- Update the secret and verify
+- List secrets and verify the secret appears
+- Shutdown devbox and delete secret
+
+### Prerequisites
+- `RUNLOOP_API_KEY`
+
+### Run
+```sh
+uv run python -m examples.secrets_with_devbox
+```
+
+### Test
+```sh
+uv run pytest -m smoketest tests/smoketests/examples/
+```
+
+**Source:** [`examples/secrets_with_devbox.py`](./examples/secrets_with_devbox.py)

{runloop_api_client-1.10.3 → runloop_api_client-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: runloop_api_client
-Version: 1.10.3
+Version: 1.12.0
 Summary: The official Python library for the runloop API
 Project-URL: Homepage, https://github.com/runloopai/api-client-python
 Project-URL: Repository, https://github.com/runloopai/api-client-python
@@ -28,7 +28,7 @@ Requires-Dist: distro<2,>=1.7.0
 Requires-Dist: httpx<1,>=0.23.0
 Requires-Dist: pydantic<3,>=2.0
 Requires-Dist: sniffio
-Requires-Dist: typing-extensions<5,>=4.10
+Requires-Dist: typing-extensions<5,>=4.14
 Requires-Dist: uuid-utils>=0.11.0
 Provides-Extra: aiohttp
 Requires-Dist: aiohttp; extra == 'aiohttp'
@@ -46,6 +46,15 @@ and offers both synchronous and asynchronous clients powered by [httpx](https://
 
 It is generated with [Stainless](https://www.stainless.com/).
 
+## MCP Server
+
+Use the Runloop MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=%40runloop%2Fapi-client-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBydW5sb29wL2FwaS1jbGllbnQtbWNwIl0sImVudiI6eyJSVU5MT09QX0FQSV9LRVkiOiJNeSBCZWFyZXIgVG9rZW4ifX0)
+[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40runloop%2Fapi-client-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40runloop%2Fapi-client-mcp%22%5D%2C%22env%22%3A%7B%22RUNLOOP_API_KEY%22%3A%22My%20Bearer%20Token%22%7D%7D)
+
+> Note: You may need to set environment variables in your MCP client.
+
 ## Documentation
 
 The REST API documentation can be found on
@@ -125,6 +134,23 @@ asyncio.run(main())
 
 Functionality between the synchronous and asynchronous clients is otherwise identical.
 
+## Examples
+
+Workflow-oriented runnable examples are documented in [`EXAMPLES.md`](./EXAMPLES.md).
+
+`EXAMPLES.md` is generated from metadata in `examples/*.py` and should not be edited manually.
+Regenerate it with:
+
+```sh
+uv run python scripts/generate_examples_md.py
+```
+
+## Agent Guidance
+
+Detailed agent-specific instructions for developing using this package live in [`llms.txt`](./llms.txt). Consolidated recipes for frequent tasks are in [`EXAMPLES.md`](./EXAMPLES.md).
+
+After completing any modifications to this project, ensure `llms.txt` and `README.md` are kept in sync.
+
 ### With aiohttp
 
 By default, the async client uses `httpx` for HTTP requests. However, for improved concurrency performance you may also use `aiohttp` as the HTTP backend.
@@ -517,6 +543,17 @@ print(runloop_api_client.__version__)
 
 Python 3.9 or higher.
 
+## Development
+
+After cloning the repository, run the bootstrap script and install git hooks:
+
+```sh
+./scripts/bootstrap
+./scripts/install-hooks
+```
+
+This installs pre-push hooks that run linting and verify generated files are up to date.
+
 ## Contributing
 
 See [the contributing documentation](./CONTRIBUTING.md).

{runloop_api_client-1.10.3 → runloop_api_client-1.12.0}/README-SDK.md

@@ -116,6 +116,7 @@ The SDK provides object-oriented interfaces for all major Runloop resources:
 - **`runloop.blueprint`** - Blueprint management (create, list, build blueprints)
 - **`runloop.snapshot`** - Snapshot management (list disk snapshots)
 - **`runloop.storage_object`** - Storage object management (upload, download, list objects)
+- **`runloop.secret`** - Secret management (create, update, list, delete encrypted key-value pairs)
 - **`runloop.api`** - Direct access to the underlying REST API client
 
 ### Devbox
@@ -160,13 +161,13 @@ print(f"Devbox {info.name} is {info.status}")
 Execute commands synchronously or asynchronously:
 
 ```python
-# Synchronous command execution (waits for completion)
+# exec blocks until completion - use for commands that return immediately
 result = devbox.cmd.exec("ls -la")
 print("Output:", result.stdout())
 print("Exit code:", result.exit_code)
 print("Success:", result.success)
 
-# Asynchronous command execution (returns immediately)
+# exec_async returns immediately - use for long-running processes
 execution = devbox.cmd.exec_async("npm run dev")
 
 # Check execution status
@@ -393,11 +394,30 @@ async with await runloop.devbox.create(name="temp-devbox") as devbox:
 # devbox is automatically shutdown when exiting the context
 ```
 
+#### Devbox Logs
+
+Retrieve logs from a devbox, optionally filtered by execution ID or shell name:
+
+```python
+# Get all devbox logs
+logs = devbox.logs()
+for log in logs.logs:
+    print(f"[{log.level}] {log.message}")
+
+# Filter logs by execution ID
+result = devbox.cmd.exec('echo "hello"')
+exec_logs = devbox.logs(execution_id=result.execution_id)
+
+# Filter logs by shell name
+shell_logs = devbox.logs(shell_name="my-shell")
+```
+
 **Key methods:**
 
 - `devbox.get_info()` - Get devbox details and status
 - `devbox.cmd.exec()` - Execute commands synchronously
 - `devbox.cmd.exec_async()` - Execute commands asynchronously
+- `devbox.logs()` - Retrieve devbox logs (optionally filter by execution_id or shell_name)
 - `devbox.file.read()` - Read file contents
 - `devbox.file.write()` - Write file contents
 - `devbox.file.upload()` - Upload files

{runloop_api_client-1.10.3 → runloop_api_client-1.12.0}/README.md

@@ -9,6 +9,15 @@ and offers both synchronous and asynchronous clients powered by [httpx](https://
 
 It is generated with [Stainless](https://www.stainless.com/).
 
+## MCP Server
+
+Use the Runloop MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=%40runloop%2Fapi-client-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBydW5sb29wL2FwaS1jbGllbnQtbWNwIl0sImVudiI6eyJSVU5MT09QX0FQSV9LRVkiOiJNeSBCZWFyZXIgVG9rZW4ifX0)
+[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40runloop%2Fapi-client-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40runloop%2Fapi-client-mcp%22%5D%2C%22env%22%3A%7B%22RUNLOOP_API_KEY%22%3A%22My%20Bearer%20Token%22%7D%7D)
+
+> Note: You may need to set environment variables in your MCP client.
+
 ## Documentation
 
 The REST API documentation can be found on
@@ -88,6 +97,23 @@ asyncio.run(main())
 
 Functionality between the synchronous and asynchronous clients is otherwise identical.
 
+## Examples
+
+Workflow-oriented runnable examples are documented in [`EXAMPLES.md`](./EXAMPLES.md).
+
+`EXAMPLES.md` is generated from metadata in `examples/*.py` and should not be edited manually.
+Regenerate it with:
+
+```sh
+uv run python scripts/generate_examples_md.py
+```
+
+## Agent Guidance
+
+Detailed agent-specific instructions for developing using this package live in [`llms.txt`](./llms.txt). Consolidated recipes for frequent tasks are in [`EXAMPLES.md`](./EXAMPLES.md).
+
+After completing any modifications to this project, ensure `llms.txt` and `README.md` are kept in sync.
+
 ### With aiohttp
 
 By default, the async client uses `httpx` for HTTP requests. However, for improved concurrency performance you may also use `aiohttp` as the HTTP backend.
@@ -480,6 +506,17 @@ print(runloop_api_client.__version__)
 
 Python 3.9 or higher.
 
+## Development
+
+After cloning the repository, run the bootstrap script and install git hooks:
+
+```sh
+./scripts/bootstrap
+./scripts/install-hooks
+```
+
+This installs pre-push hooks that run linting and verify generated files are up to date.
+
 ## Contributing
 
 See [the contributing documentation](./CONTRIBUTING.md).

runloop_api_client-1.12.0/examples/__init__.py

@@ -0,0 +1 @@
+# Examples package for Runloop Python SDK

runloop_api_client-1.12.0/examples/_harness.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import sys
+import json
+import time
+import asyncio
+from typing import Any, TypeVar, Callable, Awaitable
+from dataclasses import asdict
+
+from .example_types import (
+    ExampleCheck,
+    RecipeOutput,
+    ExampleResult,
+    RecipeContext,
+    ExampleCleanupStatus,
+    ExampleCleanupFailure,
+)
+
+T = TypeVar("T")
+
+
+def unique_name(prefix: str) -> str:
+    """Generate a unique name with timestamp and random suffix."""
+    return f"{prefix}-{int(time.time())}-{hex(int(time.time() * 1000) % 0xFFFFFF)[2:]}"
+
+
+class _CleanupTracker:
+    """Tracks cleanup actions and executes them in LIFO order."""
+
+    def __init__(self, status: ExampleCleanupStatus) -> None:
+        self._status = status
+        self._actions: list[tuple[str, Callable[[], Any]]] = []
+
+    def add(self, resource: str, action: Callable[[], Any]) -> None:
+        """Register a cleanup action for a resource."""
+        self._actions.append((resource, action))
+
+    async def run(self) -> None:
+        """Execute all cleanup actions in reverse order."""
+        while self._actions:
+            resource, action = self._actions.pop()
+            self._status.attempted.append(resource)
+            try:
+                result = action()
+                if asyncio.iscoroutine(result):
+                    await result
+                self._status.succeeded.append(resource)
+            except Exception as e:
+                self._status.failed.append(ExampleCleanupFailure(resource, str(e)))
+
+        if self._status.attempted:
+            if not self._status.failed:
+                print("Cleanup completed.")  # noqa: T201
+            else:
+                print("Cleanup finished with errors.")  # noqa: T201
+
+
+def _should_fail_process(result: ExampleResult) -> bool:
+    """Determine if the process should exit with failure."""
+    has_failed_checks = any(not check.passed for check in result.checks)
+    return result.skipped or has_failed_checks or len(result.cleanup_status.failed) > 0
+
+
+def _run_recipe_impl(
+    recipe_call: Callable[[], RecipeOutput | Awaitable[RecipeOutput]],
+    cleanup: _CleanupTracker,
+    cleanup_status: ExampleCleanupStatus,
+) -> ExampleResult:
+    """Shared implementation for running recipes with cleanup."""
+
+    async def _run_async() -> RecipeOutput:
+        try:
+            result = recipe_call()
+            if asyncio.iscoroutine(result):
+                output: RecipeOutput = await result
+                return output
+            return result  # type: ignore[return-value]
+        finally:
+            await cleanup.run()
+
+    loop = asyncio.new_event_loop()
+    try:
+        output = loop.run_until_complete(_run_async())
+        return ExampleResult(
+            resources_created=output.resources_created,
+            checks=output.checks,
+            cleanup_status=cleanup_status,
+        )
+    finally:
+        loop.close()
+
+
+def wrap_recipe(
+    recipe: Callable[[RecipeContext], RecipeOutput] | Callable[[RecipeContext], Awaitable[RecipeOutput]],
+    validate_env: Callable[[], tuple[bool, list[ExampleCheck]]] | None = None,
+) -> Callable[[], ExampleResult]:
+    """Wrap a recipe function with cleanup tracking and result handling.
+
+    Args:
+        recipe: The recipe function to wrap. Can be sync or async.
+        validate_env: Optional function to validate environment before running.
+                      Returns (skip, checks) tuple.
+
+    Returns:
+        A callable that runs the recipe and returns ExampleResult.
+    """
+
+    def run() -> ExampleResult:
+        cleanup_status = ExampleCleanupStatus()
+        cleanup = _CleanupTracker(cleanup_status)
+
+        if validate_env is not None:
+            skip, checks = validate_env()
+            if skip:
+                return ExampleResult(
+                    resources_created=[],
+                    checks=checks,
+                    cleanup_status=cleanup_status,
+                    skipped=True,
+                )
+
+        ctx = RecipeContext(cleanup=cleanup)
+        return _run_recipe_impl(lambda: recipe(ctx), cleanup, cleanup_status)
+
+    return run
+
+
+def wrap_recipe_with_options(
+    recipe: Callable[[RecipeContext, T], RecipeOutput] | Callable[[RecipeContext, T], Awaitable[RecipeOutput]],
+    validate_env: Callable[[T], tuple[bool, list[ExampleCheck]]] | None = None,
+) -> Callable[[T], ExampleResult]:
+    """Wrap a recipe function that takes options with cleanup tracking.
+
+    Args:
+        recipe: The recipe function to wrap. Can be sync or async. Takes options parameter.
+        validate_env: Optional function to validate environment before running.
+                      Takes options and returns (skip, checks) tuple.
+
+    Returns:
+        A callable that runs the recipe with options and returns ExampleResult.
+    """
+
+    def run(options: T) -> ExampleResult:
+        cleanup_status = ExampleCleanupStatus()
+        cleanup = _CleanupTracker(cleanup_status)
+
+        if validate_env is not None:
+            skip, checks = validate_env(options)
+            if skip:
+                return ExampleResult(
+                    resources_created=[],
+                    checks=checks,
+                    cleanup_status=cleanup_status,
+                    skipped=True,
+                )
+
+        ctx = RecipeContext(cleanup=cleanup)
+        return _run_recipe_impl(lambda: recipe(ctx, options), cleanup, cleanup_status)
+
+    return run
+
+
+def run_as_cli(run: Callable[[], ExampleResult]) -> None:
+    """Run an example and exit with appropriate status code."""
+    try:
+        result = run()
+        print(json.dumps(asdict(result), indent=2))  # noqa: T201
+        if _should_fail_process(result):
+            sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}")  # noqa: T201
+        sys.exit(1)