How to Use MXC CLI Command Override: A Complete Guide to Overriding Policy Commands

The MXC wxc-exec binary supports CLI command override by accepting positional arguments after a -- separator, replacing the process.commandLine defined in the policy JSON file with the user-supplied command.

The MXC CLI command override feature in the microsoft/mxc repository allows you to dynamically replace the command specified in a policy file when running the wxc-exec binary. This capability enables ad-hoc command execution within MXC sandboxes without modifying the underlying JSON policy configuration. According to the source code in src/core/wxc/src/main.rs, the override mechanism intercepts command-line tokens, validates execution context, and replaces the script_code field in the execution request.

How the CLI Command Override Mechanism Works

The wxc-exec binary defines a dedicated argument parser that captures trailing tokens as the override command. In src/core/wxc/src/main.rs (lines 12–20), the Cli struct includes a command field marked with #[arg(last = true, allow_hyphen_values = true)]:

/// Command to run inside the container, overriding `process.commandLine`
/// from the policy. The command must follow a `--` separator …
/// When provided, `process.commandLine` in the policy file becomes
/// optional and is overridden.
#[arg(value_name = "COMMAND", last = true, allow_hyphen_values = true)]
command: Vec<String>,

To trigger the override, append -- after the configuration file path, followed by the command and its arguments. The parser collects these tokens into cli.command as a Vec<String>, preserving hyphenated values and multi-token commands.

Detecting Valid Command Overrides

Before processing, MXC validates whether an override was supplied and whether the execution context supports it. The has_cli_command function (lines 60–62) performs a simple emptiness check:

fn has_cli_command(cli: &Cli) -> bool {
    !cli.command.is_empty()
}

However, the system restricts overrides to state-aware execution requests in the Exec phase only. As implemented in lines 98–100, attempting to apply an override to other phases triggers an error:

if parsed.phase != Phase::Exec {
    return Err(MxcError::malformed_request(
        "CLI command override is only supported for state-aware exec requests",
    ));
}

Converting Commands for Target Sandboxes

Once validated, the raw token vector must be converted into a platform-appropriate command-line string. The command_override_from_cli function (lines 80–88) delegates this conversion to cmdline_from_argv_for_context:

fn command_override_from_cli(
    cli: &Cli,
    context: CommandLineContext,
) -> Result<Option<String>, CommandLineError> {
    if cli.command.is_empty() {
        Ok(None)
    } else {
        cmdline_from_argv_for_context(&cli.command, context).map(Some)
    }
}

cmdline_from_argv_for_context, defined in src/core/wxc_common/src/cmdline.rs, adapts the command syntax based on the target backend:

• Windows CreateProcess: Formats arguments for direct API consumption (e.g., Hyperlight).
• Windows command processor: Escapes shell-specific characters.
• POSIX shell: Joins tokens for /bin/sh -c execution (e.g., WSLC).

Applying the Override to the Execution Request

The final stage replaces the policy-defined command in the ExecutionRequest struct. The apply_command_override function (lines 11–21) overwrites the script_code field and logs the action:

fn apply_command_override(
    request: &mut ExecutionRequest,
    command_override: Option<&str>,
    logger: &mut Logger,
) {
    if let Some(cmd) = command_override {
        if !request.script_code.is_empty() {
            let _ = writeln!(
                logger,
                "Overriding policy process.commandLine with CLI command: {}",
                cmd
            );
        }
        request.script_code = cmd.to_string();
    }
}

This function is invoked in the main execution path (lines 666–676) after resolving the appropriate command-line context:

let command_override = match command_override_context_for_state_aware(&parsed, has_command_override) {
    // … resolve appropriate context …
    .map(|ctx| command_override_from_cli(&cli, ctx))?,
};
apply_command_override(&mut request, command_override.as_deref(), &mut logger);

Practical Examples of MXC CLI Command Override

Python One-Liner Execution

Override the policy command to execute a Python script inline:

wxc-exec policy.json -- python -c "print('hello')"

The tokens python, -c, and "print('hello')" replace the JSON-defined process.commandLine.

POSIX Shell with Special Characters

When targeting Linux backends (e.g., WSLC), the command processes through /bin/sh -c:

wxc-exec policy.json -- echo 'safe&whoami'

cmdline_from_argv_for_context ensures proper shell escaping for the POSIX context.

Windows CreateProcess Backend

For Hyperlight and similar Windows sandboxes, commands execute via the CreateProcess API:

wxc-exec policy.json -- powershell -Command "Get-Process"

The override converts the token vector into a format suitable for Windows process creation.

Default Policy Execution (No Override)

Running wxc-exec without trailing arguments preserves the policy behavior:

wxc-exec policy.json

MXC reads process.commandLine from policy.json and populates request.script_code without modification.

Summary

• Syntax: Append -- followed by command tokens after the policy file path to activate the MXC CLI command override.
• Validation: Overrides require state-aware execution requests in the Exec phase; other phases return a malformed request error.
• Conversion: The command_override_from_cli function in src/core/wxc/src/main.rs delegates to cmdline_from_argv_for_context to generate platform-specific syntax for Windows or POSIX backends.
• Application: The apply_command_override function replaces the script_code field in the ExecutionRequest struct, logging the policy override before sandbox launch.
• Source Files: Core logic resides in src/core/wxc/src/main.rs with shared parsing utilities in src/core/wxc_common/src/cmdline.rs.

Frequently Asked Questions

What is the exact syntax for MXC CLI command override?

Follow the configuration file path with a double hyphen (--) separator, then provide the command and arguments as positional tokens. For example: wxc-exec policy.json -- /bin/bash -c "echo test". The -- token distinguishes override arguments from MXC-specific flags.

Can I use CLI command override with any MXC execution phase?

No. According to the validation logic in src/core/wxc/src/main.rs (lines 98–100), CLI command override is restricted to state-aware execution requests in the Exec phase. Attempting to apply an override to other phases results in a malformed_request error.

How does MXC handle special characters in overridden commands?

The cmdline_from_argv_for_context function in src/core/wxc_common/src/cmdline.rs handles platform-specific escaping. For POSIX contexts, it prepares commands for shell interpretation; for Windows CreateProcess contexts, it formats arguments according to Windows command-line parsing rules, ensuring special characters are correctly escaped.

Which source files contain the command override implementation?

The primary implementation resides in src/core/wxc/src/main.rs, containing argument parsing, validation, and application logic. Shared command-line formatting utilities are in src/core/wxc_common/src/cmdline.rs. State-aware request dispatching (which enforces the Exec phase restriction) is handled in src/core/wxc_common/src/state_aware_dispatch.rs, and the ExecutionRequest model definition is in src/core/wxc_common/src/models.rs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}