contree-cli 0.4.5__tar.gz → 0.5.1__tar.gz

{contree_cli-0.4.5 → contree_cli-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: contree-cli
-Version: 0.4.5
+Version: 0.5.1
 Summary: CLI client for the ConTree sandbox platform
 Keywords: sandbox,cli,vm,ai-agent,contree
 Author: Dmitry Orlov
@@ -279,9 +279,9 @@ contree --help
 contree auth
 ```
 
-You'll be prompted to enter your API token and project ID. The CLI verifies the token and saves credentials to `~/.config/contree-cli/config.ini`.
+You'll be prompted to enter your API token and project ID. The CLI verifies the token and saves credentials to `~/.config/contree/auth.ini` (override the data directory via `CONTREE_HOME`).
 
-If `NEBIUS_API_KEY` and `NEBIUS_AI_PROJECT` environment variables are set and no CLI flags are passed, they are picked up automatically instead of prompting.
+If `--token`/`--url`/`--project` flags are omitted, `contree auth` reads `CONTREE_TOKEN` (or `NEBIUS_API_KEY`), `CONTREE_URL`, and `CONTREE_PROJECT` (or `NEBIUS_AI_PROJECT`) from the environment instead of prompting. These variables are read only during registration; runtime commands use the saved profile only.
 
 ### 2. Install agent skills (optional)
 
@@ -492,17 +492,24 @@ contree auth switch staging           # switch active profile
 
 ### Environment variables
 
+Read at runtime (any command):
+
 | Variable | Purpose |
 |---|---|
-| `CONTREE_HOME` | Data directory (default `~/.config/contree-cli`) |
-| `CONTREE_TOKEN` | API bearer token (overrides config) |
-| `CONTREE_URL` | API base URL (overrides config) |
-| `CONTREE_PROJECT` | Project ID (overrides config) |
-| `CONTREE_PROFILE` | Active profile name |
+| `CONTREE_HOME` | Data directory (default `$XDG_CONFIG_HOME/contree`, or `~/.config/contree`) |
+| `CONTREE_PROFILE` | Active profile name (selects which profile commands use) |
 | `CONTREE_SESSION` | Explicit session key (for multi-terminal workflows) |
 | `CONTREE_SESSION_DB` | Path to session SQLite database |
 
-Environment variables take precedence over the config file. `--token` and `--url` flags override everything.
+Read only by `contree auth` (registration-time fallbacks for omitted flags):
+
+| Variable | Used for |
+|---|---|
+| `CONTREE_TOKEN` / `NEBIUS_API_KEY` | `--token` |
+| `CONTREE_URL` | `--url` |
+| `CONTREE_PROJECT` / `NEBIUS_AI_PROJECT` | `--project` |
+
+Credentials come strictly from the saved profile at runtime. `--token`, `--url`, `--project` CLI flags override profile fields for a single invocation.
 
 ## Zero Dependencies
 

{contree_cli-0.4.5 → contree_cli-0.5.1}/README.md

@@ -72,9 +72,9 @@ contree --help
 contree auth
 ```
 
-You'll be prompted to enter your API token and project ID. The CLI verifies the token and saves credentials to `~/.config/contree-cli/config.ini`.
+You'll be prompted to enter your API token and project ID. The CLI verifies the token and saves credentials to `~/.config/contree/auth.ini` (override the data directory via `CONTREE_HOME`).
 
-If `NEBIUS_API_KEY` and `NEBIUS_AI_PROJECT` environment variables are set and no CLI flags are passed, they are picked up automatically instead of prompting.
+If `--token`/`--url`/`--project` flags are omitted, `contree auth` reads `CONTREE_TOKEN` (or `NEBIUS_API_KEY`), `CONTREE_URL`, and `CONTREE_PROJECT` (or `NEBIUS_AI_PROJECT`) from the environment instead of prompting. These variables are read only during registration; runtime commands use the saved profile only.
 
 ### 2. Install agent skills (optional)
 
@@ -285,17 +285,24 @@ contree auth switch staging           # switch active profile
 
 ### Environment variables
 
+Read at runtime (any command):
+
 | Variable | Purpose |
 |---|---|
-| `CONTREE_HOME` | Data directory (default `~/.config/contree-cli`) |
-| `CONTREE_TOKEN` | API bearer token (overrides config) |
-| `CONTREE_URL` | API base URL (overrides config) |
-| `CONTREE_PROJECT` | Project ID (overrides config) |
-| `CONTREE_PROFILE` | Active profile name |
+| `CONTREE_HOME` | Data directory (default `$XDG_CONFIG_HOME/contree`, or `~/.config/contree`) |
+| `CONTREE_PROFILE` | Active profile name (selects which profile commands use) |
 | `CONTREE_SESSION` | Explicit session key (for multi-terminal workflows) |
 | `CONTREE_SESSION_DB` | Path to session SQLite database |
 
-Environment variables take precedence over the config file. `--token` and `--url` flags override everything.
+Read only by `contree auth` (registration-time fallbacks for omitted flags):
+
+| Variable | Used for |
+|---|---|
+| `CONTREE_TOKEN` / `NEBIUS_API_KEY` | `--token` |
+| `CONTREE_URL` | `--url` |
+| `CONTREE_PROJECT` / `NEBIUS_AI_PROJECT` | `--project` |
+
+Credentials come strictly from the saved profile at runtime. `--token`, `--url`, `--project` CLI flags override profile fields for a single invocation.
 
 ## Zero Dependencies
 

{contree_cli-0.4.5 → contree_cli-0.5.1}/contree_cli/__main__.py

@@ -2,16 +2,18 @@ import contextvars
 import logging
 import sys
 from collections.abc import Callable
+from contextlib import suppress
 from dataclasses import replace
 
 import contree_cli.config as config_mod
 from contree_cli import CLIENT, FORMATTER, PROFILE, SESSION_STORE, ArgumentsProtocol
 from contree_cli.arguments import parser
 from contree_cli.client import ApiError, client_from_profile
-from contree_cli.config import Config
+from contree_cli.config import SETTINGS, Config
 from contree_cli.log import setup_logging
 from contree_cli.output import FORMATTERS
 from contree_cli.session import SessionStore, get_session_key
+from contree_cli.update_check import UpdateChecker
 
 log = logging.getLogger(__name__)
 
@@ -21,9 +23,27 @@ def main() -> None:
         parser.print_help()
         exit(0)
 
+    if SETTINGS.has_section("cli"):
+        parser.set_defaults(**SETTINGS["cli"])
+
     args = parser.parse_args()
     setup_logging(level=getattr(logging, args.log_level.upper(), logging.INFO))
 
+    # Update check runs only after argparse so it skips --help / --version
+    # / no-command paths and so the warning respects --log-level. refresh()
+    # is best-effort; check() is a pure predicate.
+    checker = UpdateChecker()
+    with suppress(Exception):
+        checker.refresh()
+    if not checker.is_latest():
+        log.warning(
+            "A new version of contree-cli is available: %s (installed: %s)."
+            " Upgrade with `uv tool install -U contree-cli` or"
+            " `pip install -U contree-cli`.",
+            checker.state.latest_version,
+            checker.current_version,
+        )
+
     config_mod.CONFIG_FILE = args.config_path
     config_mod.CONFIG_DIR = args.config_path.parent
 
@@ -38,14 +58,19 @@ def main() -> None:
     if args.project:
         profile = replace(profile, project=args.project)
 
-    # auth creates its own client and can work with nonexistent profiles
-    if args.command not in ("auth",):
-        if profile.name not in cfg:
-            log.error(
-                "Profile %r does not exist. Run `contree auth` first.",
-                profile.name,
-            )
-            exit(1)
+    # Local-only commands don't need a client or a configured profile:
+    # auth bootstraps its own; agent/man/skill operate purely on local files.
+    LOCAL_COMMANDS = ("auth", "agent", "man", "skill")
+    needs_client = args.command not in LOCAL_COMMANDS
+
+    if needs_client and profile.name not in cfg:
+        log.error(
+            "Profile %r does not exist. Run `contree auth` first.",
+            profile.name,
+        )
+        exit(1)
+
+    if needs_client:
         try:
             client = client_from_profile(profile)
         except ValueError as exc:
@@ -57,6 +82,7 @@ def main() -> None:
 
     session_key = get_session_key(profile.name, override=args.session_key)
     db_path = profile.session_db_path
+    log.debug("Running in session: %s", session_key)
 
     with SessionStore(db_path, session_key) as store:
         PROFILE.set(profile)

{contree_cli-0.4.5 → contree_cli-0.5.1}/contree_cli/agent.md

@@ -328,18 +328,23 @@ Per-command -p is useful for cross-project operations:
   contree -p project-a images --prefix=base
   contree -p project-b images import tag:base:latest
 
-Data directory: ~/.config/contree-cli/
-  config.ini              profile credentials
-  sessions-{profile}.db   per-profile sessions, history, cache
-  skills.db               installed agent skill registry
+Data directory: $XDG_CONFIG_HOME/contree/ (or ~/.config/contree/)
+  auth.ini                       profile credentials (mode 0600)
+  cli.ini                        optional CLI defaults
+  cli/sessions/{profile}.db      per-profile sessions, history, cache
+  cli/skills.db                  installed agent skill registry
+  cli/version_check.json         cached PyPI update-check state
 
 Environment variables:
   CONTREE_HOME       data directory override
-  CONTREE_TOKEN      API token (overrides config)
-  CONTREE_URL        API URL (overrides config)
-  CONTREE_PROFILE    active profile (overrides config)
+  CONTREE_PROFILE    active profile (selects which profile commands use)
   CONTREE_SESSION    explicit session key
 
+Read only by `contree auth` (registration-time fallbacks):
+  CONTREE_TOKEN / NEBIUS_API_KEY        token when --token is omitted
+  CONTREE_URL                           URL when --url is omitted
+  CONTREE_PROJECT / NEBIUS_AI_PROJECT   project ID when --project is omitted
+
 More: contree auth --help
 
 All commands

{contree_cli-0.4.5 → contree_cli-0.5.1}/contree_cli/arguments.py

@@ -71,20 +71,19 @@ mutating commands (change remote or local session state):
   contree use IMAGE | run -- CMD | file edit PATH | file cp SRC DEST
   contree tag UUID TAG | kill UUID | cd PATH | session checkout BRANCH
 
-environment variables (advanced overrides; most users can ignore):
-  CONTREE_TOKEN      API bearer token (overrides config file)
-  CONTREE_URL        API base URL (overrides config file)
-  CONTREE_PROJECT    Project ID for IAM auth (overrides config file)
-  CONTREE_PROFILE    Active config profile (overrides config file)
-  CONTREE_SESSION    Explicit session name (for multi-terminal workflows).
-                    If unset, contree auto-generates <cwd>+<8hex> (derived from
-                    profile+ppid+tty); export your own for stable reuse.
-                    You can also pass -S/--session instead of exporting env.
-  CONTREE_SESSION_DB Path to session SQLite database
-
-nebius shortcuts (used by `contree auth` as fallback when flags are omitted):
-  NEBIUS_API_KEY     Fallback token for auth registration
-  NEBIUS_AI_PROJECT  Fallback project ID for IAM auth registration
+environment variables:
+  CONTREE_PROFILE          Active config profile (selects which profile to use)
+  CONTREE_SESSION          Explicit session name (for multi-terminal workflows).
+                           If unset, contree auto-generates <cwd>+<8hex> (derived
+                           from profile+ppid+tty); export your own for stable
+                           reuse. You can also pass -S/--session instead.
+  CONTREE_SESSION_DB       Path to session SQLite database
+  CONTREE_NO_UPDATE_CHECK  Set to any value to disable PyPI update checks
+
+registration-time fallbacks (only read by `contree auth`, not at runtime):
+  CONTREE_TOKEN / NEBIUS_API_KEY        Token used when --token is omitted
+  CONTREE_URL                           URL used when --url is omitted
+  CONTREE_PROJECT / NEBIUS_AI_PROJECT   Project ID used when --project is omitted
 """
 
 DESCRIPTION = """\
@@ -95,7 +94,7 @@ through the ConTree REST API.
 
 Authentication:
   Bearer token + project ID. Default API URL:
-    https://api.studio.nebius.com/sandboxes/
+    https://api.tokenfactory.nebius.com/sandboxes/
 
   Use `contree auth --help` to configure persistent credentials.
 
@@ -121,7 +120,7 @@ parser.add_argument(
 parser.add_argument(
     *FLAGS["token"],
     default=None,
-    help="API token (overrides config and env)",
+    help="API token (overrides profile for this invocation)",
 )
 
 
@@ -133,12 +132,12 @@ parser.add_argument(
     *FLAGS["url"],
     default=None,
     type=_strip_trailing_slashes,
-    help="API base URL (overrides config and env)",
+    help="API base URL (overrides profile for this invocation)",
 )
 parser.add_argument(
     *FLAGS["project"],
     default=None,
-    help="Project ID (overrides config and env)",
+    help="Project ID (overrides profile for this invocation)",
 )
 parser.add_argument(
     *FLAGS["config"],

{contree_cli-0.4.5 → contree_cli-0.5.1}/contree_cli/cli/auth.py

@@ -8,9 +8,13 @@ Supports two auth types:
   iam (default) — bearer token + project ID, default URL provided
   jwt (legacy)  — bearer token only, URL must be specified
 
-Nebius environment variable shortcuts:
-  NEBIUS_API_KEY     used as token fallback during registration
-  NEBIUS_AI_PROJECT  used as project fallback during IAM registration
+Environment variable fallbacks during registration:
+  CONTREE_TOKEN / NEBIUS_API_KEY     used when --token is omitted
+  CONTREE_URL                        used when --url is omitted
+  CONTREE_PROJECT / NEBIUS_AI_PROJECT used when --project is omitted (IAM)
+
+Other commands ignore these variables; only ``contree auth`` reads
+them. ``CONTREE_PROFILE`` selects the profile for any command.
 
 Subcommands:
   profiles    List saved profiles (* marks active)
@@ -22,6 +26,7 @@ from __future__ import annotations
 import argparse
 import getpass
 import hashlib
+import json
 import logging
 import os
 from dataclasses import dataclass
@@ -35,6 +40,7 @@ from contree_cli.types import FLAGS
 logger = logging.getLogger(__name__)
 PROFILE_CHECK_TIMEOUT = 2.0
 PROFILE_CHECK_CONCURRENCY = 4
+REQUIRED_PERMISSION = "list"
 
 EPILOG = """\
 for coding agents:
@@ -169,6 +175,24 @@ def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
     return cmd_auth, AuthArgs
 
 
+def env_fallback(names: tuple[str, ...], *, what: str) -> str | None:
+    for name in names:
+        value = os.environ.get(name)
+        if value:
+            logger.info("Using %s from %s", what, name)
+            return value
+    return None
+
+
+def check_permission(payload: object, permission: str) -> bool:
+    if not isinstance(payload, dict):
+        return False
+    perms = payload.get("permissions")
+    if not isinstance(perms, dict):
+        return False
+    return bool(perms.get(permission))
+
+
 def cmd_auth(args: AuthArgs) -> int | None:
     cfg = Config()
     exists = args.profile in cfg
@@ -188,18 +212,16 @@ def cmd_auth(args: AuthArgs) -> int | None:
             print("Aborted.")
             return 1
 
-    # Token: --token > NEBIUS_API_KEY > interactive prompt
-    token = args.token
+    # Token: --token > CONTREE_TOKEN > NEBIUS_API_KEY > interactive prompt
+    token = args.token or env_fallback(
+        ("CONTREE_TOKEN", "NEBIUS_API_KEY"),
+        what="token",
+    )
     if token is None:
-        nebius_key = os.environ.get("NEBIUS_API_KEY")
-        if nebius_key:
-            logger.info("Using token from NEBIUS_API_KEY")
-            token = nebius_key
-        else:
-            token = getpass.getpass("Token: ")
+        token = getpass.getpass("Token: ")
 
-    # URL: --url > type-specific default > interactive prompt
-    url = args.url
+    # URL: --url > CONTREE_URL > type-specific default > interactive prompt
+    url = args.url or env_fallback(("CONTREE_URL",), what="URL")
     if url is None:
         if args.auth_type == AuthType.IAM:
             url = Config.DEFAULT_IAM_URL
@@ -209,17 +231,15 @@ def cmd_auth(args: AuthArgs) -> int | None:
                 logger.error("URL is required for JWT auth")
                 return 1
 
-    # Project (IAM only): --project > NEBIUS_AI_PROJECT > interactive prompt
+    # Project (IAM only): --project > CONTREE_PROJECT > NEBIUS_AI_PROJECT > prompt
     project: str | None = None
     if args.auth_type == AuthType.IAM:
-        project = args.project
+        project = args.project or env_fallback(
+            ("CONTREE_PROJECT", "NEBIUS_AI_PROJECT"),
+            what="project",
+        )
         if project is None:
-            nebius_project = os.environ.get("NEBIUS_AI_PROJECT")
-            if nebius_project:
-                logger.info("Using project from NEBIUS_AI_PROJECT")
-                project = nebius_project
-            else:
-                project = input("Project ID: ").strip()
+            project = input("Project ID: ").strip()
     profile = ConfigProfile(
         name=args.profile,
         token=token,
@@ -235,15 +255,33 @@ def cmd_auth(args: AuthArgs) -> int | None:
         return 1
 
     try:
-        client.get("/v1/whoami")
+        resp = client.get("/v1/whoami")
+        whoami = json.loads(resp.read() or b"{}")
     except ApiError as exc:
         # Logs the API error message, not the token itself.
         # nosemgrep: python-logger-credential-disclosure
         logger.error("Token verification failed: %s. Profile not changed.", exc)
         return 1
+    except ValueError as exc:
+        logger.error("Could not parse /v1/whoami response: %s", exc)
+        return 1
+
+    if not check_permission(whoami, REQUIRED_PERMISSION):
+        project_label = profile.project or profile.url
+        logger.warning(
+            "Warning: token is valid but sandboxes are disabled on %s"
+            " (no %r permission). The profile will be saved but no commands"
+            " will work until the service is enabled.",
+            project_label,
+            REQUIRED_PERMISSION,
+        )
 
     cfg[args.profile] = profile
-    logger.info("Token verified and saved to profile %r", args.profile)
+    logger.info(
+        "auth accepted, profile %r saved to -> %s",
+        args.profile,
+        cfg.path,
+    )
     return None
 
 
@@ -284,11 +322,17 @@ def cmd_list(args: ProfilesArgs) -> None:
 
         try:
             resp = client.get("/v1/whoami")
-            resp.read()
+            payload = resp.read()
         except TimeoutError:
             return profile, "timeout"
         except Exception:
             return profile, "error"
+        try:
+            whoami = json.loads(payload or b"{}")
+        except ValueError:
+            return profile, "error"
+        if not check_permission(whoami, REQUIRED_PERMISSION):
+            return profile, "inactive"
         return profile, "ok"
 
     formatter = FORMATTER.get()

{contree_cli-0.4.5 → contree_cli-0.5.1}/contree_cli/cli/file.py

@@ -19,7 +19,6 @@ import argparse
 import hashlib
 import json
 import logging
-import os
 import shlex
 import subprocess
 import tempfile
@@ -28,6 +27,7 @@ from pathlib import Path
 
 from contree_cli import CLIENT, SESSION_STORE, ArgumentsProtocol, SetupResult
 from contree_cli.client import ApiError, ContreeClient, resolve_image, stream_response
+from contree_cli.config import EDITOR
 from contree_cli.session import SessionStore
 from contree_cli.types import FLAGS
 
@@ -79,7 +79,8 @@ def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
     )
     edit_p.add_argument(
         *FLAGS["editor"],
-        help="Editor command (default: $EDITOR or vi)",
+        default=EDITOR,
+        help=f"Editor command (default: {EDITOR})",
     )
     edit_p.add_argument("path", help="Path inside image")
     edit_p.set_defaults(handler=cmd_file_edit, load_args=FileEditArgs)
@@ -128,14 +129,14 @@ def _upload_and_record(
     except ApiError as exc:
         if exc.status != 404:
             raise
-        data = local_path.read_bytes()
-        resp = client.request(
-            "POST",
-            "/v1/files",
-            body=data,
-            headers={"Content-Type": "application/octet-stream"},
-        )
-        file_uuid = json.loads(resp.read())["uuid"]
+        with open(local_path, "rb") as fh:
+            resp = client.request(
+                "POST",
+                "/v1/files",
+                body=fh,
+                headers={"Content-Type": "application/octet-stream"},
+            )
+            file_uuid = json.loads(resp.read())["uuid"]
         logger.info("Uploaded %s (%s)", instance_path, file_uuid)
 
     history_id = store.set_image(
@@ -178,14 +179,13 @@ def cmd_file_edit(args: FileEditArgs) -> int | None:
 
     # 2. Record original hash, open editor
     original_hash = _file_sha256(tmp_file)
-    editor = args.editor or os.environ.get("EDITOR", "vi")
-    logger.info("Opening %s in %s", tmp_file, editor)
+    logger.info("Opening %s in %s", tmp_file, args.editor)
     # $EDITOR may contain shell expressions (env vars, tilde, pipes),
     # e.g. "TERM=xterm vim" or "~/bin/editor". shlex.split would not
-    # expand those — shell=True is required. The file path is quoted
+    # expand those, shell=True is required. The file path is quoted
     # via shlex.quote to prevent injection from the filename.
     # nosemgrep: subprocess-shell-true
-    rc = subprocess.call(f"{editor} {shlex.quote(str(tmp_file))}", shell=True)
+    rc = subprocess.call(f"{args.editor} {shlex.quote(str(tmp_file))}", shell=True)
     if rc != 0:
         logger.error("Editor exited with code %d", rc)
         return 1

{contree_cli-0.4.5 → contree_cli-0.5.1}/contree_cli/cli/images.py

@@ -25,11 +25,13 @@ from contree_cli.types import (
     isoformat_datetime,
     parse_datetime,
     parse_interval,
+    positive_int,
 )
 
 logger = logging.getLogger(__name__)
 
-PAGE_SIZE = 100
+PAGE_SIZE = 1000
+LIMIT_DEFAULT = 3000
 TERMINAL_STATUSES = frozenset({"SUCCESS", "FAILED", "CANCELLED"})
 DOCKER_HUB = "docker.io"
 
@@ -77,6 +79,7 @@ class ImagesArgs(ArgumentsProtocol):
     all_images: bool = False
     since: datetime | None = None
     until: datetime | None = None
+    limit: int = LIMIT_DEFAULT
 
     @classmethod
     def from_args(cls, ns: argparse.Namespace) -> ImagesArgs:
@@ -86,6 +89,7 @@ class ImagesArgs(ArgumentsProtocol):
             all_images=getattr(ns, "all_images", False),
             since=getattr(ns, "since", None),
             until=getattr(ns, "until", None),
+            limit=getattr(ns, "limit", LIMIT_DEFAULT),
         )
 
 
@@ -189,6 +193,12 @@ def _add_list_args(p: argparse.ArgumentParser) -> None:
         type=parse_interval,
         help="Show images before. " + str(parse_interval.__doc__),
     )
+    p.add_argument(
+        *FLAGS["limit"],
+        type=positive_int,
+        default=LIMIT_DEFAULT,
+        help="Stop after this many images and warn if more are available",
+    )
 
 
 def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
@@ -249,7 +259,7 @@ def cmd_images(args: ImagesArgs) -> None:
     client = CLIENT.get()
     formatter = FORMATTER.get()
 
-    base_params: dict[str, str] = {"limit": str(PAGE_SIZE)}
+    base_params: dict[str, str] = {}
     if args.prefix is not None:
         base_params["tag"] = args.prefix
     if args.uuid is not None:
@@ -262,13 +272,19 @@ def cmd_images(args: ImagesArgs) -> None:
         base_params["until"] = isoformat_datetime(args.until)
 
     offset = 0
-    while True:
-        params = {**base_params, "offset": str(offset)}
+    emitted = 0
+    while emitted < args.limit:
+        page_size = min(PAGE_SIZE, args.limit - emitted)
+        params = {
+            **base_params,
+            "offset": str(offset),
+            "limit": str(page_size),
+        }
         resp = client.get("/v1/images", params=params)
         data = json.loads(resp.read())
         images = data["images"]
         if not images:
-            break
+            return
         for image in images:
             created_at = parse_datetime(image["created_at"])
             formatter(
@@ -276,9 +292,31 @@ def cmd_images(args: ImagesArgs) -> None:
                 created_at=created_at,
                 tag=image.get("tag") or "",
             )
-        if len(images) < PAGE_SIZE:
-            break
+        emitted += len(images)
+        if len(images) < page_size:
+            return
         offset += len(images)
+        if emitted < args.limit:
+            logger.info(
+                "Fetched %d images so far... (press Ctrl+C to break)",
+                emitted,
+            )
+
+    # Hit the limit. Probe one extra record (offset=emitted, limit=1) to
+    # detect truncation without re-fetching a full page.
+    probe_params = {**base_params, "offset": str(offset), "limit": "1"}
+    resp = client.get("/v1/images", params=probe_params)
+    data = json.loads(resp.read())
+    if data.get("images"):
+        # Flush buffered output (e.g. TableFormatter) before the warning
+        # so the truncation note appears AFTER the listing on screen.
+        formatter.flush()
+        logger.warning(
+            "Output truncated at --limit=%d images; more results are"
+            " available. Raise --limit or narrow with"
+            " --prefix/--since/--until.",
+            args.limit,
+        )
 
 
 def _parse_explicit_tag(ref: str) -> tuple[str, str | None]: