Add az webapp exec command for Linux web apps (shell + execute)

Author: vageorge00

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

@@ -1971,6 +1971,44 @@
     text: az webapp create-remote-connection --name MyWebApp --resource-group MyResourceGroup
 """
 
+helps['webapp exec'] = """
+type: command
+short-summary: Interact with a Linux web app container via command execution or an interactive shell session.
+long-summary: >
+    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: Run a direct command in the container
+    text: >
+        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 -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 --mode execute --command pwd --instance all
+  - name: Execute a command on a deployment slot
+    text: >
+        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'] = """
 type: command
 short-summary: Delete a web app.

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

@@ -1605,3 +1605,21 @@ def load_arguments(self, _):
         c.argument('environment_name', help="Name of the environment of static site")
     with self.argument_context('staticwebapp enterprise-edge') as c:
         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 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/commands.py

@@ -134,6 +134,7 @@ def load_command_table(self, _):
         g.custom_command('up', 'webapp_up', exception_handler=ex_handler_factory(), validator=validate_webapp_up,
                          deprecate_info=g.deprecate(redirect='webapp create and webapp deploy'))
         g.custom_command('ssh', 'ssh_webapp', exception_handler=ex_handler_factory(), is_preview=True)
+        g.custom_command('exec', 'webapp_exec', exception_handler=ex_handler_factory(), is_preview=True)
         g.custom_command('list', 'list_webapp', table_transformer=transform_web_list_output)
         g.custom_show_command('show', 'show_app', table_transformer=transform_web_output)
         g.custom_command('delete', 'delete_webapp')

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

@@ -12883,3 +12883,234 @@ def _compute_checksum(input_bytes):
         logger.info("Computing the checksum of the file failed with exception:'%s'", ex)
 
     return file_hash
+
+
+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
+
+    exec_url = f"{scm_url}/exec/execute"
+
+    body = {"Command": command}
+    if args:
+        body["Args"] = args
+    if working_directory:
+        body["WorkingDirectory"] = working_directory
+
+    response = requests.post(
+        exec_url,
+        json=body,
+        headers=headers,
+        cookies=cookies,
+        verify=not should_disable_connection_verify()
+    )
+
+    if response.status_code == 202:
+        return None
+    else:
+        raise CLIError(f"Command execution failed with status code {response.status_code}: {response.text}")
+
+
+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:
+        raise ResourceNotFoundError("Unable to find resource '{}' in ResourceGroup '{}'.".format(name, resource_group_name))
+
+    is_linux = webapp.reserved
+    if not is_linux:
+        raise ValidationError("Only Linux App Service Plans supported.")
+
+    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)
+
+    # 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 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:
+            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)
+            invalid_instances = [inst for inst in requested_instances if inst not in instance_names]
+            if invalid_instances:
+                raise ValidationError("The following instances are not valid for this webapp: {}. Valid instances: {}".format(
+                    ', '.join(invalid_instances), ', '.join(sorted(instance_names))))
+            target_instances = requested_instances
+
+    # 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, 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