unique-sdk 2026.44.0.dev13__tar.gz → 2026.44.0.dev15__tar.gz

{unique_sdk-2026.44.0.dev13 → unique_sdk-2026.44.0.dev15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.44.0.dev13
+Version: 2026.44.0.dev15
 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.44.0.dev13 → unique_sdk-2026.44.0.dev15}/pyproject.toml

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

{unique_sdk-2026.44.0.dev13 → unique_sdk-2026.44.0.dev15}/unique_sdk/__init__.py

@@ -34,6 +34,7 @@ from unique_sdk._error import APIConnectionError as APIConnectionError
 from unique_sdk._error import APIError as APIError
 from unique_sdk._error import AuthenticationError as AuthenticationError
 from unique_sdk._error import InvalidRequestError as InvalidRequestError
+from unique_sdk._error import RateLimitError as RateLimitError
 from unique_sdk._error import (
     SignatureVerificationError as SignatureVerificationError,
 )

{unique_sdk-2026.44.0.dev13 → unique_sdk-2026.44.0.dev15}/unique_sdk/_api_requestor.py

@@ -392,7 +392,15 @@ class APIRequestor(object):
         cause = error_data.get("cause", {})
         if isinstance(cause, str):
             cause = {"error": {"message": cause}, "status": rcode}
-        status = cause.get("status", rcode)
+
+        cause_error = cause.get("error") or {}
+        cause_code = cause_error.get("code")
+        cause_message = cause_error.get("message")
+
+        message = error_data.get("message") or cause_message
+        code = error_data.get("code") or cause_code
+        params = error_data.get("params") or cause_error.get("params")
+        status = rcode if error_data.get("code") else cause.get("status", rcode)
 
         _util.log_info(
             "Unique error received",
@@ -402,46 +410,63 @@ class APIRequestor(object):
             error_params=_util.redacted_error_params(error_data.get("params")),
         )
 
-        error = cause.get("error", {}) if cause else {}
-        error_code = error.get("code", "<Unknown code>")
-        error_message = error.get("message", "<No message>")
-        original_error = f"{error_code}: {error_message}"
+        original_error = None
+        if cause_code or cause_message:
+            original_error = (
+                f"{cause_code or '<Unknown code>'}: {cause_message or '<No message>'}"
+            )
 
-        if status in [400, 404]:
-            return _error.InvalidRequestError(
-                message=error_data.get("message"),
-                params=error_data.get("params"),
-                code=error_data.get("code"),
+        if status == 429:
+            return _error.RateLimitError(
+                message=message,
+                params=params,
+                code=code,
                 http_body=rbody,
                 http_status=rcode,
                 json_body=resp,
                 headers=rheaders,
                 original_error=original_error,
             )
-        elif status == 401:
-            return _error.AuthenticationError(
-                message=error_data.get("message"),
+        if status in [400, 404]:
+            return _error.InvalidRequestError(
+                message=message,
+                params=params,
+                code=code,
                 http_body=rbody,
-                http_status=status,
+                http_status=rcode,
                 json_body=resp,
                 headers=rheaders,
                 original_error=original_error,
             )
-        elif status == 403:
-            return _error.PermissionError(
-                message=error_data.get("message"),
+        if status == 401:
+            return _error.AuthenticationError(
+                message=message,
                 http_body=rbody,
                 http_status=status,
                 json_body=resp,
                 headers=rheaders,
+                code=code,
                 original_error=original_error,
+                params=params,
             )
-        else:
-            return _error.APIError(
-                message=error_data.get("message"),
+        if status == 403:
+            return _error.PermissionError(
+                message=message,
                 http_body=rbody,
                 http_status=status,
                 json_body=resp,
                 headers=rheaders,
+                code=code,
                 original_error=original_error,
+                params=params,
             )
+        return _error.APIError(
+            message=message,
+            http_body=rbody,
+            http_status=status,
+            json_body=resp,
+            headers=rheaders,
+            code=code,
+            original_error=original_error,
+            params=params,
+        )

{unique_sdk-2026.44.0.dev13 → unique_sdk-2026.44.0.dev15}/unique_sdk/_error.py

@@ -1,4 +1,4 @@
-from typing import cast
+from typing import Any, cast
 
 
 class UniqueError(Exception):
@@ -10,6 +10,7 @@ class UniqueError(Exception):
     code: str | None
     request_id: str | None
     original_error: Exception | str | None
+    params: dict[str, Any] | str | None
 
     def __init__(
         self,
@@ -20,6 +21,7 @@ class UniqueError(Exception):
         headers: dict[str, str] | None = None,
         code: str | None = None,
         original_error: Exception | str | None = None,
+        params: dict[str, Any] | str | None = None,
     ):
         super(UniqueError, self).__init__(message)
 
@@ -41,6 +43,7 @@ class UniqueError(Exception):
         self.code = code
         self.request_id = self.headers.get("request-id", None)
         self.original_error = original_error
+        self.params = params
 
     def __str__(self):
         msg = self._message or "<empty message>"
@@ -51,7 +54,7 @@ class UniqueError(Exception):
 
 class UniqueErrorWithParamsCode(UniqueError):
     # str included: InvalidRequestError callers pass plain strings (e.g. "id")
-    params: dict[str, str] | str | None
+    params: dict[str, Any] | str | None
 
     def __init__(
         self,
@@ -62,12 +65,18 @@ class UniqueErrorWithParamsCode(UniqueError):
         headers: dict[str, str] | None = None,
         code: str | None = None,
         original_error: Exception | str | None = None,
-        params: dict[str, str] | str | None = None,
+        params: dict[str, Any] | str | None = None,
     ):
         super().__init__(
-            message, http_body, http_status, json_body, headers, code, original_error
+            message,
+            http_body,
+            http_status,
+            json_body,
+            headers,
+            code,
+            original_error,
+            params,
         )
-        self.params = params
 
     def __repr__(self):
         return "%s(message=%r, params=%r, code=%r, http_status=%r, request_id=%r)" % (
@@ -112,6 +121,10 @@ class PermissionError(UniqueError):
     pass
 
 
+class RateLimitError(APIError):
+    pass
+
+
 class InvalidRequestError(UniqueErrorWithParamsCode):
     def __init__(
         self,

{unique_sdk-2026.44.0.dev13 → unique_sdk-2026.44.0.dev15}/unique_sdk/_util.py

@@ -333,6 +333,35 @@ class class_method_variant(object):
         return _wrapper
 
 
+def _should_retry_error(
+    error: UniqueError,
+    error_messages: list[str],
+    should_retry_5xx: bool,
+) -> bool:
+    status = error.http_status
+    if status is not None and 400 <= status < 500:
+        return False
+    if isinstance(error.params, Mapping) and error.params.get("retryable") is False:
+        return False
+    if should_retry_5xx and status is not None and 500 <= status < 600:
+        return True
+    return any(err_msg.lower() in str(error).lower() for err_msg in error_messages)
+
+
+def _log_retry(error: UniqueError, attempt: int, max_retries: int) -> None:
+    # str(error) can carry upstream provider text via original_error.
+    params = error.params if isinstance(error.params, Mapping) else {}
+    logger.warning(
+        "Retrying Unique API call, attempt %d of %d: "
+        "code=%s http_status=%s correlation_id=%s",
+        attempt + 1,
+        max_retries,
+        error.code,
+        error.http_status,
+        params.get("correlationId"),
+    )
+
+
 def retry_on_error(
     error_messages: list[str],
     max_retries: int = 3,
@@ -341,6 +370,13 @@ def retry_on_error(
     error_class=APIError,
     should_retry_5xx=False,
 ):
+    """Retry ``APIError`` and ``APIConnectionError``.
+
+    4xx responses and errors with ``params.retryable`` false are not retried.
+    After the last attempt ``error_class`` is raised with the last error as
+    its ``__cause__``.
+    """
+
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
         @wraps(func)
         async def async_wrapper(*args, **kwargs) -> Any:
@@ -350,25 +386,16 @@ def retry_on_error(
                     return await func(*args, **kwargs)
                 except (APIError, APIConnectionError) as e:
                     e = cast(UniqueError, e)
-                    logger.error(f"Retrying because of {e}")
-                    should_retry = any(
-                        err_msg.lower() in str(e).lower() for err_msg in error_messages
-                    )
-                    # Add 5xx check if `should_retry_5xx` is True
-                    has_valid_status = (
-                        hasattr(e, "http_status") and e.http_status is not None
-                    )
-                    if should_retry_5xx and has_valid_status:
-                        should_retry = should_retry or (
-                            500 <= int(cast(int, e.http_status)) < 600
-                        )
-
-                    if not should_retry:
-                        raise e  # Raise the error if no retry condition is met
+                    if not _should_retry_error(e, error_messages, should_retry_5xx):
+                        raise
 
                     attempts += 1
                     if attempts >= max_retries:
-                        raise error_class(f"Failed after {max_retries} attempts: {e}")
+                        raise error_class(
+                            f"Failed after {max_retries} attempts: {e}"
+                        ) from e
+
+                    _log_retry(e, attempts, max_retries)
 
                     # Calculate exponential backoff with some randomness (jitter)
                     delay = initial_delay * (backoff_factor ** (attempts - 1))
@@ -382,25 +409,16 @@ def retry_on_error(
                     return func(*args, **kwargs)
                 except (APIError, APIConnectionError) as e:
                     e = cast(UniqueError, e)
-                    logger.error(f"Retrying because of {e}")
-                    should_retry = any(
-                        err_msg.lower() in str(e).lower() for err_msg in error_messages
-                    )
-                    # Add 5xx check if `should_retry_5xx` is True
-                    has_valid_status = (
-                        hasattr(e, "http_status") and e.http_status is not None
-                    )
-                    if should_retry_5xx and has_valid_status:
-                        should_retry = should_retry or (
-                            500 <= int(cast(int, e.http_status)) < 600
-                        )
-
-                    if not should_retry:
-                        raise e  # Raise the error if no retry condition is met
+                    if not _should_retry_error(e, error_messages, should_retry_5xx):
+                        raise
 
                     attempts += 1
                     if attempts >= max_retries:
-                        raise error_class(f"Failed after {max_retries} attempts: {e}")
+                        raise error_class(
+                            f"Failed after {max_retries} attempts: {e}"
+                        ) from e
+
+                    _log_retry(e, attempts, max_retries)
 
                     # Calculate exponential backoff with some randomness (jitter)
                     delay = initial_delay * (backoff_factor ** (attempts - 1))

{unique_sdk-2026.44.0.dev13 → unique_sdk-2026.44.0.dev15}/unique_sdk/cli/cli.py

@@ -69,7 +69,13 @@ from unique_sdk.cli.commands.mcp import cmd_mcp
 from unique_sdk.cli.commands.mcp import (
     is_error_output as _is_mcp_error_output,
 )
-from unique_sdk.cli.commands.navigation import cmd_cd, cmd_ls, cmd_pwd
+from unique_sdk.cli.commands.navigation import (
+    LS_DEFAULT_LIMIT,
+    LS_MAX_LIMIT,
+    cmd_cd,
+    cmd_ls,
+    cmd_pwd,
+)
 from unique_sdk.cli.commands.navigation import (
     is_ls_error_output as _is_ls_error_output,
 )
@@ -309,13 +315,44 @@ def cd(ctx: click.Context, target: str) -> None:
 
 @main.command()
 @click.argument("target", required=False, default=None)
+@click.option(
+    "--limit",
+    "-l",
+    type=int,
+    default=LS_DEFAULT_LIMIT,
+    show_default=True,
+    help=f"Max folders and max files to show (1-{LS_MAX_LIMIT}).",
+)
+@click.option(
+    "--skip",
+    type=int,
+    default=0,
+    show_default=True,
+    help="Skip this many folders and files first (for paging).",
+)
+@click.option(
+    "--all",
+    "-a",
+    "all_items",
+    is_flag=True,
+    help=f"Show up to {LS_MAX_LIMIT} folders and {LS_MAX_LIMIT} files.",
+)
 @click.pass_context
-def ls(ctx: click.Context, target: str | None) -> None:
+def ls(
+    ctx: click.Context,
+    target: str | None,
+    limit: int,
+    skip: int,
+    all_items: bool,
+) -> None:
     """List folders and files in a directory.
 
     \b
     Without TARGET, lists the current directory. With TARGET, lists
     the specified folder (by name, absolute path, or scope ID).
+    Shows 50 folders and 50 files by default. When a folder holds more,
+    the output says "showing ... of N" and prints the command for the
+    rest: use --skip to page, --limit to show more, or --all.
 
     \b
     Output columns: TYPE  NAME  ID  SIZE  UPDATED
@@ -327,8 +364,12 @@ def ls(ctx: click.Context, target: str | None) -> None:
       unique-cli ls              List root folders
       unique-cli ls /Reports     List a specific path
       unique-cli ls scope_abc    List by scope ID
+      unique-cli ls /Reports --skip 50    Next page of a large folder
+      unique-cli ls /Reports --all        Up to 1000 folders and files
     """
-    output = cmd_ls(LazyState.get(ctx), target)
+    output = cmd_ls(
+        LazyState.get(ctx), target, skip=skip, limit=limit, all_items=all_items
+    )
     emit(output, is_error=_is_ls_error_output)
 
 

{unique_sdk-2026.44.0.dev13 → unique_sdk-2026.44.0.dev15}/unique_sdk/cli/commands/navigation.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import shlex
+from collections.abc import Callable, Mapping
 from typing import Any
 
 import unique_sdk
@@ -13,6 +15,11 @@ from unique_sdk.cli.metadata_filter import (
 from unique_sdk.cli.paths import canonical_folder_path, same_folder_path
 from unique_sdk.cli.state import ShellState
 
+# Server take is capped at 100 and defaults to 50; ls pages to reach --limit rows.
+LS_PAGE_SIZE = 100
+LS_DEFAULT_LIMIT = 50
+LS_MAX_LIMIT = 1000
+
 
 def cmd_pwd(state: ShellState) -> str:
     return state.cwd
@@ -87,8 +94,90 @@ def is_ls_error_output(output: str) -> bool:
     return output.startswith("ls:")
 
 
-def cmd_ls(state: ShellState, target: str | None = None) -> str:
-    """List folders and files at the given (or current) path."""
+def _fetch_window(
+    fetch_page: Callable[[int, int], Mapping[str, Any]],
+    rows_key: str,
+    skip: int,
+    limit: int,
+) -> tuple[list[Any], int]:
+    """Return up to *limit* rows starting at *skip*, and the API total."""
+    rows: list[Any] = []
+    total: int | None = None
+    offset = skip
+    while len(rows) < limit:
+        take = min(LS_PAGE_SIZE, limit - len(rows))
+        result = fetch_page(offset, take)
+        page = result.get(rows_key, [])
+        total = result.get("totalCount", total)
+        rows.extend(page)
+        offset += len(page)
+        if len(page) < take or (total is not None and offset >= total):
+            break
+    return rows, total if total is not None else skip + len(rows)
+
+
+def _window_note(
+    label: str,
+    skip: int,
+    limit: int,
+    shown: dict[str, int],
+    totals: dict[str, int],
+    hidden_files: int = 0,
+) -> str:
+    """Say which rows this call read and how to list the rest; empty when complete.
+
+    ``shown`` counts rows read from the server. ``hidden_files`` of them were
+    dropped by the task scope and are not printed, so the wording says "read".
+    """
+    parts: list[str] = []
+    for kind in ("folders", "files"):
+        total = totals[kind]
+        count = shown[kind]
+        if total == 0 or (skip == 0 and count >= total):
+            continue
+        if count == 0:
+            parts.append(f"no {kind} after {skip} (of {total})")
+        else:
+            parts.append(f"{kind} {skip + 1}-{skip + count} of {total}")
+    if not parts:
+        return ""
+    verb = "read" if hidden_files else "showing"
+    note = f"\n{verb} " + ", ".join(parts)
+    if hidden_files:
+        note += f" ({hidden_files} file(s) hidden by task scope)"
+    if any(skip + shown[kind] < totals[kind] for kind in shown):
+        quoted = shlex.quote(label)
+        limit_arg = "" if limit == LS_DEFAULT_LIMIT else f" --limit {limit}"
+        note += f"\nmore: unique-cli ls {quoted} --skip {skip + limit}{limit_arg}"
+        # --all restarts at row 0, so it only helps when it would show more
+        # than this window already does; at the cap it would repeat rows.
+        if skip == 0 and limit < LS_MAX_LIMIT:
+            note += f" (or: unique-cli ls {quoted} --all)"
+    return note
+
+
+def cmd_ls(
+    state: ShellState,
+    target: str | None = None,
+    *,
+    skip: int = 0,
+    limit: int = LS_DEFAULT_LIMIT,
+    all_items: bool = False,
+) -> str:
+    """List folders and files at the given (or current) path.
+
+    Shows up to *limit* folders and *limit* files starting at *skip*
+    (``all_items`` raises *limit* to ``LS_MAX_LIMIT``). When more exist, the
+    output says which rows are shown and ends with the ``ls`` call for the rest.
+    """
+    if all_items and limit != LS_DEFAULT_LIMIT:
+        return "ls: --all and --limit cannot be combined"
+    if all_items:
+        limit = LS_MAX_LIMIT
+    if skip < 0:
+        return "ls: --skip must be 0 or more"
+    if not 1 <= limit <= LS_MAX_LIMIT:
+        return f"ls: --limit must be between 1 and {LS_MAX_LIMIT}"
     try:
         if target is not None:
             resolved_path, scope_id = state.resolve_path(target)
@@ -108,6 +197,16 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
                 f"({state.scope_denial_hint()})."
             )
 
+        # The scoped root lists a fixed set of folders; there is nothing to page.
+        if (
+            scope_id is None
+            and skip
+            and (
+                state.workspace_metadata_filter is not None or state.workspace_scope_ids
+            )
+        ):
+            return "ls: paging is not supported at the scoped root"
+
         # At root with a per-message KB scope (e.g. an Agentic Table column's
         # scope_rules), show only the in-scope folders and explicitly-scoped
         # documents so the agent explores within the boundary rather than the
@@ -194,27 +293,36 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
         if scope_id:
             folder_params["parentId"] = scope_id
 
-        folder_result = unique_sdk.Folder.get_infos(
-            user_id=state.config.user_id,
-            company_id=state.config.company_id,
-            **folder_params,
+        folders, total_folders = _fetch_window(
+            lambda offset, take: unique_sdk.Folder.get_infos(
+                user_id=state.config.user_id,
+                company_id=state.config.company_id,
+                skip=offset,
+                take=take,
+                **folder_params,
+            ),
+            "folderInfos",
+            skip,
+            limit,
         )
-        folders = folder_result.get("folderInfos", [])
-        total_folders = folder_result.get("totalCount", len(folders))
-
         # Every file lives in a folder, so the root has no files of its own.
         files: list[Any] = []
         total_files = 0
         if scope_id:
-            content_result = unique_sdk.Content.get_infos(
-                user_id=state.config.user_id,
-                company_id=state.config.company_id,
-                metadataFilter=direct_children_filter(scope_id),
+            files, total_files = _fetch_window(
+                lambda offset, take: unique_sdk.Content.get_infos(
+                    user_id=state.config.user_id,
+                    company_id=state.config.company_id,
+                    metadataFilter=direct_children_filter(scope_id),
+                    skip=offset,
+                    take=take,
+                ),
+                "contentInfos",
+                skip,
+                limit,
             )
-            files = content_result.get("contentInfos", [])
-            total_files = content_result.get("totalCount", len(files))
 
-        if scope_id and not folders and not files:
+        if scope_id and not folders and not files and skip == 0:
             label = target if target is not None else resolved_path
             counts_error = _counts_without_rows_error(
                 label,
@@ -229,25 +337,36 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
         # allowlist): read/cite would deny them, so ls must hide them too.
         # Folder-only filters keep every file (each passes the folderIdPath
         # leaf); the verdict is cached per content id. See UN-21780.
+        # The paging note counts rows read from the server, before the scope filter.
+        scanned_files = len(files)
         if state.workspace_metadata_filter is not None:
             files = [
                 f for f in files if state.is_content_within_workspace(f.get("id", ""))
             ]
+        note = _window_note(
+            target if target is not None else resolved_path,
+            skip,
+            limit,
+            {"folders": len(folders), "files": scanned_files},
+            {"folders": total_folders, "files": total_files},
+            hidden_files=scanned_files - len(files),
+        )
+
+        output = format_ls(folders, files)
+        if state.workspace_metadata_filter is not None:
             # ``files`` is only the current API page, so the in-scope count is
             # per-page, not the folder total. Report it as the shown-in-scope
             # count and keep the API ``totalCount`` as the folder's real size,
             # rather than overwriting total_files with the page length (which
             # would silently undercount paginated folders). See UN-21780.
-            output = format_ls(folders, files)
             summary = (
                 f"\n{total_folders} folder(s), {len(files)} file(s) in task scope "
                 f"(of {total_files} in folder)"
             )
-            return output + summary
+            return output + summary + note
 
-        output = format_ls(folders, files)
         summary = f"\n{total_folders} folder(s), {total_files} file(s)"
-        return output + summary
+        return output + summary + note
 
     except (ValueError, unique_sdk.UniqueError) as e:
         return f"ls: {e}"

{unique_sdk-2026.44.0.dev13 → unique_sdk-2026.44.0.dev15}/unique_sdk/cli/shell.py

@@ -27,7 +27,12 @@ from unique_sdk.cli.commands.files import (
 )
 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
+from unique_sdk.cli.commands.navigation import (
+    LS_DEFAULT_LIMIT,
+    cmd_cd,
+    cmd_ls,
+    cmd_pwd,
+)
 from unique_sdk.cli.commands.scheduled_tasks import (
     cmd_schedule_create,
     cmd_schedule_delete,
@@ -217,10 +222,12 @@ class UniqueShell(cmd.Cmd):
     def do_ls(self, arg: str) -> None:
         """List folders and files in a directory.
 
-        Usage: ls [target]
+        Usage: ls [target] [--limit N] [--skip N] [--all]
 
         Without arguments, lists the current directory. With an argument,
         lists the specified folder (by name, path, or scope ID).
+        Shows 50 folders and 50 files by default; when a folder holds more,
+        the output says so and prints the command for the rest.
 
         Output columns: TYPE  NAME  ID  SIZE  UPDATED
 
@@ -233,8 +240,51 @@ class UniqueShell(cmd.Cmd):
           /> ls /Reports/Q1
           /> ls scope_abc123
         """
-        target = arg.strip() or None
-        self._print(cmd_ls(self.state, target))
+        try:
+            parts = shlex.split(arg)
+        except ValueError as e:
+            self._print(f"ls: {e}")
+            return
+        target: str | None = None
+        skip = 0
+        limit = LS_DEFAULT_LIMIT
+        all_items = False
+        # Accept --limit=20 / --skip=50 like the one-shot CLI does.
+        expanded: list[str] = []
+        for part in parts:
+            name, sep, value = part.partition("=")
+            if sep and name in ("--limit", "--skip"):
+                expanded.extend([name, value])
+            else:
+                expanded.append(part)
+        it = iter(expanded)
+        for part in it:
+            if part in ("--all", "-a"):
+                all_items = True
+            elif part in ("--limit", "-l", "--skip"):
+                value = next(it, None)
+                try:
+                    number = int(value) if value is not None else None
+                except ValueError:
+                    number = None
+                if number is None:
+                    self._print(f"ls: {part} needs a whole number")
+                    return
+                if part == "--skip":
+                    skip = number
+                else:
+                    limit = number
+            elif part.startswith("-") and len(part) > 1:
+                self._print(f"ls: unknown option {part}")
+                return
+            elif target is None:
+                target = part
+            else:
+                self._print("ls: expected at most one target")
+                return
+        self._print(
+            cmd_ls(self.state, target, skip=skip, limit=limit, all_items=all_items)
+        )
 
     # -- Folder operations --
 

{unique_sdk-2026.44.0.dev13 → unique_sdk-2026.44.0.dev15}/unique_sdk/cli/skills/unique-cli-file-management/SKILL.md

@@ -42,6 +42,11 @@ unique-cli ls /Reports/Q1
 # List by scope ID
 unique-cli ls scope_abc123
 
+# Large folder: ls shows 50 folders and 50 files by default. When it prints
+# "showing files 1-50 of N", run the "more:" command it gives you
+unique-cli ls /Reports/Q1 --skip 50      # next page
+unique-cli ls /Reports/Q1 --all          # up to 1000 folders and 1000 files
+
 # Create a folder
 unique-cli mkdir Q2
 

{unique_sdk-2026.44.0.dev13 → unique_sdk-2026.44.0.dev15}/unique_sdk/cli/skills/unique-cli-search/SKILL.md

@@ -12,7 +12,8 @@ description: >-
   (.xlsx/.xls), CSV (.csv), and image files are NOT full-text indexed,
   so they will not appear in search results. To locate these file types,
   use the unique-cli-file-management skill instead (browse folders with
-  `unique-cli ls` to find them by name).
+  `unique-cli ls` to find them by name; `ls` shows 50 files at a time, so
+  follow its "more:" line or use `--all` for larger folders).
 ---
 
 # Unique CLI -- Knowledge Base Search & Document Read
@@ -32,7 +33,7 @@ Use `read` after a `ls` or `search` surfaces a content ID and you need to go dee
 
 Search the Unique knowledge base using combined vector + full-text search via the `unique-cli search` command. Every invocation wraps each result in a `<sourceN>...</sourceN>` block and records a per-turn citation manifest at `.unique/kb-search-refs.jsonl`, so any fact you cite as `[sourceN]` is rendered with a footnote and a clickable reference chip in the chat UI.
 
-> **Limitation:** Excel (`.xlsx`/`.xls`), CSV (`.csv`), and image files are **not** full-text indexed. They will not appear in search results. To find these files, use the `unique-cli-file-management` skill and browse folders with `unique-cli ls` to locate them by name.
+> **Limitation:** Excel (`.xlsx`/`.xls`), CSV (`.csv`), and image files are **not** full-text indexed. They will not appear in search results. To find these files, use the `unique-cli-file-management` skill and browse folders with `unique-cli ls` to locate them by name (`ls` shows 50 files at a time; follow its "more:" line or use `--all` for larger folders).
 
 
 ## Basic Search