# Protocol Version Schema for Preview-Bundle/v1 and Preview-Trajectory/v1 in CLI-Anything > Discover the protocol version schema for preview-bundle/v1 and preview-trajectory/v1 in CLI-Anything. Learn about the /v structure. - Repository: [✨Data Intelligence Lab@HKU✨/CLI-Anything](https://github.com/HKUDS/CLI-Anything) - Tags: api-reference - Published: 2026-05-18 --- **CLI-Anything uses two protocol version identifiers—`"preview-bundle/v1"` for bundle manifests and `"preview-trajectory/v1"` for trajectory files—following a strict `"/v"` schema defined in each agent harness's [`preview_bundle.py`](https://github.com/HKUDS/CLI-Anything/blob/main/preview_bundle.py) utility.** The CLI-Anything repository provides agent harnesses for multiple software applications that generate preview bundles and live trajectories. Understanding the **protocol version schema** ensures your integrations correctly interpret manifest files and trajectory data across different versions of the toolkit. ## Protocol Version Schema Definition CLI-Anything implements a simple, extensible versioning pattern for its preview system. The schema follows the format: ``` "/v" ``` Where: - **``** specifies the entity type, either `preview-bundle` or `preview-trajectory`. - **`v`** indicates the major version number, currently `v1` for both protocols. When maintainers release breaking changes, the version increments to `v2` while preserving the same structural pattern (e.g., `"preview-bundle/v2"`). ## Where Protocol Versions Are Defined The protocol version constants reside in each agent harness's [`preview_bundle.py`](https://github.com/HKUDS/CLI-Anything/blob/main/preview_bundle.py) utility module. All harnesses—including FreeCAD, Blender, Shotcut, RenderDoc, and OpenScreen—maintain identical definitions in their respective paths: - [`freecad/agent-harness/cli_anything/freecad/utils/preview_bundle.py`](https://github.com/HKUDS/CLI-Anything/blob/main/freecad/agent-harness/cli_anything/freecad/utils/preview_bundle.py) - [`blender/agent-harness/cli_anything/blender/utils/preview_bundle.py`](https://github.com/HKUDS/CLI-Anything/blob/main/blender/agent-harness/cli_anything/blender/utils/preview_bundle.py) - [`shotcut/agent-harness/cli_anything/shotcut/utils/preview_bundle.py`](https://github.com/HKUDS/CLI-Anything/blob/main/shotcut/agent-harness/cli_anything/shotcut/utils/preview_bundle.py) - [`renderdoc/agent-harness/cli_anything/renderdoc/utils/preview_bundle.py`](https://github.com/HKUDS/CLI-Anything/blob/main/renderdoc/agent-harness/cli_anything/renderdoc/utils/preview_bundle.py) - [`openscreen/agent-harness/cli_anything/openscreen/utils/preview_bundle.py`](https://github.com/HKUDS/CLI-Anything/blob/main/openscreen/agent-harness/cli_anything/openscreen/utils/preview_bundle.py) - [`cli-anything-plugin/preview_bundle.py`](https://github.com/HKUDS/CLI-Anything/blob/main/cli-anything-plugin/preview_bundle.py) Each file contains these constant definitions: ```python PROTOCOL_VERSION = "preview-bundle/v1" TRAJECTORY_PROTOCOL_VERSION = "preview-trajectory/v1" ``` ## How Protocol Versions Are Used The protocol version strings tag generated artifacts to ensure consuming applications can parse the data correctly. ### In Preview Bundle Manifests When finalizing a preview bundle, the `finalize_bundle` function writes `PROTOCOL_VERSION` to the [`manifest.json`](https://github.com/HKUDS/CLI-Anything/blob/main/manifest.json) file under the `protocol_version` key. This occurs in [`.../utils/preview_bundle.py`](https://github.com/HKUDS/CLI-Anything/blob/main/.../utils/preview_bundle.py) within each harness. ```python from cli_anything.freecad.utils.preview_bundle import prepare_bundle, finalize_bundle # Initialize a new preview bundle bundle = prepare_bundle( software="freecad", recipe="curiosity-rover", bundle_kind="preview", source_fingerprint="sha256:abc123", ) # Complete the bundle and generate manifest manifest = finalize_bundle( bundle_dir=bundle["bundle_dir"], bundle_id=bundle["bundle_id"], bundle_kind="preview", software="freecad", recipe="curiosity-rover", source={"project_fingerprint": "sha256:abc123"}, artifacts=[], summary={"summary": "Automated preview generation"}, cache_key=bundle["cache_key"], generator={"command": "/cli-anything freecad"}, ) # The manifest contains the protocol version print(manifest["protocol_version"]) # Output: preview-bundle/v1 ``` ### In Live Trajectory Files For live trajectory tracking, the `append_live_trajectory` function records `TRAJECTORY_PROTOCOL_VERSION` in the [`trajectory.json`](https://github.com/HKUDS/CLI-Anything/blob/main/trajectory.json) file. This allows the CLI-Anything plugin to distinguish trajectory formats across different software agents. ```python from cli_anything.freecad.utils.preview_bundle import append_live_trajectory # Update the live trajectory with a new step trajectory = append_live_trajectory( session_dir="~/.cli-anything/previews/freecad/curiosity-rover", software="freecad", recipe="curiosity-rover", bundle_manifest=manifest, publish_reason="preview", project_path="/path/to/project", ) # Verify the trajectory protocol version print(trajectory["protocol_version"]) # Output: preview-trajectory/v1 ``` ## Versioning Strategy and Future Compatibility The current **protocol version schema** uses `v1` for both bundle and trajectory protocols. When CLI-Anything introduces breaking changes—such as modified manifest structures or new required fields—the constants update to `v2` following the same `"/v"` pattern. This approach ensures backward compatibility: older bundles remain parseable by checking their `protocol_version` field, while newer implementations can gate features based on the version string. ## Summary - CLI-Anything defines two protocol version constants: `"preview-bundle/v1"` and `"preview-trajectory/v1"`. - The schema follows `"/v"`, where type identifies the data format and `v` tracks breaking changes. - `PROTOCOL_VERSION` is written to [`manifest.json`](https://github.com/HKUDS/CLI-Anything/blob/main/manifest.json) by `finalize_bundle` in each agent harness's [`preview_bundle.py`](https://github.com/HKUDS/CLI-Anything/blob/main/preview_bundle.py). - `TRAJECTORY_PROTOCOL_VERSION` is written to [`trajectory.json`](https://github.com/HKUDS/CLI-Anything/blob/main/trajectory.json) by `append_live_trajectory`. - All software harnesses (FreeCAD, Blender, Shotcut, RenderDoc, OpenScreen) share identical protocol version definitions. ## Frequently Asked Questions ### What is the exact format of the protocol version schema? The protocol version schema follows `"/v"`. For example, `"preview-bundle/v1"` indicates a preview bundle at major version 1, while `"preview-trajectory/v1"` indicates a trajectory file at major version 1. This pattern remains consistent across all CLI-Anything agent harnesses. ### Where is the protocol version stored in preview bundles? The protocol version is stored in the bundle's [`manifest.json`](https://github.com/HKUDS/CLI-Anything/blob/main/manifest.json) file under the key `protocol_version`. The `finalize_bundle` function in [`.../utils/preview_bundle.py`](https://github.com/HKUDS/CLI-Anything/blob/main/.../utils/preview_bundle.py) populates this field using the `PROTOCOL_VERSION` constant (`"preview-bundle/v1"`). ### How does CLI-Anything handle protocol version updates? When breaking changes occur, the maintainers increment the major version number in the constants (e.g., from `v1` to `v2`). The schema pattern `"/v"` remains unchanged, allowing downstream tools to parse the version string consistently while detecting format differences via the version number. ### Are protocol versions consistent across different software harnesses? Yes. All agent harnesses—including FreeCAD, Blender, Shotcut, RenderDoc, and OpenScreen—use identical protocol version strings. Each harness's [`preview_bundle.py`](https://github.com/HKUDS/CLI-Anything/blob/main/preview_bundle.py) file defines `PROTOCOL_VERSION = "preview-bundle/v1"` and `TRAJECTORY_PROTOCOL_VERSION = "preview-trajectory/v1"`, ensuring cross-platform compatibility.