modal 1.5.3.dev13__tar.gz → 1.5.4.dev1__tar.gz

{modal-1.5.3.dev13 → modal-1.5.4.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.5.3.dev13
+Version: 1.5.4.dev1
 Summary: Python client library for Modal
 Author-email: Modal Labs <support@modal.com>
 License-Expression: Apache-2.0

{modal-1.5.3.dev13 → modal-1.5.4.dev1}/modal/_clustered_functions.py

@@ -15,6 +15,7 @@ class ClusterInfo:
     cluster_id: str
     container_ips: list[str]
     container_ipv4_ips: list[str]
+    fabric_ids: list[str]
 
 
 cluster_info: ClusterInfo | None = None
@@ -29,6 +30,14 @@ def get_cluster_info() -> ClusterInfo:
     return cluster_info
 
 
+def get_fabric_peers() -> list[int]:
+    info = get_cluster_info()
+    if info.rank >= len(info.fabric_ids) or not info.fabric_ids[info.rank]:
+        return [info.rank]
+    own_fabric_id = info.fabric_ids[info.rank]
+    return [rank for rank, fabric_id in enumerate(info.fabric_ids) if fabric_id == own_fabric_id]
+
+
 async def _initialize_clustered_function(client: _Client, task_id: str, world_size: int):
     global cluster_info
 
@@ -70,6 +79,7 @@ async def _initialize_clustered_function(client: _Client, task_id: str, world_si
             cluster_id=resp.cluster_id,
             container_ips=resp.container_ips,
             container_ipv4_ips=resp.container_ipv4_ips,
+            fabric_ids=resp.fabric_ids,
         )
     else:
         cluster_info = ClusterInfo(
@@ -77,6 +87,7 @@ async def _initialize_clustered_function(client: _Client, task_id: str, world_si
             cluster_id="",  # No cluster ID for single-node  # TODO(irfansharif): Is this right?
             container_ips=[container_ip],
             container_ipv4_ips=[],  # No IPv4 IPs for single-node
+            fabric_ids=[],
         )
 
 

{modal-1.5.3.dev13 → modal-1.5.4.dev1}/modal/_clustered_functions.pyi

@@ -3,14 +3,17 @@ import types
 import typing_extensions
 
 class ClusterInfo:
-    """ClusterInfo(rank: int, cluster_id: str, container_ips: list[str], container_ipv4_ips: list[str])"""
+    """ClusterInfo(rank: int, cluster_id: str, container_ips: list[str], container_ipv4_ips: list[str], fabric_ids: list[str])"""
 
     rank: int
     cluster_id: str
     container_ips: list[str]
     container_ipv4_ips: list[str]
+    fabric_ids: list[str]
 
-    def __init__(self, rank: int, cluster_id: str, container_ips: list[str], container_ipv4_ips: list[str]) -> None:
+    def __init__(
+        self, rank: int, cluster_id: str, container_ips: list[str], container_ipv4_ips: list[str], fabric_ids: list[str]
+    ) -> None:
         """Initialize self.  See help(type(self)) for accurate signature."""
         ...
 
@@ -23,6 +26,7 @@ class ClusterInfo:
         ...
 
 def get_cluster_info() -> ClusterInfo: ...
+def get_fabric_peers() -> list[int]: ...
 async def _initialize_clustered_function(client: modal.client._Client, task_id: str, world_size: int): ...
 
 class __initialize_clustered_function_spec(typing_extensions.Protocol):

{modal-1.5.3.dev13 → modal-1.5.4.dev1}/modal/_environments.py

@@ -4,7 +4,7 @@ import builtins
 from collections.abc import Iterable, Mapping
 from dataclasses import dataclass
 from datetime import datetime, timezone
-from typing import Literal
+from typing import Any, Literal
 
 from google.protobuf.empty_pb2 import Empty
 from google.protobuf.message import Message
@@ -16,6 +16,7 @@ from modal_proto import api_pb2
 from ._load_context import LoadContext
 from ._object import _Object
 from ._resolver import Resolver
+from ._utils.deprecation import deprecation_warning
 from ._utils.name_utils import check_environment_name
 from ._utils.time_utils import is_utc_month_aligned, parse_billing_cycle
 from .client import _Client
@@ -38,6 +39,7 @@ class _EnvironmentManager:
         name: str,  # Name to use for the new Environment
         *,
         restricted: bool = False,  # If True, enable RBAC restrictions on the Environment
+        experimental_options: dict[str, Any] | None = None,  # Experimental options for Environment creation
         client: _Client | None = None,  # Optional client with Modal credentials
     ) -> None:
         """Create a new Environment.
@@ -50,7 +52,10 @@ class _EnvironmentManager:
         """
         check_environment_name(name)
         client = await _Client.from_env() if client is None else client
-        await client.stub.EnvironmentCreate(api_pb2.EnvironmentCreateRequest(name=name, is_managed=restricted))
+        request = api_pb2.EnvironmentCreateRequest(name=name, is_managed=restricted)
+        if (experimental_options or {}).get("is_public", False):
+            request.environment_type = api_pb2.ENVIRONMENT_TYPE_PUBLIC
+        await client.stub.EnvironmentCreate(request)
 
     async def list(
         self,
@@ -104,7 +109,7 @@ class _EnvironmentManager:
         await client.stub.EnvironmentDelete(api_pb2.EnvironmentDeleteRequest(name=name))
 
 
-class _EnvironmentMembersManager:
+class _EnvironmentRolesManager:
     """mdmd:namespace"""
 
     def __init__(self, environment: "_Environment"):
@@ -112,13 +117,13 @@ class _EnvironmentMembersManager:
         self._environment = environment
 
     async def list(self) -> dict[Literal["users", "service_users"], dict[str, str]]:
-        """Enumerate the environment roles for each user and service user in the workspace.
+        """Enumerate the Environment Role for each user and service user in the workspace.
 
         **Examples:**
 
         ```python notest
-        members = modal.Environment.from_name("my-env").members.list()
-        print(members)
+        roles = modal.Environment.from_name("my-env").roles.list()
+        print(roles)
         # {
         #     "users": {"alice": "contributor", "bob": "viewer", "carol": "contributor"},
         #     "service_users": {"alice-bot": "contributor", "ops-bot": "viewer", "ci-bot": "no-access"},
@@ -145,16 +150,17 @@ class _EnvironmentMembersManager:
         users: Mapping[str, str] | None = None,
         service_users: Mapping[str, str] | None = None,
     ) -> None:
-        """Add or modify roles for members of a restricted Environment.
+        """Update the Environment Role of users and service users.
 
-        Each user or service user will be added to the Environment if not currently a member;
-        if already a member, the user or service user's role will be updated.
+        Each role is one of 'contributor', 'viewer', or 'no-access'. Service users can be
+        assigned a role on any Environment, while workspace members can only be assigned a
+        role on restricted Environments.
 
         **Examples:**
 
         ```python notest
         env = modal.Environment.from_name("my-restricted-env")
-        env.members.update(
+        env.roles.update(
             users={"alice": "contributor", "bob": "viewer"},
             service_users={"alice-bot": "contributor"},
         )
@@ -196,24 +202,59 @@ class _EnvironmentMembersManager:
 
         await self._dispatch_role_updates(requests)
 
+    async def _dispatch_role_updates(self, requests: dict[str, api_pb2.EnvironmentRoleSetRequest]) -> None:
+        """Send batched EnvironmentRoleSet RPCs and report all errors encountered."""
+        results = await asyncio.gather(
+            *(self._environment.client.stub.EnvironmentRoleSet(req) for req in requests.values()),
+            return_exceptions=True,
+        )
+        errors = [(label, result) for label, result in zip(requests.keys(), results) if isinstance(result, Exception)]
+        if errors:
+            n = len(errors)
+            header = f"{n} error{'s' if n != 1 else ''} occurred while updating Environment roles:"
+            details = "\n".join(f"  - {label}: {e}" for label, e in errors)
+            raise WorkspaceManagementError(f"{header}\n{details}")
+
+
+# Deprecated alias for `_EnvironmentRolesManager`; each method warns and delegates.
+class _EnvironmentMembersManager:
+    """mdmd:hidden"""
+
+    def __init__(self, environment: "_Environment"):
+        """mdmd:hidden"""
+        self._environment = environment
+
+    async def list(self) -> dict[Literal["users", "service_users"], dict[str, str]]:
+        deprecation_warning(
+            (2026, 7, 23),
+            "`Environment.members.list()` is deprecated; use `Environment.roles.list()` instead.",
+        )
+        return await _EnvironmentRolesManager(self._environment).list()
+
+    async def update(
+        self,
+        *,
+        users: Mapping[str, str] | None = None,
+        service_users: Mapping[str, str] | None = None,
+    ) -> None:
+        deprecation_warning(
+            (2026, 7, 23),
+            "`Environment.members.update()` is deprecated; use `Environment.roles.update()` instead.",
+        )
+        await _EnvironmentRolesManager(self._environment).update(users=users, service_users=service_users)
+
     async def remove(
         self,
         *,
         users: Iterable[str] | None = None,
         service_users: Iterable[str] | None = None,
     ) -> None:
-        """Remove members from a restricted Environment.
-
-        **Examples:**
-
-        ```python notest
-        env = modal.Environment.from_name("my-restricted-env")
-        env.members.remove(
-            users=["alice"],
-            service_users=["alice-bot"],
+        """Remove the Environment Role of users and service users, reverting them to the default."""
+        deprecation_warning(
+            (2026, 7, 23),
+            "`Environment.members.remove()` is deprecated. Environment Roles are now explicit; "
+            "set a role (e.g. 'no-access') with `Environment.roles.update()` instead.",
         )
-        ```
-        """
         await self._environment.hydrate()
         users = users or []
         service_users = service_users or []
@@ -247,20 +288,7 @@ class _EnvironmentMembersManager:
                 role=api_pb2.ENVIRONMENT_ROLE_UNSPECIFIED,
             )
 
-        await self._dispatch_role_updates(requests)
-
-    async def _dispatch_role_updates(self, requests: dict[str, api_pb2.EnvironmentRoleSetRequest]) -> None:
-        """Send batched EnvironmentRoleSet RPCs and report all errors encountered."""
-        results = await asyncio.gather(
-            *(self._environment.client.stub.EnvironmentRoleSet(req) for req in requests.values()),
-            return_exceptions=True,
-        )
-        errors = [(label, result) for label, result in zip(requests.keys(), results) if isinstance(result, Exception)]
-        if errors:
-            n = len(errors)
-            header = f"{n} error{'s' if n != 1 else ''} occurred while updating Environment members:"
-            details = "\n".join(f"  - {label}: {e}" for label, e in errors)
-            raise WorkspaceManagementError(f"{header}\n{details}")
+        await _EnvironmentRolesManager(self._environment)._dispatch_role_updates(requests)
 
 
 class _Environment(_Object, type_prefix="en"):
@@ -284,11 +312,17 @@ class _Environment(_Object, type_prefix="en"):
         return _EnvironmentManager()
 
     @property
-    def members(self) -> "_EnvironmentMembersManager":
-        """Namespace with methods for managing the membership of a restricted Environment.
+    def roles(self) -> "_EnvironmentRolesManager":
+        """Namespace with methods for managing the Environment Roles of users and service users.
 
-        See https://modal.com/docs/guide/rbac for more information on restricted Environments.
+        See https://modal.com/docs/guide/rbac for more information on Environment Roles.
         """
+        return _EnvironmentRolesManager(self)
+
+    @property
+    def members(self) -> "_EnvironmentMembersManager":
+        """mdmd:hidden"""
+        # Deprecated alias for `Environment.roles`.
         return _EnvironmentMembersManager(self)
 
     # TODO(michael) Keeping this private for now until we decide what else should be in it

{modal-1.5.3.dev13 → modal-1.5.4.dev1}/modal/_image.py

@@ -117,34 +117,51 @@ def _validate_image_tag(tag: str) -> None:
     check_object_name(tag, "Image tag")
 
 
-def _parse_named_image_ref(name: str) -> tuple[str, str]:
-    """Parse an image reference, returning (namespace_prefix, name_tag).
-
-    If the name contains a '/', the part before the last '/' is extracted as
-    a namespace prefix (intended for environment/name or workspace/env/name
-    syntax). The actual image name (after the last '/') is validated as a
-    standard object name.
-
-    Returns a tuple of (prefix, "full_name:tag") where prefix is empty string
-    if no '/' is present.
-    """
-    image_name, sep, tag = name.partition(":")
+def _parse_image_name(partial_name: str) -> tuple[str | None, str]:
+    partial_name_no_env, sep, tag = partial_name.partition(":")
     if not sep:
         tag = "latest"
 
-    prefix = ""
-    if "/" in image_name:
-        prefix, image_name = image_name.rsplit("/", 1)
-        if not prefix:
-            raise InvalidError("Invalid Image name: '/' prefix must be non-empty.")
+    if "/" in partial_name_no_env:
+        environment, image_name = partial_name_no_env.rsplit("/", 1)
+        if not environment:
+            raise InvalidError("Invalid Image name: environment prefix before '/' must be non-empty.")
         if not image_name:
-            raise InvalidError("Invalid Image name: name after '/' must be non-empty.")
+            raise InvalidError("Invalid Image name: name after last '/' must be non-empty.")
+    else:
+        environment = None
+        image_name = partial_name_no_env
 
     _validate_image_name(image_name)
     _validate_image_tag(tag)
 
-    full_name = f"{prefix}/{image_name}" if prefix else image_name
-    return prefix, f"{full_name}:{tag}"
+    return environment, f"{image_name}:{tag}"
+
+
+def _upgrade_image_name(
+    partial_name: str,
+    *,
+    explicit_environment_name: str | None = None,
+    fallback_environment_name: str | None = None,
+) -> str:
+    """Ensures an Image name has a tag and an environment name when possible
+
+    * If no tag is present, add :latest
+    * If an explicit environment name is passed, add it as a prefix and error
+      if there is already a prefix
+    * If a fallback environment name is passed, add it only when there is no prefix
+
+    """
+    prefix_environment, name_tag = _parse_image_name(partial_name)
+    if prefix_environment:
+        if explicit_environment_name is not None:
+            raise InvalidError("environment_name cannot be used when an Image name includes an environment prefix.")
+        return f"{prefix_environment}/{name_tag}"
+
+    environment_name = explicit_environment_name if explicit_environment_name is not None else fallback_environment_name
+    if environment_name:
+        return f"{environment_name}/{name_tag}"
+    return name_tag  # no explicit environment - use just the unprefixed name:tag
 
 
 def _validate_python_version(
@@ -2932,8 +2949,8 @@ class _Image(_Object, type_prefix="im"):
     ) -> "_Image":
         """Reference a named Image that was previously published with `.publish()`.
 
-        Names can contain an optional `:tag` part - if no tag part is included `":latest"` is used,
-        matching Docker conventions.
+        Names can contain an optional `:tag` part. If no tag part is included, `":latest"` is used, matching
+        Docker conventions.
 
         ```python notest
         image = modal.Image.from_name("my-image")     # references my-image:latest
@@ -2944,20 +2961,16 @@ class _Image(_Object, type_prefix="im"):
             ...
         ```
         """
-        namespace_prefix, tag = _parse_named_image_ref(name)
-
-        if namespace_prefix and environment_name:
-            raise InvalidError("Cannot specify 'environment_name' when the image name contains a '/'.")
+        _upgrade_image_name(name, explicit_environment_name=environment_name)  # validate
 
         async def _load(self: _Image, resolver: Resolver, load_context: LoadContext, existing_object_id: str | None):
             req = api_pb2.ImageGetByTagRequest(
-                tag=tag,
-                environment_name="" if namespace_prefix else load_context.environment_name,
+                tag=_upgrade_image_name(name, fallback_environment_name=load_context.environment_name),
             )
             response = await load_context.client.stub.ImageGetByTag(req)
             self._hydrate(response.image_id, load_context.client, None)
 
-        rep = _Image._repr(tag, environment_name)
+        rep = _Image._repr(name, environment_name)
         return _Image._from_loader(
             _load,
             rep,
@@ -2971,13 +2984,14 @@ class _Image(_Object, type_prefix="im"):
         name: str,
         *,
         environment_name: str | None = None,
+        experimental_options: dict[str, Any] | None = None,
         client: _Client | None = None,
     ) -> None:
         """Publish this image under the given name
 
         The Image must already be created (typically by calling `image.build()` or `sandbox.snapshot_filesystem()`).
 
-        Image names can contain an explicit tag designation (using the `name:tag`). If no tag is included in the name,
+        Image names can contain an explicit tag designation using `name:tag`. If no tag is included in the name,
         `":latest"` is used, matching Docker conventions. To publish multiple tags, call `.publish()` once per tag.
 
         ```python notest
@@ -2987,25 +3001,20 @@ class _Image(_Object, type_prefix="im"):
         image.publish("my-image-with-numpy:v1")
         ```
         """
-        namespace_prefix, tag = _parse_named_image_ref(name)
-
-        if namespace_prefix:
-            if environment_name:
-                raise InvalidError("Cannot specify 'environment_name' when the image name contains a '/'.")
-            resolved_env = ""
-        else:
-            resolved_env = environment_name or config.get("environment") or ""
-
         if self._object_id is None:
             raise InvalidError("Cannot publish an image that has not been created yet. Call `.build()` first.")
 
         _client = client or await _Client.from_env()
+        tag = _upgrade_image_name(
+            name,
+            explicit_environment_name=environment_name,
+            fallback_environment_name=config.get("environment"),
+        )
 
         await _client.stub.ImagePublish(
             api_pb2.ImagePublishRequest(
                 image_id=self._object_id,
-                environment_name=resolved_env,
-                allow_public=False,
+                allow_public=bool((experimental_options or {}).get("is_public", False)),
                 tag=tag,
             )
         )

{modal-1.5.3.dev13 → modal-1.5.4.dev1}/modal/cli/environment.py

@@ -1,5 +1,6 @@
 # Copyright Modal Labs 2023
 import json as json_mod
+import warnings
 
 import click
 import rich
@@ -11,6 +12,7 @@ from rich.text import Text
 from modal import environments
 from modal._environments import _Environment
 from modal._utils.async_utils import synchronizer
+from modal._utils.deprecation import deprecation_warning
 from modal._utils.display_utils import pretty_decimal
 from modal._utils.name_utils import check_environment_name
 from modal._utils.time_utils import format_interval
@@ -18,7 +20,7 @@ from modal.cli.billing import DATE_HELP, _validate_and_parse_interval
 from modal.cli.utils import _col_name_to_json_key, confirm_or_suggest_yes, display_table, yes_option
 from modal.config import config
 from modal.environments import Environment
-from modal.exception import InvalidError
+from modal.exception import DeprecationError, InvalidError
 from modal.output import OutputManager
 
 from ._help import ModalGroup
@@ -55,7 +57,7 @@ def list_(json: bool = False):
     # over the server default
     active_env = config.get("environment") or ""
     for env in envs:
-        if env.default is True and active_env is None:
+        if env.default is True and not active_env:
             active_env = env.name
 
     table_data = []
@@ -70,10 +72,11 @@ def list_(json: bool = False):
 @environment_cli.command("create", help="Create a new environment in the current workspace.", no_args_is_help=True)
 @click.argument("name")
 @click.option("--restricted", is_flag=True, default=False, help="Enable RBAC restrictions on the new environment")
-def create(name: str, restricted: bool = False):
+@click.option("--public", is_flag=True, default=False, hidden=True)
+def create(name: str, restricted: bool = False, public: bool = False):
     check_environment_name(name)
-    Environment.objects.create(name, restricted=restricted)
-    prefix = "Restricted " if restricted else ""
+    Environment.objects.create(name, restricted=restricted, experimental_options={"is_public": public})
+    prefix = "Public " if public else "Restricted " if restricted else ""
     rich.print(f"[green]✓[/green] {prefix}Environment created: {name}")
 
 
@@ -123,67 +126,127 @@ def update(
     rich.print("[green]✓[/green] Environment updated")
 
 
-MEMBERS_HELP_TEXT = """Manage members and their roles in a restricted Environment.
-
-Restricted Environments use RBAC to limit the actions that can be performed by
-users (and service users) based on roles: https://modal.com/docs/guide/rbac.
-"""
-
-members_cli = ModalGroup(name="members", help=MEMBERS_HELP_TEXT)
-environment_cli.add_command(members_cli)
-
 service_user_option = click.option(
-    "--service-user", is_flag=True, default=False, help="Treat MEMBER as the name of a service user"
+    "--service-user", is_flag=True, default=False, help="Treat PRINCIPAL as the name of a service user"
 )
 
 
-@members_cli.command("list", help="List the members of a restricted Environment", no_args_is_help=True)
-@click.argument("environment")
-@click.option("--json", is_flag=True, default=False)
-def members_list(environment: str, json: bool = False):
-    members = Environment.from_name(environment).members.list()
+def _render_roles_list(environment: str, json: bool) -> None:
+    roles = Environment.from_name(environment).roles.list()
     if json:
         # Mirror the API output shape: a nested dict keyed by users / service_users.
-        OutputManager.get().print_json(json_mod.dumps(members))
+        OutputManager.get().print_json(json_mod.dumps(roles))
         return
     rows = []
-    for name, role in members.get("users", {}).items():
+    for name, role in roles.get("users", {}).items():
         rows.append([name, role])
-    for name, role in members.get("service_users", {}).items():
+    for name, role in roles.get("service_users", {}).items():
         rows.append([f"{name} (service user)", role])
     rows = sorted(rows, key=lambda x: x[0])
     display_table(["name", "role"], rows)
 
 
-@members_cli.command("update", help="Add or update a member's role in a restricted Environment", no_args_is_help=True)
-@click.argument("environment")
-@click.argument("member")
-@click.option(
-    "--role", type=click.Choice(["contributor", "viewer"]), required=True, help="Role to assign to the member"
-)
-@service_user_option
-def members_update(environment: str, member: str, role: str, service_user: bool = False):
+def _apply_role_update(environment: str, principal: str, role: str, service_user: bool) -> None:
     env = Environment.from_name(environment)
     if service_user:
-        env.members.update(service_users={member: role})
+        env.roles.update(service_users={principal: role})
     else:
-        env.members.update(users={member: role})
+        env.roles.update(users={principal: role})
     kind = "service user" if service_user else "user"
-    rich.print(f"[green]✓[/green] Set {kind} {member!r} to role {role!r} in environment {environment!r}")
+    rich.print(f"[green]✓[/green] Set {kind} {principal!r} to role {role!r} in environment {environment!r}")
 
 
-@members_cli.command("remove", help="Remove a member from a restricted Environment", no_args_is_help=True)
-@click.argument("environment")
-@click.argument("member")
-@service_user_option
-def members_remove(environment: str, member: str, service_user: bool = False):
+def _apply_role_remove(environment: str, principal: str, service_user: bool) -> None:
     env = Environment.from_name(environment)
-    if service_user:
-        env.members.remove(service_users=[member])
-    else:
-        env.members.remove(users=[member])
+    # `remove` only lives on the deprecated `members` manager, which warns. The caller (a
+    # deprecated `members` command) has already warned, so suppress the redundant SDK warning.
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", DeprecationError)
+        if service_user:
+            env.members.remove(service_users=[principal])
+        else:
+            env.members.remove(users=[principal])
     kind = "service user" if service_user else "user"
-    rich.print(f"[green]✓[/green] Removed {kind} {member!r} from environment {environment!r}")
+    rich.print(f"[green]✓[/green] Removed {kind} {principal!r} from environment {environment!r}")
+
+
+ROLES_HELP_TEXT = """Manage the Environment Roles of users and service users.
+
+An Environment Role is one of 'contributor' (read-write), 'viewer' (read-only), or
+'no-access', and dictates access to Environments. See
+https://modal.com/docs/guide/rbac for details on which principals can be assigned
+which roles.
+"""
+
+roles_cli = ModalGroup(name="roles", help=ROLES_HELP_TEXT)
+environment_cli.add_command(roles_cli)
+
+
+@roles_cli.command("list", help="List the roles of each user and service user in an Environment", no_args_is_help=True)
+@click.argument("environment")
+@click.option("--json", is_flag=True, default=False)
+def roles_list(environment: str, json: bool = False):
+    _render_roles_list(environment, json)
+
+
+@roles_cli.command("update", help="Update a user's or service user's role in an Environment", no_args_is_help=True)
+@click.argument("environment")
+@click.argument("principal")
+@click.option("--role", type=click.Choice(["contributor", "viewer", "no-access"]), required=True, help="Role to assign")
+@service_user_option
+def roles_update(environment: str, principal: str, role: str, service_user: bool = False):
+    _apply_role_update(environment, principal, role, service_user)
+
+
+# The deprecated `members` command group keeps working for existing automation, but is hidden
+# from `--help` so it is not discoverable. Each subcommand warns with its own guidance.
+members_cli = ModalGroup(name="members", help="[Deprecated] Use `modal environment roles`.", hidden=True)
+environment_cli.add_command(members_cli)
+
+
+@members_cli.command("list", help="[Deprecated] Use `modal environment roles list`", no_args_is_help=True)
+@click.argument("environment")
+@click.option("--json", is_flag=True, default=False)
+def members_list(environment: str, json: bool = False):
+    deprecation_warning(
+        (2026, 7, 23),
+        "`modal environment members list` is deprecated; use `modal environment roles list`.",
+        show_source=False,
+    )
+    _render_roles_list(environment, json)
+
+
+@members_cli.command("update", help="[Deprecated] Use `modal environment roles update`", no_args_is_help=True)
+@click.argument("environment")
+@click.argument("principal")
+@click.option(
+    "--role",
+    type=click.Choice(["contributor", "viewer", "no-access"]),
+    required=True,
+    help="Role to assign to the principal",
+)
+@service_user_option
+def members_update(environment: str, principal: str, role: str, service_user: bool = False):
+    deprecation_warning(
+        (2026, 7, 23),
+        "`modal environment members update` is deprecated; use `modal environment roles update`.",
+        show_source=False,
+    )
+    _apply_role_update(environment, principal, role, service_user)
+
+
+@members_cli.command("remove", help="[Deprecated] Use `modal environment roles update`", no_args_is_help=True)
+@click.argument("environment")
+@click.argument("principal")
+@service_user_option
+def members_remove(environment: str, principal: str, service_user: bool = False):
+    deprecation_warning(
+        (2026, 7, 23),
+        "`modal environment members remove` is deprecated; roles are now explicit — set a role "
+        "(e.g. `--role no-access`) with `modal environment roles update` instead.",
+        show_source=False,
+    )
+    _apply_role_remove(environment, principal, service_user)
 
 
 billing_cli = ModalGroup(name="billing", help="View billing and usage info for the given Environment.")