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

> Learn how to use MXC CLI command override with wxc-exec. Easily replace policy commands by providing arguments after the -- separator. Master MXC command overrides today.

- Repository: [Microsoft/mxc](https://github.com/microsoft/mxc)
- Tags: how-to-guide
- Published: 2026-06-07

---

**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`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/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)]`:

```rust
/// 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:

```rust
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:

```rust
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`:

```rust
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`](https://github.com/microsoft/mxc/blob/main/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:

```rust
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:

```rust
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:

```bash
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`:

```bash
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:

```bash
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:

```bash
wxc-exec policy.json

```

MXC reads `process.commandLine` from [`policy.json`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/src/core/wxc/src/main.rs) with shared parsing utilities in [`src/core/wxc_common/src/cmdline.rs`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/src/core/wxc_common/src/state_aware_dispatch.rs)**, and the `ExecutionRequest` model definition is in **[`src/core/wxc_common/src/models.rs`](https://github.com/microsoft/mxc/blob/main/src/core/wxc_common/src/models.rs)**.