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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: contree-cli
-Version: 0.5.0
+Version: 0.6.0
 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.6.0}/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.6.0}/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.6.0}/contree_cli/agent.md

@@ -134,7 +134,28 @@ Tag conventions:
 Always search before building:
   contree images --prefix=python-dev
 
-More: contree images --help, contree tag --help
+Building from a Dockerfile:
+  When a project already ships a Dockerfile, prefer `contree build`
+  over hand-running each step. It executes FROM/RUN/COPY/WORKDIR/ENV
+  /ARG/USER against the API and caches every layer as a branch so
+  rebuilds are fast.
+
+  Layer cache is keyed by abspath(context), shared across invocations:
+    contree build .                     build ./Dockerfile, no tag
+    contree build . --tag myapp:dev     build + tag the final image
+    contree build ./app --dockerfile ./app/Dockerfile.prod --tag svc:prod
+    contree build . --build-arg VERSION=1.2
+    contree build . --no-cache          force rebuild
+
+  Supported directives: FROM, RUN, COPY, ADD (local paths only),
+  WORKDIR, ENV, ARG, USER. CMD/ENTRYPOINT/LABEL/EXPOSE/VOLUME/etc.
+  are parsed but skipped with a warning. Multi-stage (AS / --from)
+  is not yet supported.
+
+  .dockerignore is applied to every COPY/ADD walk on top of the
+  default exclude list (.git, __pycache__, node_modules, etc.).
+
+More: contree build --help, contree images --help, contree tag --help
 
 Files and directories
 =====================
@@ -177,6 +198,32 @@ Pending files are injected into the next non-disposable run.
 Explicit --file takes priority over pending files at same path.
 Pending files are branch-aware.
 
+Listing uploaded files:
+  contree file ls                 list all uploaded files in the project
+  contree file ls --since 1d      narrow by upload time
+  contree file ls -q              uuid + sha256 + source only (quiet)
+  contree -f json file ls         JSON output for jq
+
+  Output joins remote files (uuid, sha256, size, created_at) with the
+  local upload cache. The SOURCE column shows whatever this machine
+  used to produce the file:
+    - absolute host path for files uploaded via `run --file` / `COPY`;
+    - https://... URL for files fetched via `ADD URL`.
+
+  IMPORTANT: SOURCE is resolved ONLY for files uploaded from this
+  specific machine. The mapping lives in the local SQLite cache (per
+  profile, under $CONTREE_HOME/cli/sessions/<profile>.db) keyed by
+  path+inode+mtime+size (for host paths) or by the URL itself (for
+  URL fetches), and is NOT shared between hosts. Rows show empty
+  SOURCE when:
+    - the file was uploaded from a different machine or by a teammate;
+    - the host file has been moved, renamed, or its inode/mtime/size
+      changed since upload (the cache key no longer matches);
+    - the upload happened before tracking landed (older entries
+      backfill on the next match).
+  An agent must not assume SOURCE is authoritative across hosts;
+  for cross-machine identity always use the remote UUID or sha256.
+
 More: contree run --help, contree file --help
 
 Execution modes
@@ -211,10 +258,31 @@ Piped stdin:
 Detached mode (-d):
   contree run -d -- long-running-task
   contree ps                              check status
+  contree ps -a -S FAILED --since=1h      recent failures
   contree show UUID                       view result
   contree session wait                    block until done
   contree session wait UUID1 UUID2        wait for specific ops
 
+Monitoring background operations:
+  Use the `operation` namespace (alias `op`) when juggling several
+  detached runs. `op ls` is `ps`; `op show` and `op cancel` accept
+  multiple UUIDs in one call.
+
+  contree op ls                           list operations (= ps)
+  contree op ls -a -S EXECUTING           filter active runs
+  contree op show UUID1 UUID2 UUID3       inspect a batch in one call
+  contree op cancel UUID1 UUID2           cancel selected operations
+  contree op cancel --all                 cancel every active op (rare)
+
+  Fan-out + join pattern:
+    A=$(contree run -d -- make -C /work/a build | jq -r .uuid)
+    B=$(contree run -d -- make -C /work/b build | jq -r .uuid)
+    contree session wait "$A" "$B"
+    contree op show "$A" "$B"
+
+  Background checks are cheap: terminal results are cached locally,
+  so repeated `op show` / `show` calls do not re-hit the API.
+
 Disposable mode (-D) — no image checkpoint:
   contree run -D -- rm -rf /tmp/*
   contree run -D -- cat /etc/passwd
@@ -328,18 +396,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
@@ -347,11 +420,16 @@ All commands
 
   use [IMAGE]             Set or show session image (aliases: ci)
   run [-- CMD]            Spawn sandbox instance (aliases: r)
+  build [CONTEXT]         Build image from Dockerfile (aliases: bd)
   images                  List/import images (aliases: i, img)
   tag [IMAGE] TAG         Tag image (aliases: t)
   ps                      List operations
   kill UUID               Cancel operation
   show UUID               Show operation result
+  operation list          List operations (aliases: op ls)
+  operation show UUID...  Show one or more operation results (aliases: op)
+  operation cancel UUID...
+                          Cancel one or more operations (or --all)
   ls [PATH]               List files in image (no VM)
   cat PATH                Show file content (no VM)
   cp PATH DEST            Download file from image
@@ -359,6 +437,7 @@ All commands
   env [KEY=VALUE ...]     Session env vars (-d to unset)
   file edit PATH          Edit remote file via $EDITOR
   file cp SRC DEST        Stage local file for next run
+  file ls [-q]            List uploaded files + local path (aliases: list)
   session list            List sessions (aliases: ls)
   session branch [NAME]   Create/list branches (aliases: br)
   session checkout BRANCH Switch branch (aliases: co)

{contree_cli-0.5.0 → contree_cli-0.6.0}/contree_cli/arguments.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from contree_cli.cli import (
     agent,
     auth,
+    build,
     cat,
     cd,
     cp,
@@ -14,6 +15,7 @@ from contree_cli.cli import (
     images,
     kill,
     ls,
+    operation,
     ps,
     run,
     session,
@@ -44,6 +46,9 @@ examples:
   contree run --file ./src:/app/src -- make -C /app/src
   contree images --prefix=ubuntu
   contree ps -q
+  contree op ls                       same as `contree ps`
+  contree op show UUID1 UUID2         multi-UUID show
+  contree op cancel UUID1 UUID2       multi-UUID cancel (or --all)
   contree show OPERATION_UUID
   contree tag IMAGE_UUID latest
   contree ls /etc                    list files in session image
@@ -71,20 +76,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 +125,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 +137,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"],
@@ -207,11 +211,18 @@ def register(
 
 register("use", "Set or show current session image", use.setup_parser, aliases=["ci"])
 register("run", "Spawn a sandbox instance", run.setup_parser, aliases=["r"])
+register("build", "Build image from Dockerfile", build.setup_parser, aliases=["bd"])
 register("images", "List and import images", images.setup_parser, aliases=["i", "img"])
 register("tag", "Tag an image", tag.setup_parser, aliases=["t"])
 register("ps", "List operations/instances", ps.setup_parser)
 register("kill", "Cancel an operation", kill.setup_parser)
 register("show", "Show operation result", show.setup_parser)
+register(
+    "operation",
+    "Manage operations (list/show/cancel)",
+    operation.setup_parser,
+    aliases=["op"],
+)
 register("ls", "List files in image", ls.setup_parser)
 register("cat", "Show file content from image", cat.setup_parser)
 register("cp", "Copy file from image to local path", cp.setup_parser)

{contree_cli-0.5.0 → contree_cli-0.6.0}/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()