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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: contree-cli
-Version: 0.5.0
+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.5.0 → 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.5.0 → contree_cli-0.5.1}/contree_cli/__main__.py

@@ -2,6 +2,7 @@ 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
@@ -12,6 +13,7 @@ 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__)
 
@@ -27,6 +29,21 @@ def main() -> None:
     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
 

{contree_cli-0.5.0 → 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.5.0 → 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 = """\
@@ -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.5.0 → 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.5.0 → 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]:

{contree_cli-0.5.0 → contree_cli-0.5.1}/contree_cli/cli/ps.py

@@ -13,14 +13,19 @@ import argparse
 import itertools
 import json
 import logging
-from collections.abc import Iterator
 from dataclasses import dataclass
 from datetime import datetime, timedelta
 from typing import Any
 
 from contree_cli import CLIENT, FORMATTER, ArgumentsProtocol, SetupResult
 from contree_cli.output import OutputFormatter
-from contree_cli.types import FLAGS, isoformat_datetime, parse_datetime, parse_interval
+from contree_cli.types import (
+    FLAGS,
+    isoformat_datetime,
+    parse_datetime,
+    parse_interval,
+    positive_int,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -103,7 +108,7 @@ def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
 
     p.add_argument(
         *FLAGS["show_max"],
-        type=int,
+        type=positive_int,
         default=1000,
         help=(
             "Show at most this many operations, useful"
@@ -114,64 +119,26 @@ def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
     return cmd_ps, PsArgs
 
 
-def operations_iterator(
-    status: str | None = None,
-    kind: str | None = None,
-    show_max: int | None = None,
-    page_size: int = PAGE_SIZE,
-    since: str | None = None,
-    until: str | None = None,
-) -> Iterator[dict[str, Any]]:
-    client = CLIENT.get()
-    assert client is not None, "Client not initialized"
-
-    offset = 0
-    counter = 1
-    while True:
-        params: dict[str, str] = {
-            "limit": str(page_size),
-            "offset": str(offset),
-        }
-        if status:
-            params["status"] = status
-        if kind:
-            params["kind"] = kind
-        if since:
-            params["since"] = since
-        if until:
-            params["until"] = until
-        resp = client.get("/v1/operations", params=params)
-        operations = json.loads(resp.read())
-
-        if not operations:
-            break
-
-        offset += len(operations)
-        for op in operations:
-            if show_max is not None and counter >= show_max:
-                logger.warning(
-                    "Reached show_max limit of %d, for see more increase --show-max",
-                    show_max,
-                )
-                return
-            counter += 1
-            yield dict(
-                uuid=op["uuid"],
-                status=op["status"],
-                kind=op["kind"],
-                created_at=parse_datetime(op["created_at"]),
-                duration=timedelta(seconds=op["duration"])
-                if op.get("duration") is not None
-                else None,
-                error=op.get("error") or "",
-            )
-
-        if len(operations) < page_size:
-            break
+def emit_op(formatter: OutputFormatter, op: dict[str, Any], *, quiet: bool) -> None:
+    row = dict(
+        uuid=op["uuid"],
+        status=op["status"],
+        kind=op["kind"],
+        created_at=parse_datetime(op["created_at"]),
+        duration=timedelta(seconds=op["duration"])
+        if op.get("duration") is not None
+        else None,
+        error=op.get("error") or "",
+    )
+    if quiet:
+        print(row["uuid"])
+    else:
+        formatter(**row)
 
 
 def cmd_ps(args: PsArgs) -> None:
     formatter: OutputFormatter = FORMATTER.get()
+    client = CLIENT.get()
 
     status: str | None = None
     if args.status is not None:
@@ -182,21 +149,62 @@ def cmd_ps(args: PsArgs) -> None:
     elif not args.all:
         status = "EXECUTING"
 
-    since: str | None = None
+    base_params: dict[str, str] = {}
+    if status:
+        base_params["status"] = status
+    if args.kind:
+        base_params["kind"] = args.kind
     if args.since is not None:
-        since = isoformat_datetime(args.since)
-    until: str | None = None
+        base_params["since"] = isoformat_datetime(args.since)
     if args.until is not None:
-        until = isoformat_datetime(args.until)
-
-    for op in operations_iterator(
-        status=status,
-        kind=args.kind,
-        show_max=args.show_max,
-        since=since,
-        until=until,
-    ):
-        if args.quiet:
-            print(op["uuid"])
-        else:
-            formatter(**op)
+        base_params["until"] = isoformat_datetime(args.until)
+
+    limit = args.show_max
+    offset = 0
+    emitted = 0
+    hit_limit = False
+
+    while limit is None or emitted < limit:
+        page_size = PAGE_SIZE if limit is None else min(PAGE_SIZE, limit - emitted)
+        params = {
+            **base_params,
+            "offset": str(offset),
+            "limit": str(page_size),
+        }
+        resp = client.get("/v1/operations", params=params)
+        operations = json.loads(resp.read())
+        if not operations:
+            return
+        for op in operations:
+            if limit is not None and emitted >= limit:
+                hit_limit = True
+                break
+            emit_op(formatter, op, quiet=args.quiet)
+            emitted += 1
+        if hit_limit:
+            break
+        if len(operations) < page_size:
+            return
+        offset += len(operations)
+        if limit is None or emitted < limit:
+            logger.info(
+                "Fetched %d operations so far... (press Ctrl+C to break)",
+                emitted,
+            )
+
+    if limit is None:
+        return
+
+    # 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(emitted), "limit": "1"}
+    resp = client.get("/v1/operations", params=probe_params)
+    operations = json.loads(resp.read())
+    if operations:
+        formatter.flush()
+        logger.warning(
+            "Output truncated at --show-max=%d operations; more results"
+            " are available. Raise --show-max or filter with"
+            " --status/--kind/--since/--until.",
+            limit,
+        )

{contree_cli-0.5.0 → contree_cli-0.5.1}/contree_cli/client.py

@@ -9,7 +9,7 @@ import platform
 import sys
 import time
 from abc import ABC, abstractmethod
-from collections.abc import Iterator
+from collections.abc import Iterable, Iterator
 from importlib.metadata import PackageNotFoundError, version
 from typing import IO, cast
 from urllib.parse import urlencode, urlsplit
@@ -21,7 +21,7 @@ log = logging.getLogger(__name__)
 RETRY_DELAYS = (1, 2, 4, 5, 10, 10, 10)
 
 
-def _cli_version() -> str:
+def cli_version() -> str:
     try:
         return version("contree-cli")
     except PackageNotFoundError:
@@ -29,12 +29,43 @@ def _cli_version() -> str:
 
 
 CLI_USER_AGENT = (
-    f"contree-cli/{_cli_version()} "
+    f"contree-cli/{cli_version()} "
     f"Python/{'.'.join(map(str, sys.version_info))} "
     f"{platform.platform()} "
 )
 
 
+class HeaderFormatter:
+    """Lazy redactor for HTTP headers, formats only on emit."""
+
+    SENSITIVE_HEADERS = frozenset(
+        {
+            "authorization",
+            "proxy-authorization",
+            "cookie",
+            "set-cookie",
+            "x-api-key",
+            "x-auth-token",
+        }
+    )
+
+    def __init__(
+        self,
+        headers: dict[str, str] | list[tuple[str, str]],
+    ) -> None:
+        self.headers = headers
+
+    def __str__(self) -> str:
+        items: Iterable[tuple[str, str]] = (
+            self.headers.items() if isinstance(self.headers, dict) else self.headers
+        )
+        redacted = {
+            k: "<redacted>" if k.lower() in self.SENSITIVE_HEADERS else v
+            for k, v in items
+        }
+        return repr(redacted)
+
+
 class BodyFormatter:
     """Lazy %s-arg for logging HTTP bodies — formats only on emit."""
 
@@ -186,9 +217,10 @@ class ContreeClient(ABC):
         attempts = len(RETRY_DELAYS) + 1
 
         log.debug(
-            "%s %s body=%s",
+            "%s %s headers=%s body=%s",
             method,
             full_path,
+            HeaderFormatter(merged),
             BodyFormatter(body, content_type=merged.get("Content-Type", "")),
         )
 
@@ -220,24 +252,27 @@ class ContreeClient(ABC):
 
             if 200 <= resp.status < 300:
                 log.debug(
-                    "%s %s -> %d %s",
+                    "%s %s -> %d %s headers=%s",
                     method,
                     full_path,
                     resp.status,
                     resp.reason,
+                    HeaderFormatter(list(resp.getheaders())),
                 )
                 if log.isEnabledFor(logging.DEBUG):
                     return self.log_and_buffer(method, full_path, resp)
                 return resp
 
+            resp_headers = list(resp.getheaders())
             resp_body = resp.read().decode("utf-8", errors="replace")
             log.debug(
-                "%s %s -> %d %s (%dB)",
+                "%s %s -> %d %s (%dB) headers=%s",
                 method,
                 full_path,
                 resp.status,
                 resp.reason,
                 len(resp_body),
+                HeaderFormatter(resp_headers),
             )
             log.debug(
                 "%s %s response body: %s",

{contree_cli-0.5.0 → contree_cli-0.5.1}/contree_cli/config.py

@@ -94,6 +94,10 @@ class Config(MutableMapping[str, ConfigProfile]):
         self.__active: str = "default"
         self._load()
 
+    @property
+    def path(self) -> Path:
+        return self.__path
+
     # -- persistence ---------------------------------------------------------
 
     def _load(self) -> None:
@@ -191,32 +195,23 @@ class Config(MutableMapping[str, ConfigProfile]):
         self._save()
 
     def resolve(self, profile_override: str | None = None) -> ConfigProfile:
-        """Resolve the active profile with env-var overrides.
+        """Resolve the active profile by name.
 
         Priority: *profile_override* > ``CONTREE_PROFILE`` > config default.
-        Per-field: ``CONTREE_TOKEN`` / ``CONTREE_URL`` / ``CONTREE_PROJECT``
-        override the stored values.
+        Credentials come strictly from the saved profile; runtime
+        commands do not read tokens, URLs, or project IDs from the
+        environment. To register/refresh credentials from env vars use
+        ``contree auth``.
         """
         name = profile_override or os.environ.get("CONTREE_PROFILE") or self.__active
-        env_token = os.environ.get("CONTREE_TOKEN")
-        env_url = os.environ.get("CONTREE_URL")
-        env_project = os.environ.get("CONTREE_PROJECT")
-
         if name in self.__profiles:
-            p = self.__profiles[name]
-            return ConfigProfile(
-                name=name,
-                token=env_token or p.token,
-                url=env_url or p.url,
-                auth_type=p.auth_type,
-                project=env_project or p.project,
-            )
+            return self.__profiles[name]
         return ConfigProfile(
             name=name,
-            token=env_token,
-            url=env_url or "",
+            token=None,
+            url="",
             auth_type=AuthType.JWT,
-            project=env_project,
+            project=None,
         )
 
     def switch(self, name: str) -> None:

{contree_cli-0.5.0 → contree_cli-0.5.1}/contree_cli/manual.md

@@ -198,9 +198,11 @@ Profiles
 
 Each profile has its own session database.
 
-Auth fallback: if `NEBIUS_API_KEY` and `NEBIUS_AI_PROJECT` are set
-in the environment and no `--token`/`--project` flags are passed,
-`contree auth` picks them up automatically (no interactive prompts).
+Auth fallback: when `--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. These are used only during registration; runtime
+commands read credentials strictly from the saved profile.
 
 More: contree auth --help
 
@@ -218,12 +220,14 @@ override with $CONTREE_HOME.
 Environment variables:
   CONTREE_HOME       data directory
   XDG_CONFIG_HOME    XDG base config dir, used to derive default CONTREE_HOME
-  CONTREE_TOKEN      API token (overrides config)
-  CONTREE_URL        API URL (overrides config)
-  CONTREE_PROJECT    project ID (overrides config)
-  CONTREE_PROFILE    active profile
+  CONTREE_PROFILE    active profile (selects which profile commands use)
   CONTREE_SESSION    explicit session key
 
+Registration-time fallbacks (read only by `contree auth`):
+  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 --help
 
 All commands

{contree_cli-0.5.0 → contree_cli-0.5.1}/contree_cli/types.py

@@ -62,6 +62,7 @@ FLAGS: Mapping[str, tuple[str, ...]] = MappingProxyType(
         "uuid": ("-i", "--uuid"),
         "username": ("--username",),
         "password": ("--password",),
+        "limit": ("--limit",),
         # use
         "new": ("-N", "--new"),
         # session
@@ -89,6 +90,17 @@ class ArgumentsFormatter(argparse.RawDescriptionHelpFormatter):
         return help_text
 
 
+def positive_int(value: str) -> int:
+    """argparse type for flags that must be at least 1."""
+    try:
+        n = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"invalid int value: {value!r}") from exc
+    if n < 1:
+        raise argparse.ArgumentTypeError(f"must be >= 1, got {n}")
+    return n
+
+
 def get_command_docs(setup_fn: SetupFn) -> tuple[str | None, str | None]:
     """Extract description and epilog from the module that defines *setup_fn*.
 

contree_cli-0.5.1/contree_cli/update_check.py

@@ -0,0 +1,165 @@
+"""PyPI update check, rate-limited to once per day.
+
+State file at ``$CONTREE_HOME/cli/version_check.json``::
+
+    {
+      "last_check": 1762555200,
+      "latest_version": "0.5.0"
+    }
+
+``last_check`` is a Unix epoch timestamp; storing seconds keeps the
+freshness check trivial (one subtraction) and immune to timezone /
+ISO-format quirks.
+
+Network errors, malformed cache files, and parse failures are swallowed:
+the update check must never break a user's command.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+import urllib.request
+from contextlib import suppress
+from dataclasses import asdict, dataclass
+from datetime import timedelta
+from pathlib import Path
+
+from contree_cli import config
+from contree_cli.client import CLI_USER_AGENT, cli_version
+
+
+@dataclass(frozen=True)
+class UpdateState:
+    last_check: int = 0
+    latest_version: str = ""
+
+    @classmethod
+    def from_file(cls, path: Path) -> UpdateState:
+        try:
+            with path.open() as f:
+                data = json.load(f)
+            return cls(
+                last_check=int(data["last_check"]),
+                latest_version=str(data["latest_version"]),
+            )
+        except Exception:
+            return cls()
+
+    def to_file(self, path: Path) -> None:
+        with suppress(OSError):
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(json.dumps(asdict(self), indent=1))
+
+
+class UpdateChecker:
+    PYPI_URL = "https://pypi.org/pypi/contree-cli/json"
+    CHECK_INTERVAL = timedelta(days=1)
+    NETWORK_TIMEOUT = 2.0
+    OPT_OUT_ENV = "CONTREE_NO_UPDATE_CHECK"
+    STATE_PATH = config.CONTREE_HOME / "cli" / "version_check.json"
+    # Capture leading digits of each dot-separated component; anything
+    # past the digits (``a1``, ``-rc.1``, etc.) marks a pre-release.
+    COMPONENT_REGEX = re.compile(r"\d+")
+
+    def __init__(
+        self,
+        *,
+        state_path: Path = STATE_PATH,
+        current_version: str = cli_version(),
+    ) -> None:
+        self.state_path = state_path
+        self.current_version = current_version
+        # ``state`` holds whatever we know about PyPI's latest version.
+        # Default sentinel ("", last_check=0) means "no cache yet" —
+        # is_latest() treats it as up-to-date so callers don't warn.
+        self.state: UpdateState = UpdateState()
+
+    def parse_version(self, value: str) -> tuple[tuple[int, int], ...]:
+        """Parse ``value`` into a sortable tuple of ``(number, rank)``.
+
+        ``rank`` is ``1`` for a clean numeric component and ``0`` for a
+        pre-release suffix (``a1``, ``-rc.1``, …). With this encoding,
+        ``0.4.2a1`` < ``0.4.2`` < ``0.4.21`` as expected. Components with
+        no digits at all are dropped.
+        """
+        parts: list[tuple[int, int]] = []
+        for raw in value.split("."):
+            match = self.COMPONENT_REGEX.search(raw)
+            if not match:
+                continue
+            tail = raw[match.end() :]
+            parts.append((int(match.group()), 0 if tail else 1))
+        return tuple(parts)
+
+    def fetch_latest_version(self) -> str | None:
+        try:
+            request = urllib.request.Request(
+                self.PYPI_URL,
+                headers={
+                    "User-Agent": CLI_USER_AGENT,
+                    "Accept": "application/json",
+                },
+            )
+            with urllib.request.urlopen(  # nosemgrep
+                request, timeout=self.NETWORK_TIMEOUT
+            ) as resp:
+                payload = json.loads(resp.read())
+        except Exception:
+            return None
+        info = payload.get("info") if isinstance(payload, dict) else None
+        if not isinstance(info, dict):
+            return None
+        version = info.get("version")
+        return version if isinstance(version, str) else None
+
+    @property
+    def enabled(self) -> bool:
+        return self.OPT_OUT_ENV not in os.environ and self.current_version != "editable"
+
+    def is_cache_fresh(self, state: UpdateState) -> bool:
+        """True if ``state.last_check`` is within ``CHECK_INTERVAL``."""
+        return time.time() - state.last_check < self.CHECK_INTERVAL.total_seconds()
+
+    def refresh(self) -> None:
+        """Load the cache, refetch from PyPI if stale, persist new state.
+
+        Populates ``self.state`` with whatever we know after this call.
+        :meth:`is_latest` then decides whether to warn based purely on
+        in-memory state — no further file IO.
+        """
+        if not self.enabled:
+            return
+
+        self.state = UpdateState.from_file(self.state_path)
+        if self.is_cache_fresh(self.state):
+            return
+
+        latest = self.fetch_latest_version()
+        if latest is None:
+            # Network failed; keep whatever was cached.
+            return
+
+        self.state = UpdateState(
+            last_check=int(time.time()),
+            latest_version=latest,
+        )
+        self.state.to_file(self.state_path)
+
+    def is_latest(self) -> bool:
+        """Return True if the installed version is at or ahead of the cached
+        ``latest_version``.
+
+        Returns True when checks are disabled or the cached
+        ``latest_version`` is the empty sentinel — callers default to
+        "no warning" in those cases. Pure decision based on in-memory
+        state populated by :meth:`refresh`; never touches the network
+        or filesystem.
+        """
+        if not self.enabled or not self.state.latest_version:
+            return True
+        return self.parse_version(self.current_version) >= self.parse_version(
+            self.state.latest_version,
+        )

{contree_cli-0.5.0 → contree_cli-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "contree-cli"
-version = "0.5.0"
+version = "0.5.1"
 description = "CLI client for the ConTree sandbox platform"
 readme = "README.md"
 requires-python = ">=3.10"