From 8188ec9fb0bbfcb1cffa824d524475f7956e0368 Mon Sep 17 00:00:00 2001
From: Zachary Lentz <zlentz@slac.stanford.edu>
Date: Tue, 7 Jul 2026 16:51:06 -0700
Subject: [PATCH] ENH: add ctrlenv-shell and document it

---
 README.md                |  6 ++++--
 scripts/ctrlenv_setup.sh | 23 ++++++++++++++++++-----
 2 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 1a06892c..88f6bee8 100644
--- a/README.md
+++ b/README.md
@@ -108,10 +108,11 @@ Usage:   /reg/g/pcds/engineering_tools/latest/scripts/check_host HOSTNAME<br/>
 usage:   source ctrlenv_setup.sh<br/>
     <br/>
     Set environment variables and add commands for using ctrlenv python tools.</br>
-    There are three subcommands that become available after sourcing:</br>
+    There are four subcommands that become available after sourcing:</br>
     <ul>
     <li>ctrlenv-pathmunge: adds a bundle, environment export bin, or application to your path.</li>
-    <li>ctrlenv-activate: activates a python environment.</li>
+    <li>ctrlenv-activate: activates a python environment in the current shell (useful for scripts).</li>
+    <li>ctrlenv-shell: activates a python environment in an exitable subshell (useful for interactive use).</li>
     <li>ctrlenv-versions: shows which versions exist for an app or environment.</li>
     </ul>
     </br>
@@ -146,6 +147,7 @@ usage:   source ctrlenv_setup.sh<br/>
     <ul><li>Note: with no args, ctrlenv-activate targets the latest ctrlenv-base</li></ul>
     <li>ctrlenv-activate ctrlenv-lucid</li>
     <li>ctrlenv-activate ctrlenv-widgets/v0.2.0</li>
+    <li>ctrlenv-shell ctrlenv-widgets/v0.2.0</li>
     <li>ctrlenv-version</li>
     <ul><li>Note: with no args, ctrlenv-activate targets the ctrlenv-base</li></ul>
     <li>ctrlenv-versions pytmc</li>
diff --git a/scripts/ctrlenv_setup.sh b/scripts/ctrlenv_setup.sh
index d3d4a3f6..74388abb 100644
--- a/scripts/ctrlenv_setup.sh
+++ b/scripts/ctrlenv_setup.sh
@@ -2,8 +2,9 @@
 #
 # Source this script to set shared environment variables and gain access to three shell functions:
 # 1. ctrlenv-pathmunge: adds the bin from a bundle, environment, or application to your path at a specific version
-# 2. ctrlenv-activate: puts you into a released pixi environment (pixi shell-hook)
-# 3. ctrlenv-versions: shows you which versions exist for an environment or application
+# 2. ctrlenv-activate: activates a released pixi environment in the current shell (useful for scripts)
+# 3. ctrlenv-shell: activates a released pixi environment in an exitable subshell (useful for interactive use)
+# 4. ctrlenv-versions: shows you which versions exist for an environment or application
 #
 # Defaults are:
 # - Always the latest release
@@ -39,13 +40,16 @@
 # Activate the default environment
 # ctrlenv-activate
 # or
-# ctrlenv-activate base
+# ctrlenv-activate ctrlenv-base
 #
 # Activate the latest version of a specific environment
-# ctrlenv-activate widgets
+# ctrlenv-activate ctrlenv-widgets
 #
 # Activate a specific version of a specific environment
-# ctrlenv-activate lucid/v0.1.2
+# ctrlenv-activate ctrlenv-lucid/v0.1.2
+#
+# Any invocation of ctrlenv-activate also works with ctrlenv-shell
+# ctrlenv-shell ctrlenv-widgets
 #
 # Show which versions exist for an environment or application
 # ctrlenv-versions ctrlenv-widgets
@@ -211,6 +215,15 @@ ctrlenv-activate() {
     return 1
 }
 
+# Enter an exitable shell with an environment.
+# Useful for exploring the pixi environments interactively.
+# Simply "exit" to exit the shell and deactivate the env.
+# Do not use this in a shell script- it will interrupt your script with a prompt.
+# This is functionally similar to the "pixi shell" command, but doesn't require pixi on the path.
+ctrlenv-shell() {
+    $SHELL -ic "ctrlenv-activate $*; exec $SHELL -i"
+}
+
 # Show which versions exist
 ctrlenv-versions() {
     local target