implement shell mode

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: vageorge00

.github/CODEOWNERS

@@ -67,4 +67,3 @@
 /src/azure-cli/azure/cli/command_modules/util/ @jiasli @zhoxing-ms @evelyn-ys
 /src/azure-cli/azure/cli/command_modules/vm/ @zhoxing-ms @jsntcy @wangzelin007 @yanzhudd @Drewm3 @TravisCragg-MSFT @nikhilpatel909 @sandeepraichura @hilaryw29 @GabstaMSFT @ramankumarlive @ushnaarshadkhan
 /src/azure-cli/azure/cli/command_modules/containerapp/ @zhoxing-ms @yanzhudd @ruslany @sanchitmehta @ebencarek @JennyLawrance @howang-ms @vinisoto @chinadragon0515 @vturecek @torosent @pagariyaalok @Juliehzl @jijohn14 @Greedygre @ShichaoQiu
-/src/azure-cli/azure/cli/command_modules/webapp/ @vageorge00

doc/sphinx/azhelpgen/doc_source_map.json

@@ -77,6 +77,5 @@
     "term": "src/azure-cli/azure/cli/command_modules/marketplaceordering/_help.py",
     "util": "src/azure-cli/azure/cli/command_modules/util/_help.py",
     "vm": "src/azure-cli/azure/cli/command_modules/vm/_help.py",
-    "vmss": "src/azure-cli/azure/cli/command_modules/vm/_help.py",
-    "webapp": "src/azure-cli/azure/cli/command_modules/webapp/_help.py"
+    "vmss": "src/azure-cli/azure/cli/command_modules/vm/_help.py"
 }

src/azure-cli/azure/cli/command_modules/appservice/_help.py

@@ -1919,24 +1919,40 @@
 
 helps['webapp exec'] = """
 type: command
-short-summary: Execute a shell command in a web app container.
+short-summary: Interact with a Linux web app container via command execution or an interactive shell session.
 long-summary: >
-    Execute shell commands remotely in your web app container. The command returns immediately 
-    after being accepted, without waiting for completion or output. Redirect to a file to capture results (see examples). 
+    Interact with your Linux web app container using two modes.
+    This command is only supported for Linux App Service plans.
+    'execute' runs a command in the container and returns immediately without waiting for completion or output.
+    Redirect to a file to capture results (see examples).
+    'shell' starts an interactive shell session with the main webapp container.
+    Shell sessions are subject to an idle timeout and may be terminated if inactive for an extended period.
     Requires SCM Basic Auth Publishing Credentials to be enabled.
 examples:
-  - name: Execute a simple command on a web app and redirect output to a log file
+  - name: Run a direct command in the container
     text: >
-        az webapp exec -g MyResourceGroup -n MyWebapp --command "(ls -l) > output.log 2>&1"
-  - name: Execute a command in a specific working directory on a specific instance
+        az webapp exec -g MyResourceGroup -n MyWebapp --mode execute --command pwd
+  - name: Run a bash command and redirect output to a file
     text: >
-        az webapp exec -g MyResourceGroup --name MyWebapp --command "npm install" --cwd /home/site/wwwroot --instance MyInstanceId
+        az webapp exec -g MyResourceGroup -n MyWebapp --mode execute --command bash --args "-c" "pwd &> pwd.txt"
+  - name: Create a file in a specific working directory
+    text: >
+        az webapp exec -g MyResourceGroup -n MyWebapp --mode execute --command touch --args "newfile.txt" --cwd /home/site
+  - name: Execute a command on a specific instance
+    text: >
+        az webapp exec -g MyResourceGroup -n MyWebapp --mode execute --command pwd --instance MyInstanceId
   - name: Execute a command on all instances
     text: >
-        az webapp exec -g MyResourceGroup -n MyWebapp --command "systemctl restart nginx" --instance all
+        az webapp exec -g MyResourceGroup -n MyWebapp --mode execute --command pwd --instance all
   - name: Execute a command on a deployment slot
     text: >
-        az webapp exec -g MyResourceGroup -n MyWebapp -s staging --command "python manage.py migrate"
+        az webapp exec -g MyResourceGroup -n MyWebapp -s staging --mode execute --command pwd
+  - name: Start an interactive shell session with the web app container
+    text: >
+        az webapp exec -g MyResourceGroup -n MyWebapp --mode shell
+  - name: Start an interactive shell session on a specific instance
+    text: >
+        az webapp exec -g MyResourceGroup -n MyWebapp --mode shell --instance MyInstanceId
 """
 
 helps['webapp delete'] = """

src/azure-cli/azure/cli/command_modules/appservice/_params.py

@@ -1504,13 +1504,19 @@ def load_arguments(self, _):
         c.argument("no_register", help="Don't try to register the Microsoft.CDN provider. Registration can be done manually with: az provider register --wait --namespace Microsoft.CDN. For more details, please review the documentation available at https://go.microsoft.com/fwlink/?linkid=2184995 .", default=False)
     with self.argument_context('webapp exec') as c:
         c.argument('name', arg_type=webapp_name_arg_type, id_part=None)
-        c.argument('command', options_list=['--command'], help='The command to execute in the container.')
-        c.argument('mode', 
-                    help='Execution mode. \'execute\': Starts command execution and returns immediately without returning command output.', 
-                    arg_type=get_enum_type(['execute']), default='execute')
-        c.argument('working_directory', options_list=['--working-directory', '--cwd'], 
-                    help='Working directory for command execution. Defaults to the container\'s working directory (typically /home/site/wwwroot for App Service images).'')
-        c.argument('instance', options_list=['--instance', '-i'], 
-                    help='Webapp instance(s) to target. Specify a comma-separated list of instance IDs (use "az webapp list-instances" to get IDs) or "all" for all instances. Defaults to a random instance.')
-        c.argument('slot', options_list=['--slot', '-s'], 
-                    help='Name of the web app slot. Default to the production slot if not specified.')
+        c.argument('command', options_list=['--command'],
+                   help='The command or executable to run in the container (e.g., pwd, bash, touch).')
+        c.argument('args', options_list=['--args'], nargs='+',
+                   help='Arguments to pass to the command. For shell commands, use: --command bash --args "-c" "your command here".')
+        c.argument('mode',
+                   help="Execution mode. 'execute': Starts command execution and returns immediately without returning"
+                   " command output. 'shell': Starts an interactive shell session with the main webapp container.",
+                   arg_type=get_enum_type(['execute', 'shell']), default='execute')
+        c.argument('working_directory', options_list=['--working-directory', '--cwd'],
+                   help="Working directory for command execution. Defaults to the container's working directory"
+                   " (typically /home/site/wwwroot for App Service images).")
+        c.argument('instance', options_list=['--instance', '-i'],
+                   help='Webapp instance(s) to target. Specify a comma-separated list of instance IDs'
+                   ' (use "az webapp list-instances" to get IDs) or "all" for all instances. Defaults to a random instance.')
+        c.argument('slot', options_list=['--slot', '-s'],
+                   help='Name of the web app slot. Default to the production slot if not specified.')

src/azure-cli/azure/cli/command_modules/appservice/custom.py

@@ -10949,37 +10949,168 @@ def _compute_checksum(input_bytes):
     return file_hash
 
 
-def _execute_command_on_instance(scm_url, headers, cookies, command, working_directory=None):
+def _start_shell_session(scm_url, headers, cookies=None):
+    import sys
+    import ssl
+    import platform
+    import threading
+    import time
+    import websocket
+    from azure.cli.core.util import should_disable_connection_verify
+
+    ws_url = scm_url.replace('https://', 'wss://') + '/exec/shell'
+
+    cookie_str = '; '.join(f'{k}={v}' for k, v in cookies.items()) if cookies else None
+    # Respect user's SSL verification settings (e.g., self-signed certs on private stamps)
+    sslopt = {'cert_reqs': ssl.CERT_NONE} if should_disable_connection_verify() else {}
+
+    ws = websocket.create_connection(
+        ws_url,
+        header=headers,
+        cookie=cookie_str,
+        sslopt=sslopt,
+        timeout=30
+    )
+
+    logger.info("Connected to %s", ws_url)
+    print("Connected! Type commands. Ctrl+C twice to quit.\n")
+
+    closed = threading.Event()
+
+    # WebSocket → stdout
+    def recv_loop():
+        try:
+            while not closed.is_set():
+                opcode, data = ws.recv_data()
+                if not data:
+                    break
+                text = data.decode('utf-8', errors='replace')
+                sys.stdout.write(text)
+                sys.stdout.flush()
+        except (websocket.WebSocketConnectionClosedException, OSError):
+            pass
+        finally:
+            closed.set()
+
+    recv_thread = threading.Thread(target=recv_loop, daemon=True)
+    recv_thread.start()
+
+    if platform.system() == 'Windows':
+        _shell_input_loop_windows(ws, closed)
+    else:
+        _shell_input_loop_unix(ws, closed)
+
+    closed.set()
+    try:
+        ws.close()
+    except Exception:  # pylint: disable=broad-except
+        pass
+
+
+def _shell_input_loop_windows(ws, closed):
+    import time
+    import msvcrt
+    import websocket as ws_module
+
+    # Windows special key codes → ANSI escape sequences
+    # Tab, Ctrl+D, Ctrl+L etc. work via the regular else branch (sent as-is)
+    # TODO: F1-F12, Insert, PgUp/PgDown not yet mapped — silently dropped
+    _WINDOWS_KEY_MAP = {
+        72: b'\x1b[A',   # Up
+        80: b'\x1b[B',   # Down
+        77: b'\x1b[C',   # Right
+        75: b'\x1b[D',   # Left
+        71: b'\x1b[H',   # Home
+        79: b'\x1b[F',   # End
+        83: b'\x1b[3~',  # Delete
+    }
+
+    last_ctrl_c = 0
+    try:
+        while not closed.is_set():
+            if not msvcrt.kbhit():
+                time.sleep(0.05)
+                continue
+
+            ch = msvcrt.getwch()
+            if ch == '\x03':  # Ctrl+C
+                now = time.time()
+                if now - last_ctrl_c < 2:
+                    break
+                last_ctrl_c = now
+                ws.send(b'\x03', opcode=ws_module.ABNF.OPCODE_BINARY)
+            elif ch == '\r':  # Enter
+                ws.send(b'\n', opcode=ws_module.ABNF.OPCODE_BINARY)
+            elif ch == '\x08':  # Backspace
+                ws.send(b'\x7f', opcode=ws_module.ABNF.OPCODE_BINARY)
+            elif ch in ('\x00', '\xe0'):  # Special key prefix
+                code = ord(msvcrt.getwch())
+                escape = _WINDOWS_KEY_MAP.get(code)
+                if escape:
+                    ws.send(escape, opcode=ws_module.ABNF.OPCODE_BINARY)
+            else:
+                ws.send(ch.encode('utf-8'), opcode=ws_module.ABNF.OPCODE_BINARY)
+    except (ws_module.WebSocketConnectionClosedException, OSError):
+        pass
+
+
+def _shell_input_loop_unix(ws, closed):
+    import sys
+    import os
+    import tty
+    import termios
+    import time
+    import websocket as ws_module
+
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+    last_ctrl_c = 0
+    try:
+        tty.setraw(fd)
+        while not closed.is_set():
+            ch = os.read(fd, 1)
+            if not ch:
+                break
+            if ch == b'\x03':  # Ctrl+C
+                now = time.time()
+                if now - last_ctrl_c < 2:
+                    break
+                last_ctrl_c = now
+            # Pass through everything (arrow keys already come as escape sequences)
+            ws.send(ch, opcode=ws_module.ABNF.OPCODE_BINARY)
+    except (ws_module.WebSocketConnectionClosedException, OSError):
+        pass
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+
+def _execute_command_on_instance(scm_url, headers, cookies, command, args=None, working_directory=None):
     from azure.cli.core.util import should_disable_connection_verify
     import requests
-    
-    # Build the exec endpoint URL
+
     exec_url = f"{scm_url}/exec/execute"
-    
-    # Build request body
+
     body = {"Command": command}
+    if args:
+        body["Args"] = args
     if working_directory:
         body["WorkingDirectory"] = working_directory
-    
-    # Make the request
+
     response = requests.post(
         exec_url,
         json=body,
         headers=headers,
         cookies=cookies,
         verify=not should_disable_connection_verify()
     )
-    
-    # Handle response
+
     if response.status_code == 202:
-        # Success - command accepted (no response body expected)
         return None
     else:
-        # Error - response contains JSON with ErrorMessage
         raise CLIError(f"Command execution failed with status code {response.status_code}: {response.text}")
 
 
-def webapp_exec(cmd, resource_group_name, name, command, mode='execute', working_directory=None, instance=None, slot=None):
+def webapp_exec(cmd, resource_group_name, name, command=None, args=None, mode='execute', working_directory=None, instance=None, slot=None):
     # Validate Linux App
     webapp = _generic_site_operation(cmd.cli_ctx, resource_group_name, name, 'get', slot)
     if not webapp:
@@ -10989,29 +11120,41 @@ def webapp_exec(cmd, resource_group_name, name, command, mode='execute', working
     if not is_linux:
         raise ValidationError("Only Linux App Service Plans supported.")
 
-    # Allow mode 'execute' only
-    if mode.lower() != 'execute': 
-        raise ValidationError("Only 'execute' mode is supported currently.")
-
-    # Validate command is provided if mode is 'execute'
-    if mode.lower() == 'execute' and not command:
-        raise ValidationError("Command is required.")
+    if mode.lower() == 'execute':
+        if not command:
+            raise ValidationError("Command is required for 'execute' mode.")
+    elif mode.lower() == 'shell':
+        if instance and instance.lower() == 'all':
+            raise ValidationError("Cannot open shell on all instances. Specify a single instance or omit for a random one.")
+    else:
+        raise ValidationError("Invalid mode '{}'. Supported modes: execute, shell.".format(mode))
 
     # Get scm site and authorization
     scm_url = _get_scm_url(cmd, resource_group_name, name, slot)
     headers = get_scm_site_headers(cmd.cli_ctx, name, resource_group_name, slot)
 
-    # Get target instances if specified
-    target_instances = []
+    # Shell mode — single interactive session
+    if mode.lower() == 'shell':
+        cookies = {}
+        if instance:
+            instances = list_instances(cmd, resource_group_name, name, slot=slot)
+            instance_names = set(i.name for i in instances)
+            if instance not in instance_names:
+                raise ValidationError("Instance '{}' is not valid. Valid instances: {}".format(
+                    instance, ', '.join(sorted(instance_names))))
+            cookies['ARRAffinity'] = instance
+        _start_shell_session(scm_url, headers, cookies)
+        return None
+
+    # Resolve target instances
+    target_instances = [None]  # default: no affinity cookie, random instance
     if instance is not None:
-        # If command execution on all instances
         if instance.lower() == "all":
             instances = list_instances(cmd, resource_group_name, name, slot=slot)
             target_instances = [i.name for i in instances]
             if not target_instances:
                 raise ValidationError("No instances found for this web app.")
         else:
-            # Validate listed instances
             instances = list_instances(cmd, resource_group_name, name, slot=slot)
             requested_instances = [i.strip() for i in instance.split(',')]
             instance_names = set(i.name for i in instances)
@@ -11021,20 +11164,17 @@ def webapp_exec(cmd, resource_group_name, name, command, mode='execute', working
                     ', '.join(invalid_instances), ', '.join(sorted(instance_names))))
             target_instances = requested_instances
 
-        # Execute command on target instances
-        results = []
-        for target in target_instances if target_instances else [None]:
-            cookies = {}
-            if target is not None:
-                cookies['ARRAffinity'] = target
+    # Execute command on target instances
+    results = []
+    for target in target_instances:
+        cookies = {}
+        if target is not None:
+            cookies['ARRAffinity'] = target
 
-            try:
-                result = _execute_command_on_instance(scm_url, headers, cookies, command, working_directory)
-                results.append({'instance': target or 'default', 'status': 'success', 'result': result})
-            except CLIError as e:
-                results.append({'instance': target or 'default', 'status': 'failed', 'error': str(e)})
-
-        return results if len(results) > 1 else results[0] if results else None
-
-        
+        try:
+            result = _execute_command_on_instance(scm_url, headers, cookies, command, args, working_directory)
+            results.append({'instance': target or 'default', 'status': 'success', 'result': result})
+        except CLIError as e:
+            results.append({'instance': target or 'default', 'status': 'failed', 'error': str(e)})
 
+    return results if len(results) > 1 else results[0] if results else None