msdev 0.14.1__tar.gz → 0.15.1__tar.gz

{msdev-0.14.1 → msdev-0.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: msdev
-Version: 0.14.1
+Version: 0.15.1
 Summary: Portable nodes and execution environments for msModelSlim development
 Author: msModelSlim Agent Contributors
 License-Expression: MulanPSL-2.0
@@ -25,12 +25,13 @@ Dynamic: license-file
 
 # msdev
 
-`msdev` exposes three capabilities: **`node`** (connect + host agent),
+`msdev` exposes three capabilities: **`node`** (SSH + connection reuse),
 **`env`** (shared execution context, shell, files), and **`exec`** (commands).
 
-A Node owns SSH reachability and `msdevd` deployment. An Env owns the full
-execution context: host or Docker runtime, conda/venv/uv layers, optional
-`setup` script (root switch, proxy, etc.), command `wrap`, and static env vars.
+A Node owns SSH reachability and optional ControlMaster multiplexing. An Env
+owns the full execution context: host or Docker runtime, conda/venv/uv layers,
+optional `setup` script (root switch, proxy, etc.), command `wrap`, and static
+env vars. Commands run over direct SSH (no remote `msdevd`).
 
 The CLI is intentionally stateless: execution always names the env as the first
 `exec` argument.
@@ -45,7 +46,7 @@ python3 -m pip install -e .
 msdev --help
 ```
 
-The package installs `msdev` and `msdevd`.
+The package installs the `msdev` CLI.
 
 Install the agent skill for Cursor and Claude Code, and sync SSH config:
 
@@ -63,43 +64,39 @@ overwrite; use `-f` to force.
 
 ## Windows client
 
-The typical setup is a **Windows laptop talking to Linux Nodes** via OpenSSH
-(`C:\Windows\System32\OpenSSH\ssh.exe`). Native Windows OpenSSH does not
-implement ControlMaster multiplexing, so msdev:
-
-- omits `ControlMaster`/`ControlPath` on Windows (override with
-  `MSDEV_SSH_CONTROL_MASTER=1` only if your SSH client actually supports mux);
-- starts a persistent `ssh -L` LocalForward tunnel automatically on the first
-  RPC (same role as ControlMaster). Explicit `msdev node connect NODE` is
-  optional; disable persist with `MSDEV_SSH_LOCAL_FORWARD_PERSIST=0`;
-- reuses that tunnel for captured RPC and default streaming `msdev exec`;
-  `env put`/`get` stay on sftp/ssh streams (file bytes do not go through JSON RPC);
-- hides SSH console windows (`CREATE_NO_WINDOW`) and kills process trees with
-  `taskkill /T` on timeout or cancel;
+The typical setup is a **Windows laptop talking to Linux Nodes**. Native
+`C:\Windows\System32\OpenSSH\ssh.exe` does **not** support ControlMaster.
+msdev therefore prefers **Git for Windows** OpenSSH when installed
+(`C:\Program Files\Git\usr\bin\ssh.exe`), which does:
+
+- auto-selects Git Bash `ssh`/`sftp`/`ssh-keygen` over PATH / System32 OpenSSH;
+  override with `MSDEV_SSH` / `MSDEV_SFTP` / `MSDEV_SSH_KEYGEN`;
+- enables ControlMaster when the resolved client is Git/MSYS OpenSSH (disable
+  with `MSDEV_SSH_CONTROL_MASTER=0`, force with `=1`);
+- falls back to System32 OpenSSH without mux if Git is not installed;
+- hides SSH console windows (`CREATE_NO_WINDOW`) and kills local process trees
+  with `taskkill /T` on timeout or cancel;
 - SSH is non-interactive: `BatchMode` unless a password is supplied, host keys
   use `accept-new`, and there is no password/passphrase/yes-no prompt. When a
   password is known, injects OpenSSH `SSH_ASKPASS` so `node connect` (and later
   ssh/sftp) can authenticate without a TTY; the local public key is then
   installed on the Node so later logins are passwordless. The password is
-  never written to the node registry;
-- serves a TCP loopback endpoint for local `msdevd` when this Python build has
-  no `AF_UNIX` sockets.
+  never written to the node registry.
 
 Install with `python -m pip install -e .`. `install-user.py` writes
-`msdev.cmd` / `msdevd.cmd` under `%USERPROFILE%\.local\bin`.
+`msdev.cmd` under `%USERPROFILE%\.local\bin`.
 
 Remote paths inside a Linux Env remain POSIX (`/srv/...`). Local `env put`/`get`
 on Windows accept Windows absolute paths (`C:\...`).
 
 Local `exec` on Windows wraps Conda with `conda run` and venvs with
 `Scripts\activate.bat` (remote Linux Nodes still use POSIX `sh`/`bash` wrappers).
-If `ssh` is not on PATH, msdev looks in `%SystemRoot%\System32\OpenSSH\`.
 
 ## Nodes and execution environments
 
 Use **`node connect`** as the single entry point: it writes `~/.ssh/config`
 when needed, registers the node, saves passwords, installs the local public
-key, and deploys `msdevd`:
+key, and opens an SSH ControlMaster when multiplexing is supported:
 
 ```bash
 msdev node connect dev-122 --hostname 80.48.33.133 --user root --password PASSWORD
@@ -111,25 +108,27 @@ msdev node list
 ```
 
 Connect writes or updates a dedicated `Host <name>` block in OpenSSH config.
-The msdev registry stores only the Host alias plus msdevd settings
-(`remote_bin`, `auto_bootstrap`). User, port, keys, and proxy remain in SSH
-config. `node sync-ssh` registers Host aliases that were added manually.
+The msdev registry stores the Host alias. User, port, keys, and proxy remain in
+SSH config. `node sync-ssh` registers Host aliases that were added manually.
 
-Connect atomically creates a same-named host Env on first use and uploads a
-**static Go msdevd** binary matching the node architecture
-(`linux-amd64` / `linux-arm64`) when the agent is missing or when the remote
-`ping` version does not match the local CLI. Use **`msdev node bootstrap NODE`**
-to force a redeploy after upgrading msdev. No Python is required on the node.
+Connect atomically creates a same-named host Env on first use. There is no
+remote agent binary to deploy. Use **`msdev node bootstrap NODE`** only to
+re-check SSH readiness after connect problems.
 
-Build the static daemons before release or local testing:
+Inspect connectivity for one node or for every registered node (probes run in
+parallel; partial failures exit non-zero):
 
 ```bash
-bash msdevd/build-static.sh
-bash file-helper/build-static.sh
+msdev node status
+msdev node status dev-122
 ```
 
-Packaged artifacts live under `src/msdev/helpers/` (gitignored until built).
-The Go source is in `msdev/`.
+Rename a node together with its same-named host Env, guide files, and SSH
+`Host` alias:
+
+```bash
+msdev node rename dev-122 lab-122
+```
 
 Persistent OpenSSH masters are optional. All SSH from msdev is
 non-interactive: host keys use `accept-new`, and password/passphrase prompts
@@ -179,11 +178,11 @@ msdev env add dev-122-root \
 msdev env open dev-122-root
 ```
 
-Open a human-operated interactive shell in an Env:
+Open an interactive shell in an env. Docker envs enter the container:
 
 ```bash
 msdev env shell dev-122
-msdev env shell dev-122 --cwd /srv/project
+msdev env shell dev-122-docker --cwd /srv/project
 ```
 
 Agent automation should use `msdev exec`, not `env shell`.
@@ -259,11 +258,9 @@ CRLF on a Windows console so remote line output does not staircase; piped
 CLI output keeps LF.
 
 `--timeout-seconds` defaults to `-1` (no deadline). Any positive finite duration
-is also accepted. A positive timeout kills the complete command
-process group and returns exit code 124. Cancelling the local CLI closes the RPC
-connection, causing `msdevd` to kill and reap the remote process group. Finite
-SSH/Unix RPC deadlines include a short completion grace for output drain and
-serialization.
+is also accepted. A positive timeout kills the local SSH/command process tree
+and returns a timed-out result. Cancelling the local CLI closes the SSH
+session (best-effort remote cancel).
 
 `--result-json` selects captured, non-streaming execution and prints one
 structured JSON result containing stdout and stderr.
@@ -273,12 +270,11 @@ structured JSON result containing stdout and stderr.
 ```text
 msdev CLI
   -> typed core service
-  -> UnixRpcTransport or SshRpcTransport
-  -> per-user msdevd (env session + job runner + files)
+  -> UnixRpcTransport (local subprocess) or SshRpcTransport
+  -> SSH ControlMaster (when supported) + direct remote command / SFTP
 ```
 
-Remote RPC responses and command output are bounded. Node/Env registries use
-locked atomic updates.
+Remote command output is bounded. Node/Env registries use locked atomic updates.
 
 ## Testing
 
@@ -287,5 +283,5 @@ python3 -m unittest discover -s tests -v
 ```
 
 Feature work must include at least one actual scenario test on the real
-control path (`msdev` CLI → service → transport → `msdevd` → effect). Unit
-tests alone are not sufficient.
+control path (`msdev` CLI → service → SSH/SFTP → effect). Unit tests alone
+are not sufficient.

{msdev-0.14.1 → msdev-0.15.1}/README.md

@@ -1,11 +1,12 @@
 # msdev
 
-`msdev` exposes three capabilities: **`node`** (connect + host agent),
+`msdev` exposes three capabilities: **`node`** (SSH + connection reuse),
 **`env`** (shared execution context, shell, files), and **`exec`** (commands).
 
-A Node owns SSH reachability and `msdevd` deployment. An Env owns the full
-execution context: host or Docker runtime, conda/venv/uv layers, optional
-`setup` script (root switch, proxy, etc.), command `wrap`, and static env vars.
+A Node owns SSH reachability and optional ControlMaster multiplexing. An Env
+owns the full execution context: host or Docker runtime, conda/venv/uv layers,
+optional `setup` script (root switch, proxy, etc.), command `wrap`, and static
+env vars. Commands run over direct SSH (no remote `msdevd`).
 
 The CLI is intentionally stateless: execution always names the env as the first
 `exec` argument.
@@ -20,7 +21,7 @@ python3 -m pip install -e .
 msdev --help
 ```
 
-The package installs `msdev` and `msdevd`.
+The package installs the `msdev` CLI.
 
 Install the agent skill for Cursor and Claude Code, and sync SSH config:
 
@@ -38,43 +39,39 @@ overwrite; use `-f` to force.
 
 ## Windows client
 
-The typical setup is a **Windows laptop talking to Linux Nodes** via OpenSSH
-(`C:\Windows\System32\OpenSSH\ssh.exe`). Native Windows OpenSSH does not
-implement ControlMaster multiplexing, so msdev:
-
-- omits `ControlMaster`/`ControlPath` on Windows (override with
-  `MSDEV_SSH_CONTROL_MASTER=1` only if your SSH client actually supports mux);
-- starts a persistent `ssh -L` LocalForward tunnel automatically on the first
-  RPC (same role as ControlMaster). Explicit `msdev node connect NODE` is
-  optional; disable persist with `MSDEV_SSH_LOCAL_FORWARD_PERSIST=0`;
-- reuses that tunnel for captured RPC and default streaming `msdev exec`;
-  `env put`/`get` stay on sftp/ssh streams (file bytes do not go through JSON RPC);
-- hides SSH console windows (`CREATE_NO_WINDOW`) and kills process trees with
-  `taskkill /T` on timeout or cancel;
+The typical setup is a **Windows laptop talking to Linux Nodes**. Native
+`C:\Windows\System32\OpenSSH\ssh.exe` does **not** support ControlMaster.
+msdev therefore prefers **Git for Windows** OpenSSH when installed
+(`C:\Program Files\Git\usr\bin\ssh.exe`), which does:
+
+- auto-selects Git Bash `ssh`/`sftp`/`ssh-keygen` over PATH / System32 OpenSSH;
+  override with `MSDEV_SSH` / `MSDEV_SFTP` / `MSDEV_SSH_KEYGEN`;
+- enables ControlMaster when the resolved client is Git/MSYS OpenSSH (disable
+  with `MSDEV_SSH_CONTROL_MASTER=0`, force with `=1`);
+- falls back to System32 OpenSSH without mux if Git is not installed;
+- hides SSH console windows (`CREATE_NO_WINDOW`) and kills local process trees
+  with `taskkill /T` on timeout or cancel;
 - SSH is non-interactive: `BatchMode` unless a password is supplied, host keys
   use `accept-new`, and there is no password/passphrase/yes-no prompt. When a
   password is known, injects OpenSSH `SSH_ASKPASS` so `node connect` (and later
   ssh/sftp) can authenticate without a TTY; the local public key is then
   installed on the Node so later logins are passwordless. The password is
-  never written to the node registry;
-- serves a TCP loopback endpoint for local `msdevd` when this Python build has
-  no `AF_UNIX` sockets.
+  never written to the node registry.
 
 Install with `python -m pip install -e .`. `install-user.py` writes
-`msdev.cmd` / `msdevd.cmd` under `%USERPROFILE%\.local\bin`.
+`msdev.cmd` under `%USERPROFILE%\.local\bin`.
 
 Remote paths inside a Linux Env remain POSIX (`/srv/...`). Local `env put`/`get`
 on Windows accept Windows absolute paths (`C:\...`).
 
 Local `exec` on Windows wraps Conda with `conda run` and venvs with
 `Scripts\activate.bat` (remote Linux Nodes still use POSIX `sh`/`bash` wrappers).
-If `ssh` is not on PATH, msdev looks in `%SystemRoot%\System32\OpenSSH\`.
 
 ## Nodes and execution environments
 
 Use **`node connect`** as the single entry point: it writes `~/.ssh/config`
 when needed, registers the node, saves passwords, installs the local public
-key, and deploys `msdevd`:
+key, and opens an SSH ControlMaster when multiplexing is supported:
 
 ```bash
 msdev node connect dev-122 --hostname 80.48.33.133 --user root --password PASSWORD
@@ -86,25 +83,27 @@ msdev node list
 ```
 
 Connect writes or updates a dedicated `Host <name>` block in OpenSSH config.
-The msdev registry stores only the Host alias plus msdevd settings
-(`remote_bin`, `auto_bootstrap`). User, port, keys, and proxy remain in SSH
-config. `node sync-ssh` registers Host aliases that were added manually.
+The msdev registry stores the Host alias. User, port, keys, and proxy remain in
+SSH config. `node sync-ssh` registers Host aliases that were added manually.
 
-Connect atomically creates a same-named host Env on first use and uploads a
-**static Go msdevd** binary matching the node architecture
-(`linux-amd64` / `linux-arm64`) when the agent is missing or when the remote
-`ping` version does not match the local CLI. Use **`msdev node bootstrap NODE`**
-to force a redeploy after upgrading msdev. No Python is required on the node.
+Connect atomically creates a same-named host Env on first use. There is no
+remote agent binary to deploy. Use **`msdev node bootstrap NODE`** only to
+re-check SSH readiness after connect problems.
 
-Build the static daemons before release or local testing:
+Inspect connectivity for one node or for every registered node (probes run in
+parallel; partial failures exit non-zero):
 
 ```bash
-bash msdevd/build-static.sh
-bash file-helper/build-static.sh
+msdev node status
+msdev node status dev-122
 ```
 
-Packaged artifacts live under `src/msdev/helpers/` (gitignored until built).
-The Go source is in `msdev/`.
+Rename a node together with its same-named host Env, guide files, and SSH
+`Host` alias:
+
+```bash
+msdev node rename dev-122 lab-122
+```
 
 Persistent OpenSSH masters are optional. All SSH from msdev is
 non-interactive: host keys use `accept-new`, and password/passphrase prompts
@@ -154,11 +153,11 @@ msdev env add dev-122-root \
 msdev env open dev-122-root
 ```
 
-Open a human-operated interactive shell in an Env:
+Open an interactive shell in an env. Docker envs enter the container:
 
 ```bash
 msdev env shell dev-122
-msdev env shell dev-122 --cwd /srv/project
+msdev env shell dev-122-docker --cwd /srv/project
 ```
 
 Agent automation should use `msdev exec`, not `env shell`.
@@ -234,11 +233,9 @@ CRLF on a Windows console so remote line output does not staircase; piped
 CLI output keeps LF.
 
 `--timeout-seconds` defaults to `-1` (no deadline). Any positive finite duration
-is also accepted. A positive timeout kills the complete command
-process group and returns exit code 124. Cancelling the local CLI closes the RPC
-connection, causing `msdevd` to kill and reap the remote process group. Finite
-SSH/Unix RPC deadlines include a short completion grace for output drain and
-serialization.
+is also accepted. A positive timeout kills the local SSH/command process tree
+and returns a timed-out result. Cancelling the local CLI closes the SSH
+session (best-effort remote cancel).
 
 `--result-json` selects captured, non-streaming execution and prints one
 structured JSON result containing stdout and stderr.
@@ -248,12 +245,11 @@ structured JSON result containing stdout and stderr.
 ```text
 msdev CLI
   -> typed core service
-  -> UnixRpcTransport or SshRpcTransport
-  -> per-user msdevd (env session + job runner + files)
+  -> UnixRpcTransport (local subprocess) or SshRpcTransport
+  -> SSH ControlMaster (when supported) + direct remote command / SFTP
 ```
 
-Remote RPC responses and command output are bounded. Node/Env registries use
-locked atomic updates.
+Remote command output is bounded. Node/Env registries use locked atomic updates.
 
 ## Testing
 
@@ -262,5 +258,5 @@ python3 -m unittest discover -s tests -v
 ```
 
 Feature work must include at least one actual scenario test on the real
-control path (`msdev` CLI → service → transport → `msdevd` → effect). Unit
-tests alone are not sufficient.
+control path (`msdev` CLI → service → SSH/SFTP → effect). Unit tests alone
+are not sufficient.

{msdev-0.14.1 → msdev-0.15.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "msdev"
-version = "0.14.1"
+version = "0.15.1"
 description = "Portable nodes and execution environments for msModelSlim development"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -35,7 +35,6 @@ Repository = "https://gitcode.com/rookie_hongchuan/msdev"
 
 [project.scripts]
 msdev = "msdev.cli:main"
-msdevd = "msdev.daemon:main"
 
 [tool.setuptools]
 package-dir = { "" = "src" }
@@ -45,8 +44,6 @@ where = ["src"]
 
 [tool.setuptools.package-data]
 msdev = [
-  "helpers/msdev-file-helper-*",
-  "helpers/msdevd-linux-*",
   "skills/msdev-cli/SKILL.md",
 ]
 

{msdev-0.14.1 → msdev-0.15.1}/src/msdev/__init__.py

@@ -1,3 +1,3 @@
 """Portable node and execution-environment tooling for msModelSlim."""
 
-__version__ = "0.14.1"
+__version__ = "0.15.1"

{msdev-0.14.1 → msdev-0.15.1}/src/msdev/cli.py

@@ -154,8 +154,6 @@ def _provision_request_for_connect(
         if ssh_host_defined(args.name):
             return NodeAddRequest(
                 name=args.name,
-                remote_bin=args.remote_bin,
-                auto_bootstrap=not args.no_auto_bootstrap,
                 force=args.force,
             )
         raise ValueError(
@@ -169,8 +167,6 @@ def _provision_request_for_connect(
         port=args.port,
         identity_file=args.identity_file,
         ssh_host=args.ssh_host,
-        remote_bin=args.remote_bin,
-        auto_bootstrap=not args.no_auto_bootstrap,
         force=bool(
             args.force or has_params
         ),
@@ -204,9 +200,7 @@ def command_node(
         print("local\tregistered\t-")
         for node in service.list().nodes:
             print(
-                f"{node.name}\tregistered\tssh={node.ssh_host}\t"
-                f"auto-bootstrap={'on' if node.auto_bootstrap else 'off'}\t"
-                f"bin={node.remote_bin}"
+                f"{node.name}\tregistered\tssh={node.ssh_host}"
             )
         if args.ssh:
             for host in service.list_ssh_hosts():
@@ -236,12 +230,39 @@ def command_node(
         if removed:
             print("removed environments: " + ", ".join(removed))
         return 0
-    if action == "status":
-        print(f"node: {args.name}")
-        _print_json(service.status(args.name))
+    if action == "rename":
+        node = service.rename(args.name, args.new_name)
+        print(f"renamed node {args.name} -> {node.name} (ssh={node.ssh_host})")
         return 0
+    if action == "status":
+        if args.name:
+            print(f"node: {args.name}")
+            _print_json(service.status(args.name))
+            return 0
+        result = service.status_all()
+        for item in result.items:
+            if item.error is not None:
+                print(
+                    f"{item.node} ({item.ssh_host}): unreachable: {item.error}",
+                    file=sys.stderr,
+                )
+            else:
+                info = item.info if isinstance(item.info, dict) else {}
+                parts: list[str] = []
+                hostname = str(info.get("hostname") or "")
+                ip = str(info.get("ip") or "")
+                target = str(info.get("target") or "")
+                if hostname:
+                    parts.append(f"hostname={hostname}")
+                if ip:
+                    parts.append(f"ip={ip}")
+                if target and target not in {hostname, ip, item.ssh_host}:
+                    parts.append(f"target={target}")
+                detail = (" " + " ".join(parts)) if parts else ""
+                print(f"{item.node} ({item.ssh_host}): reachable{detail}")
+        return result.exit_code
     if action == "bootstrap":
-        result = service.bootstrap(args.name, package_path=args.package)
+        result = service.bootstrap(args.name)
         _print_json(result)
         return 0
     if action in {"connect", "disconnect"}:
@@ -281,8 +302,8 @@ def command_node(
                 key = getattr(item, "key", None)
                 if key:
                     suffix = f"(persist={item.persist}, key={key})"
-                if item.agent_ready:
-                    suffix = suffix[:-1] + ", agent=ready)"
+                if item.ssh_ready:
+                    suffix = suffix[:-1] + ", ssh=ready)"
                 print(
                     f"{item.node}: {item.state} to {item.ssh_host} "
                     f"{suffix}"
@@ -615,27 +636,31 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="also remove every environment on this node",
     )
-    node_status = node_sub.add_parser("status")
-    node_status.add_argument("name")
+    node_rename = node_sub.add_parser(
+        "rename",
+        help="rename a node, its host environment, and a matching SSH Host alias",
+    )
+    node_rename.add_argument("name")
+    node_rename.add_argument("new_name")
+    node_status = node_sub.add_parser(
+        "status",
+        help="check node connectivity (every registered SSH node by default)",
+    )
+    node_status.add_argument(
+        "name",
+        nargs="?",
+        help="check one node; omit to check every registered SSH node",
+    )
     node_bootstrap = node_sub.add_parser(
         "bootstrap",
-        help=(
-            "force-redeploy msdevd on the node "
-            "(use after local upgrade when remote version mismatches)"
-        ),
+        help="ensure SSH reachability / ControlMaster for the node",
     )
     node_bootstrap.add_argument("name")
-    node_bootstrap.add_argument(
-        "--package",
-        type=Path,
-        default=None,
-        help="optional source checkout for source-layout bootstrap",
-    )
     node_connect = node_sub.add_parser(
         "connect",
         help=(
-            "register a node if needed, write ~/.ssh/config, connect, "
-            "and deploy/start msdevd when needed"
+            "register a node if needed, write ~/.ssh/config, "
+            "and open an SSH ControlMaster when supported"
         ),
     )
     node_connect.add_argument(
@@ -662,17 +687,11 @@ def build_parser() -> argparse.ArgumentParser:
         "--ssh-host",
         help="legacy shorthand for user@hostname when writing ~/.ssh/config",
     )
-    node_connect.add_argument("--remote-bin", default="~/.local/bin/msdevd")
     node_connect.add_argument(
         "--force",
         action="store_true",
         help="replace an existing node and its same-named host environment",
     )
-    node_connect.add_argument(
-        "--no-auto-bootstrap",
-        action="store_true",
-        help="do not install/start msdevd automatically on first use",
-    )
     node_connect.add_argument(
         "--password",
         default=None,
@@ -752,7 +771,7 @@ def build_parser() -> argparse.ArgumentParser:
     environment_inspect.add_argument("name")
     environment_open = environment_sub.add_parser(
         "open",
-        help="establish the shared environment session (runs setup once)",
+        help="check that the environment is ready (setup runs on each exec)",
     )
     environment_open.add_argument("name")
     environment_guide = environment_sub.add_parser("guide")
@@ -760,7 +779,10 @@ def build_parser() -> argparse.ArgumentParser:
     environment_guide_action = environment_guide.add_mutually_exclusive_group()
     environment_guide_action.add_argument("--write", metavar="FILE")
     environment_guide_action.add_argument("--delete", action="store_true")
-    environment_shell = environment_sub.add_parser("shell")
+    environment_shell = environment_sub.add_parser(
+        "shell",
+        help="open an interactive shell in the environment (including Docker)",
+    )
     environment_shell.add_argument("name")
     environment_shell.add_argument("--cwd")
     environment_put = environment_sub.add_parser(