unique-sdk 2026.26.0.dev8__tar.gz → 2026.26.0.dev9__tar.gz

{unique_sdk-2026.26.0.dev8 → unique_sdk-2026.26.0.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.26.0.dev8
+Version: 2026.26.0.dev9
 Summary: 
 Author: Martin Fadler, Konstantin Krauss, Andreas Hauri
 Author-email: Martin Fadler <martin.fadler@unique.ch>, Konstantin Krauss <konstantin@unique.ch>, Andreas Hauri <andreas@unique.ch>

{unique_sdk-2026.26.0.dev8 → unique_sdk-2026.26.0.dev9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_sdk"
-version = "2026.26.0.dev8"
+version = "2026.26.0.dev9"
 description = ""
 readme = "README.md"
 license = { text = "MIT" }

{unique_sdk-2026.26.0.dev8 → unique_sdk-2026.26.0.dev9}/unique_sdk/api_resources/_content.py

@@ -170,6 +170,50 @@ class Content(APIResource["Content"]):
         # a SAS URL the caller PUTs the PDF bytes to. ``file_io.upload_file``
         # exposes this as ``preview_pdf_path`` for a one-call flow.
         previewPdfFileName: NotRequired[str | None]
+        # When true, the platform archives previous blobs for this
+        # content and makes them restorable through the version APIs.
+        versioningEnabled: NotRequired[bool | None]
+
+    class VersionsParams(RequestOptions):
+        contentId: str
+        skip: NotRequired[int | None]
+        take: NotRequired[int | None]
+
+    class ContentVersion(TypedDict):
+        id: str
+        contentId: str
+        versionNumber: int
+        reason: str
+        blobObjectKey: str
+        key: str
+        title: str | None
+        description: str | None
+        url: str | None
+        byteSize: int
+        mimeType: str
+        ownerType: str
+        ownerId: str
+        contentHash: str | None
+        archivedAt: str
+        archivedBy: str | None
+        originalCreatedAt: str
+        originalCreatedBy: str | None
+        createdBy: str | None
+
+    class PaginatedContentVersions(TypedDict):
+        data: list["Content.ContentVersion"]
+        object: str
+
+    class VersionDownloadUrlParams(RequestOptions):
+        contentVersionId: str
+
+    class ContentVersionDownloadUrl(TypedDict):
+        id: str
+        object: str
+        url: str
+
+    class RestoreVersionParams(RequestOptions):
+        contentVersionId: str
 
     class UpdateParams(RequestOptions):
         contentId: NotRequired[str]
@@ -467,6 +511,120 @@ class Content(APIResource["Content"]):
             ),
         )
 
+    @classmethod
+    def versions(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Content.VersionsParams"],
+    ) -> "Content.PaginatedContentVersions":
+        content_id = params.pop("contentId")
+        return cast(
+            Content.PaginatedContentVersions,
+            cls._static_request(
+                "get",
+                f"/content/{content_id}/versions",
+                user_id,
+                company_id,
+                params=params,
+            ),
+        )
+
+    @classmethod
+    async def versions_async(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Content.VersionsParams"],
+    ) -> "Content.PaginatedContentVersions":
+        content_id = params.pop("contentId")
+        return cast(
+            Content.PaginatedContentVersions,
+            await cls._static_request_async(
+                "get",
+                f"/content/{content_id}/versions",
+                user_id,
+                company_id,
+                params=params,
+            ),
+        )
+
+    @classmethod
+    def version_download_url(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Content.VersionDownloadUrlParams"],
+    ) -> "Content.ContentVersionDownloadUrl":
+        content_version_id = params.pop("contentVersionId")
+        return cast(
+            Content.ContentVersionDownloadUrl,
+            cls._static_request(
+                "get",
+                f"/content/versions/{content_version_id}/download-url",
+                user_id,
+                company_id,
+                params=params,
+            ),
+        )
+
+    @classmethod
+    async def version_download_url_async(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Content.VersionDownloadUrlParams"],
+    ) -> "Content.ContentVersionDownloadUrl":
+        content_version_id = params.pop("contentVersionId")
+        return cast(
+            Content.ContentVersionDownloadUrl,
+            await cls._static_request_async(
+                "get",
+                f"/content/versions/{content_version_id}/download-url",
+                user_id,
+                company_id,
+                params=params,
+            ),
+        )
+
+    @classmethod
+    def restore_version(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Content.RestoreVersionParams"],
+    ) -> "Content.ContentInfo":
+        content_version_id = params.pop("contentVersionId")
+        return cast(
+            Content.ContentInfo,
+            cls._static_request(
+                "post",
+                f"/content/versions/{content_version_id}/restore",
+                user_id,
+                company_id,
+                params=params,
+            ),
+        )
+
+    @classmethod
+    async def restore_version_async(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Content.RestoreVersionParams"],
+    ) -> "Content.ContentInfo":
+        content_version_id = params.pop("contentVersionId")
+        return cast(
+            Content.ContentInfo,
+            await cls._static_request_async(
+                "post",
+                f"/content/versions/{content_version_id}/restore",
+                user_id,
+                company_id,
+                params=params,
+            ),
+        )
+
     @classmethod
     def ingest_magic_table_sheets(
         cls,

{unique_sdk-2026.26.0.dev8 → unique_sdk-2026.26.0.dev9}/unique_sdk/cli/cli.py

@@ -20,7 +20,14 @@ from unique_sdk.cli.commands.elicitation import (
     cmd_elicit_respond,
     cmd_elicit_wait,
 )
-from unique_sdk.cli.commands.files import cmd_download, cmd_mv_file, cmd_rm, cmd_upload
+from unique_sdk.cli.commands.files import (
+    cmd_download,
+    cmd_mv_file,
+    cmd_restore_version,
+    cmd_rm,
+    cmd_upload,
+    cmd_versions,
+)
 from unique_sdk.cli.commands.folders import cmd_mkdir, cmd_mvdir, cmd_rmdir
 from unique_sdk.cli.commands.mcp import cmd_mcp
 from unique_sdk.cli.commands.navigation import cmd_cd, cmd_ls, cmd_pwd
@@ -91,6 +98,7 @@ Path formats accepted by all commands:
 \b
 File identifiers:
   report.pdf          File name (matched in current directory)
+  /Reports/report.pdf File path (absolute or relative)
   cont_abc123         Content ID (used directly)
 
 \b
@@ -99,8 +107,10 @@ Examples:
   unique-cli ls                     List root folders
   unique-cli ls /Reports            List a specific folder
   unique-cli search "revenue" -l 50 Search with custom limit
-  unique-cli upload ./file.pdf      Upload to current folder
+  unique-cli upload ./file.pdf      Upload versioned to current folder
   unique-cli download cont_abc123   Download by content ID
+  unique-cli versions cont_abc123   List archived file versions
+  unique-cli restore-version cver_1 Restore a file from a version
   unique-cli elicit ask "Which?"    Ask the user a question synchronously
   unique-cli subagent Legal "Review" Invoke a connected space/subagent
   unique-cli web-search search "x"  Search the web via the public API
@@ -261,12 +271,13 @@ def mvdir(ctx: click.Context, old_name: str, new_name: str) -> None:
 @click.argument("destination", required=False, default=None)
 @click.pass_context
 def upload(ctx: click.Context, local_path: str, destination: str | None) -> None:
-    """Upload a local file (works like Linux cp).
+    """Upload a local file with versioning enabled (works like Linux cp).
 
     \b
-    Uploads LOCAL_PATH to the Unique platform. DESTINATION works like
-    the target in cp -- it can be a folder path, a new filename, or
-    a combination of both. MIME type is auto-detected.
+    Uploads LOCAL_PATH to the Unique platform with immutable versioning
+    enabled. DESTINATION works like the target in cp -- it can be a
+    folder path, a new filename, or a combination of both. MIME type is
+    auto-detected.
 
     \b
     Destination formats:
@@ -288,6 +299,48 @@ def upload(ctx: click.Context, local_path: str, destination: str | None) -> None
     click.echo(cmd_upload(LazyState.get(ctx), local_path, destination))
 
 
+@main.command()
+@click.argument("name_or_id")
+@click.option("--skip", type=int, default=None, help="Number of versions to skip.")
+@click.option("--take", type=int, default=None, help="Number of versions to return.")
+@click.pass_context
+def versions(
+    ctx: click.Context,
+    name_or_id: str,
+    skip: int | None,
+    take: int | None,
+) -> None:
+    """List archived versions for a file.
+
+    \b
+    NAME_OR_ID is a file path, a file name matched in the current
+    directory, or a content ID (cont_...) which is resolved directly.
+
+    \b
+    Examples:
+      unique-cli versions report.pdf
+      unique-cli versions /Reports/Q1/report.pdf
+      unique-cli versions cont_abc123 --take 10
+    """
+    click.echo(cmd_versions(LazyState.get(ctx), name_or_id, skip=skip, take=take))
+
+
+@main.command(name="restore-version")
+@click.argument("content_version_id")
+@click.pass_context
+def restore_version(ctx: click.Context, content_version_id: str) -> None:
+    """Restore a file from a content version ID.
+
+    \b
+    CONTENT_VERSION_ID is returned by `unique-cli versions`.
+
+    \b
+    Examples:
+      unique-cli restore-version cver_abc123
+    """
+    click.echo(cmd_restore_version(LazyState.get(ctx), content_version_id))
+
+
 @main.command()
 @click.argument("name_or_id")
 @click.argument("local_dest", required=False, default=None)
@@ -296,8 +349,8 @@ def download(ctx: click.Context, name_or_id: str, local_dest: str | None) -> Non
     """Download a file to your local machine.
 
     \b
-    NAME_OR_ID is a file name (matched in the current directory) or
-    a content ID (cont_...) which is resolved directly.
+    NAME_OR_ID is a file path, a file name matched in the current
+    directory, or a content ID (cont_...) which is resolved directly.
 
     \b
     LOCAL_DEST is an optional path (directory or file) to save to.
@@ -306,6 +359,7 @@ def download(ctx: click.Context, name_or_id: str, local_dest: str | None) -> Non
     \b
     Examples:
       unique-cli download annual.pdf
+      unique-cli download /Reports/Q1/annual.pdf
       unique-cli download annual.pdf ./downloads/
       unique-cli download cont_abc123 ~/Desktop/
     """
@@ -331,10 +385,12 @@ def cite(
     \b
     Registers [filesourceN] markers for pages you referenced in your answer.
     Does NOT read or extract the file — use your own tools for that.
+    NAME_OR_ID can be a file path, current-directory file name, or content ID.
 
     \b
     Examples:
       unique-cli cite report.pdf --pages 3,5,7
+      unique-cli cite /Reports/Q1/report.pdf --pages 3,5,7
       unique-cli cite cont_abc123 --pages 1-4
     """
     click.echo(cmd_cite_file(LazyState.get(ctx), name_or_id, pages))
@@ -442,15 +498,16 @@ def dynamic_frontend_list(ctx: click.Context, output_json: bool) -> None:
 @click.argument("name_or_id")
 @click.pass_context
 def rm(ctx: click.Context, name_or_id: str) -> None:
-    """Delete a file by name or content ID.
+    """Delete a file by path, name, or content ID.
 
     \b
-    NAME_OR_ID is a file name (matched in the current directory) or
-    a content ID (cont_...).
+    NAME_OR_ID is a file path, a file name matched in the current
+    directory, or a content ID (cont_...).
 
     \b
     Examples:
       unique-cli rm report.pdf
+      unique-cli rm /Reports/Q1/report.pdf
       unique-cli rm cont_abc123
     """
     click.echo(cmd_rm(LazyState.get(ctx), name_or_id))
@@ -465,11 +522,12 @@ def mv(ctx: click.Context, old_name: str, new_name: str) -> None:
 
     \b
     Changes the file's display title without changing its content ID
-    or location. OLD_NAME can be a file name or content ID.
+    or location. OLD_NAME can be a file path, file name, or content ID.
 
     \b
     Examples:
       unique-cli mv annual.pdf annual-2025.pdf
+      unique-cli mv /Reports/Q1/annual.pdf annual-2025.pdf
       unique-cli mv cont_abc123 "New Title.pdf"
     """
     click.echo(cmd_mv_file(LazyState.get(ctx), old_name, new_name))

{unique_sdk-2026.26.0.dev8 → unique_sdk-2026.26.0.dev9}/unique_sdk/cli/commands/files.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import mimetypes
 import shutil
+from collections.abc import Mapping, Sequence
 from pathlib import Path
 from typing import Any
 
@@ -13,32 +14,113 @@ from unique_sdk.cli.state import ShellState
 from unique_sdk.utils.file_io import download_content, upload_file
 
 
+def _normalize_unique_file_path(cwd: str, path: str) -> str:
+    """Normalize a Unique file path without allowing traversal above root."""
+    raw_parts = (
+        path.split("/") if path.startswith("/") else [*cwd.split("/"), *path.split("/")]
+    )
+    parts: list[str] = []
+    for part in raw_parts:
+        if part in ("", "."):
+            continue
+        if part == "..":
+            if not parts:
+                raise ValueError(f"File path escapes root: {path}")
+            parts.pop()
+            continue
+        parts.append(part)
+    return "/" + "/".join(parts)
+
+
 def _resolve_content_id(state: ShellState, name_or_id: str) -> tuple[str, str]:
     """Resolve a file name or content ID to (content_id, display_name).
 
-    Accepts either a content ID (cont_...) or a file name/path.
+    Accepts a content ID (cont_...), a file name in the current folder,
+    or an absolute/relative Unique file path.
     """
     if name_or_id.startswith("cont_"):
+        if not state.is_content_within_workspace(name_or_id):
+            raise ValueError("permission denied (outside workspace scope)")
         return name_or_id, name_or_id
 
+    lookup_name = name_or_id
     scope_id = state.scope_id
+    if "/" in name_or_id:
+        unique_path = _normalize_unique_file_path(state.cwd, name_or_id)
+        folder_path, lookup_name = unique_path.rsplit("/", 1)
+        if not lookup_name:
+            raise ValueError(f"File path must include a file name: {name_or_id}")
+        if not folder_path:
+            folder_path = "/"
+        if not state.is_folder_target_within_workspace(folder_path):
+            raise ValueError("permission denied (outside workspace scope)")
+
+        info = unique_sdk.Folder.get_info(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            folderPath=folder_path,
+        )
+        scope_id = info.get("id")
+        if not scope_id:
+            raise ValueError(f"folder not found: {folder_path}")
+    elif not state.is_within_workspace():
+        raise ValueError("permission denied (outside workspace scope)")
+
     params: dict[str, Any] = {}
     if scope_id:
         params["parentId"] = scope_id
 
-    result = unique_sdk.Content.get_infos(
-        user_id=state.config.user_id,
-        company_id=state.config.company_id,
-        **params,
-    )
-    for info in result.get("contentInfos", []):
-        title = info.get("title") or info.get("key") or ""
-        if title == name_or_id:
-            return info["id"], title
+    take = 100
+    skip = 0
+    while True:
+        result = unique_sdk.Content.get_infos(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            skip=skip,
+            take=take,
+            **params,
+        )
+        content_infos = result.get("contentInfos", [])
+        if not content_infos:
+            break
+
+        for info in content_infos:
+            title = info.get("title") or ""
+            key = info.get("key") or ""
+            if lookup_name in {title, key}:
+                return info["id"], title or key
+
+        skip += len(content_infos)
 
     raise ValueError(f"File not found: {name_or_id}")
 
 
+def _format_version_value(value: Any) -> str:
+    if value is None:
+        return ""
+    return str(value)
+
+
+def _format_content_versions(versions: Sequence[Mapping[str, Any]]) -> str:
+    if not versions:
+        return "No versions found."
+
+    lines = ["VERSION  VERSION_ID  ARCHIVED_AT  REASON  TITLE"]
+    for version in versions:
+        lines.append(
+            "  ".join(
+                [
+                    _format_version_value(version.get("versionNumber")),
+                    _format_version_value(version.get("id")),
+                    _format_version_value(version.get("archivedAt")),
+                    _format_version_value(version.get("reason")),
+                    _format_version_value(version.get("title") or version.get("key")),
+                ]
+            )
+        )
+    return "\n".join(lines)
+
+
 def _resolve_upload_destination(
     state: ShellState,
     local_filename: str,
@@ -144,6 +226,7 @@ def cmd_upload(
             displayed_filename=display_name,
             mime_type=mime_type,
             scope_or_unique_path=scope_id,
+            versioning_enabled=True,
         )
 
         content_id = result.id if hasattr(result, "id") else "?"
@@ -158,6 +241,49 @@ def cmd_upload(
         return f"upload: {e}"
 
 
+def cmd_versions(
+    state: ShellState,
+    name_or_id: str,
+    skip: int | None = None,
+    take: int | None = None,
+) -> str:
+    """List archived versions for a file by name or content ID."""
+    try:
+        content_id, display_name = _resolve_content_id(state, name_or_id)
+        params: dict[str, Any] = {"contentId": content_id}
+        if skip is not None:
+            params["skip"] = skip
+        if take is not None:
+            params["take"] = take
+
+        result = unique_sdk.Content.versions(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            **params,
+        )
+        data = result.get("data", [])
+        return f"Versions for {display_name} ({content_id}):\n{_format_content_versions(data)}"
+    except (ValueError, unique_sdk.APIError) as e:
+        return f"versions: {e}"
+
+
+def cmd_restore_version(state: ShellState, content_version_id: str) -> str:
+    """Restore a file from an archived content version ID."""
+    if not state.is_within_workspace():
+        return "restore-version: permission denied (outside workspace scope)"
+    try:
+        result = unique_sdk.Content.restore_version(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            contentVersionId=content_version_id,
+        )
+        title = result.get("title") or result.get("key") or result.get("id", "?")
+        content_id = result.get("id", "?")
+        return f"Restored: {title} ({content_id}) from version {content_version_id}"
+    except (ValueError, unique_sdk.APIError) as e:
+        return f"restore-version: {e}"
+
+
 def cmd_download(
     state: ShellState,
     name_or_id: str,

{unique_sdk-2026.26.0.dev8 → unique_sdk-2026.26.0.dev9}/unique_sdk/cli/shell.py

@@ -16,7 +16,14 @@ from unique_sdk.cli.commands.elicitation import (
     cmd_elicit_respond,
     cmd_elicit_wait,
 )
-from unique_sdk.cli.commands.files import cmd_download, cmd_mv_file, cmd_rm, cmd_upload
+from unique_sdk.cli.commands.files import (
+    cmd_download,
+    cmd_mv_file,
+    cmd_restore_version,
+    cmd_rm,
+    cmd_upload,
+    cmd_versions,
+)
 from unique_sdk.cli.commands.folders import cmd_mkdir, cmd_mvdir, cmd_rmdir
 from unique_sdk.cli.commands.mcp import cmd_mcp
 from unique_sdk.cli.commands.navigation import cmd_cd, cmd_ls, cmd_pwd
@@ -35,7 +42,7 @@ OVERVIEW_HELP = textwrap.dedent("""\
 
     Navigate the knowledge base like a Linux filesystem. Folders are
     identified by name, path, or scope ID. Files are identified by
-    name or content ID.
+    name, path, or content ID.
 
     Navigation:
       pwd                       Print current working directory
@@ -48,11 +55,13 @@ OVERVIEW_HELP = textwrap.dedent("""\
       mvdir <old> <new>         Rename a folder
 
     File operations:
-      upload <local> [name]     Upload a local file
-      download <name|id> [dest] Download a file to local machine
-      rm <name|id>              Delete a file
-      mv <old> <new>            Rename a file
-      cite <name|id> [--pages]  Declare page citations for a file
+      upload <local> [name]     Upload a local file with versioning
+      versions <name|path|id>   List archived file versions
+      restore-version <ver_id>  Restore a file from a version
+      download <name|path|id> [dest] Download a file to local machine
+      rm <name|path|id>         Delete a file
+      mv <old|path|id> <new>    Rename a file
+      cite <name|path|id> [--pages] Declare page citations for a file
 
     Search:
       search <query> [options]  Combined search (vector + full-text)
@@ -292,13 +301,14 @@ class UniqueShell(cmd.Cmd):
     # -- File operations --
 
     def do_upload(self, arg: str) -> None:
-        """Upload a local file (works like Linux cp).
+        """Upload a local file with versioning enabled (works like Linux cp).
 
         Usage: upload <local_path> [destination]
 
-        Uploads a file from your local machine. The destination argument
-        works like cp -- it can be a folder, a new filename, or both.
-        MIME type is auto-detected from the file extension.
+        Uploads a file from your local machine with immutable versioning
+        enabled. The destination argument works like cp -- it can be a
+        folder, a new filename, or both. MIME type is auto-detected from
+        the file extension.
 
         Destination formats:
           (omitted)       Upload to current dir, keep original name
@@ -330,17 +340,78 @@ class UniqueShell(cmd.Cmd):
         destination = parts[1] if len(parts) > 1 else None
         self._print(cmd_upload(self.state, local_path, destination))
 
+    def do_versions(self, arg: str) -> None:
+        """List archived versions for a file.
+
+        Usage: versions <name|path|content_id> [--skip N] [--take N]
+
+        Lists immutable versions for a file identified by its Unique
+        path, name (matched in the current directory), or content ID
+        (cont_...). Use the VERSION_ID column with restore-version.
+
+        Examples:
+          /Reports> versions annual.pdf
+          /Reports> versions /Reports/Q1/annual.pdf
+          /Reports> versions cont_mno345 --take 10
+        """
+        parts = shlex.split(arg)
+        if not parts:
+            self._print("Usage: versions <name|path|content_id> [--skip N] [--take N]")
+            return
+
+        name_or_id = parts[0]
+        skip: int | None = None
+        take: int | None = None
+        i = 1
+        while i < len(parts):
+            if parts[i] == "--skip" and i + 1 < len(parts):
+                try:
+                    skip = int(parts[i + 1])
+                except ValueError:
+                    self._print(f"Invalid --skip: {parts[i + 1]}")
+                    return
+                i += 2
+            elif parts[i] == "--take" and i + 1 < len(parts):
+                try:
+                    take = int(parts[i + 1])
+                except ValueError:
+                    self._print(f"Invalid --take: {parts[i + 1]}")
+                    return
+                i += 2
+            else:
+                self._print(f"Unknown option: {parts[i]}")
+                return
+
+        self._print(cmd_versions(self.state, name_or_id, skip=skip, take=take))
+
+    def do_restore_version(self, arg: str) -> None:
+        """Restore a file from a content version ID.
+
+        Usage: restore-version <content_version_id>
+
+        The content version ID is shown by the versions command.
+
+        Example:
+          /Reports> restore-version cver_abc123
+          Restored: annual.pdf (cont_mno345) from version cver_abc123
+        """
+        content_version_id = arg.strip()
+        if not content_version_id:
+            self._print("Usage: restore-version <content_version_id>")
+            return
+        self._print(cmd_restore_version(self.state, content_version_id))
+
     def do_download(self, arg: str) -> None:
         """Download a file from the platform to your local machine.
 
-        Usage: download <name|content_id> [local_path]
+        Usage: download <name|path|content_id> [local_path]
 
-        Downloads a file identified by its name (matched in the current
-        directory) or content ID (cont_...). Saves to the specified local
-        path, or the current working directory if omitted.
+        Downloads a file identified by its Unique path, name (matched in
+        the current directory), or content ID (cont_...). Saves to the
+        specified local path, or the current working directory if omitted.
 
         Arguments:
-          name_or_id    File name or content ID (cont_...)
+          name_or_id    File path, file name, or content ID (cont_...)
           local_path    Optional local directory or file path
 
         Examples:
@@ -350,12 +421,15 @@ class UniqueShell(cmd.Cmd):
           /Reports> download annual.pdf ./downloads/
           Downloaded: annual.pdf -> ./downloads/annual.pdf
 
+          /Reports> download /Reports/Q1/annual.pdf ./downloads/
+          Downloaded: annual.pdf -> ./downloads/annual.pdf
+
           /Reports> download cont_mno345 ~/Desktop/
           Downloaded: cont_mno345 -> ~/Desktop/cont_mno345
         """
         parts = shlex.split(arg)
         if not parts:
-            self._print("Usage: download <name|content_id> [local_path]")
+            self._print("Usage: download <name|path|content_id> [local_path]")
             return
         name_or_id = parts[0]
         local_dest = parts[1] if len(parts) > 1 else None
@@ -364,17 +438,18 @@ class UniqueShell(cmd.Cmd):
     def do_cite(self, arg: str) -> None:
         """Declare page citations for a file.
 
-        Usage: cite <name|content_id> [--pages RANGE]
+        Usage: cite <name|path|content_id> [--pages RANGE]
 
         Examples:
           /Reports> cite report.pdf --pages 3,5,7
+          /Reports> cite /Reports/Q1/report.pdf --pages 3,5,7
           /Reports> cite cont_abc123 --pages 1-4
         """
         from unique_sdk.cli.commands.cite_file import cmd_cite_file
 
         parts = shlex.split(arg)
         if not parts:
-            self._print("Usage: cite <name|content_id> [--pages RANGE]")
+            self._print("Usage: cite <name|path|content_id> [--pages RANGE]")
             return
         pages: str | None = None
         positional: list[str] = []
@@ -391,7 +466,7 @@ class UniqueShell(cmd.Cmd):
                 positional.append(token)
                 index += 1
         if not positional:
-            self._print("Usage: cite <name|content_id> [--pages RANGE]")
+            self._print("Usage: cite <name|path|content_id> [--pages RANGE]")
             return
         self._print(cmd_cite_file(self.state, positional[0], pages))
 
@@ -420,28 +495,31 @@ class UniqueShell(cmd.Cmd):
     def do_rm(self, arg: str) -> None:
         """Delete a file.
 
-        Usage: rm <name|content_id>
+        Usage: rm <name|path|content_id>
 
-        Permanently deletes a file by its name (matched in the current
-        directory) or content ID.
+        Permanently deletes a file by its Unique path, name (matched in
+        the current directory), or content ID.
 
         Examples:
           /Reports> rm annual.pdf
           Deleted: annual.pdf (cont_mno345)
 
+          /Reports> rm /Reports/Q1/annual.pdf
+          Deleted: annual.pdf (cont_mno345)
+
           /Reports> rm cont_xyz789
           Deleted: cont_xyz789 (cont_xyz789)
         """
         name_or_id = arg.strip()
         if not name_or_id:
-            self._print("Usage: rm <name|content_id>")
+            self._print("Usage: rm <name|path|content_id>")
             return
         self._print(cmd_rm(self.state, name_or_id))
 
     def do_mv(self, arg: str) -> None:
         """Rename a file.
 
-        Usage: mv <old_name|content_id> <new_name>
+        Usage: mv <old_name|path|content_id> <new_name>
 
         Changes the file's display title. The content ID and location
         remain the same.
@@ -450,12 +528,15 @@ class UniqueShell(cmd.Cmd):
           /Reports> mv annual.pdf annual-2025.pdf
           Renamed: annual.pdf -> annual-2025.pdf
 
+          /Reports> mv /Reports/Q1/annual.pdf annual-2025.pdf
+          Renamed: annual.pdf -> annual-2025.pdf
+
           /Reports> mv cont_abc123 "New Title.pdf"
           Renamed: cont_abc123 -> New Title.pdf
         """
         parts = shlex.split(arg)
         if len(parts) != 2:
-            self._print("Usage: mv <old_name|content_id> <new_name>")
+            self._print("Usage: mv <old_name|path|content_id> <new_name>")
             return
         self._print(cmd_mv_file(self.state, parts[0], parts[1]))
 
@@ -1103,6 +1184,9 @@ class UniqueShell(cmd.Cmd):
         return False
 
     def default(self, line: str) -> None:
+        if line.startswith("restore-version"):
+            self.do_restore_version(line[len("restore-version") :].strip())
+            return
         self._print(
             f"Unknown command: {line.split()[0]}. Type 'help' for available commands."
         )

{unique_sdk-2026.26.0.dev8 → unique_sdk-2026.26.0.dev9}/unique_sdk/cli/skills/unique-cli-file-management/SKILL.md

@@ -3,7 +3,7 @@ name: unique-cli-file-management
 description: >-
   Manage files and folders on the Unique AI Platform using the unique-cli
   command-line tool. Use when the user asks to upload, download, delete,
-  rename, list, find, look for, or organize files and folders on Unique,
+  rename, list, find, restore versions, list versions, look for, or organize files and folders on Unique,
   or when working with scope IDs (scope_*) or content IDs (cont_*).
   IMPORTANT: When a user says they are "looking for a file" or wants to
   "find a file", they typically mean locating it within the Unique AI
@@ -50,11 +50,16 @@ unique-cli rmdir scope_abc123 -r
 # Rename a folder
 unique-cli mvdir Q1 "Q1-2025"
 
-# Upload a file (to current scope -- cd first or specify destination)
+# Upload a file with versioning enabled (to current scope -- cd first or specify destination)
 unique-cli upload ./report.pdf
 unique-cli upload ./report.pdf /Reports/Q1/
 unique-cli upload ./data.csv scope_abc123
 
+# List and restore file versions
+unique-cli versions /Reports/Q1/report.pdf
+unique-cli versions cont_abc123 --take 10
+unique-cli restore-version cver_abc123
+
 # Download a file
 unique-cli download report.pdf ./local/
 unique-cli download cont_abc123 ~/Desktop/
@@ -81,10 +86,11 @@ unique-cli mv report.pdf "Annual Report 2025.pdf"
 | `..` | `..` | Parent directory |
 | `/` | `/` | Root |
 | Content ID | `cont_abc123` | File directly by ID |
+| File path | `/Reports/Q1/report.pdf` | File in a folder |
 
 ## Upload Destination Resolution
 
-The `upload` destination works like Linux `cp`:
+The `upload` command always enables immutable content versioning. It does not expose an unversioned upload mode. Its destination works like Linux `cp`:
 
 | Destination | Behavior |
 |-------------|----------|
@@ -116,6 +122,18 @@ unique-cli download "annual.pdf" ./downloads/
 unique-cli download cont_abc123 ./downloads/
 ```
 
+### Restore a previous file version
+
+```bash
+# List versions for a file path, file name in the current folder, or content ID.
+unique-cli versions /Reports/Q1/annual.pdf
+unique-cli versions "annual.pdf"
+unique-cli versions cont_abc123 --take 20
+
+# Restore using the VERSION_ID shown by `versions`.
+unique-cli restore-version cver_abc123
+```
+
 ### Create folder hierarchy and upload
 
 ```bash

{unique_sdk-2026.26.0.dev8 → unique_sdk-2026.26.0.dev9}/unique_sdk/utils/file_io.py

@@ -106,6 +106,7 @@ def upload_file(
     ingestion_config: Content.IngestionConfig | None = None,
     metadata: dict[str, Any] | None = None,
     preview_pdf_path: str | None = None,
+    versioning_enabled: bool | None = None,
 ):
     """Upload *path_to_file* as a Unique :class:`Content`.
 
@@ -148,6 +149,9 @@ def upload_file(
             responsibility — there is no override kwarg, by design,
             so all callers land on the same ``${content.id}_pdfPreview``
             convention as the ingestion worker.
+        versioning_enabled: When ``True``, ask the platform to archive
+            previous blobs for the same content so they can be listed
+            and restored through the content version endpoints.
     """
     if not chat_id and not scope_or_unique_path:
         raise ValueError("chat_id or scope_or_unique_path must be provided")
@@ -177,6 +181,7 @@ def upload_file(
         },
         scopeId=scope_or_unique_path,
         chatId=chat_id,
+        versioningEnabled=versioning_enabled,
     )
 
     # Step 2 — PUT the original bytes to the SAS URL minted by Step 1.
@@ -229,6 +234,7 @@ def upload_file(
             },
             fileUrl=createdContent.readUrl,
             chatId=chat_id,
+            versioningEnabled=versioning_enabled,
             **preview_kwargs,
         )
     else:
@@ -246,6 +252,7 @@ def upload_file(
             },
             fileUrl=createdContent.readUrl,
             scopeId=scope_or_unique_path,
+            versioningEnabled=versioning_enabled,
             **preview_kwargs,
         )