Microsoft PowerToys version

0.94

Installation method

Dev build in Visual Studio

Area(s) with issue?

Awake

Steps to reproduce

The discrepancy

There is a multi-way conflict in the default behaviour of Awake's --display-on flag, which controls whether the user's screen remains on during the keep-awake period:

1. When parsing the command line, a default of true is used:

    Option<bool> displayOption = new(_aliasesDisplayOption, () => true, Resources.AWAKE_CMD_HELP_DISPLAY_OPTION)
    {
        Arity = ArgumentArity.ZeroOrOne,
        IsRequired = false,
    };

2. Contradicting the CLI behaviour, the official documentation states:

While PowerToys Awake can keep the computer awake indefinitely or temporarily, in its default state the displays connected to the machine will turn off even if the computer stays awake.

(Emphasis mine.)

3. The default settings file (and therefore the default for if Awake is started via PowerToys) has keepDisplayOn set to false.

This creates a confusing and inconsistent user experience, as the application's default behaviour changes depending on how it is launched.

Proposed solution

This is somewhat nuanced because I realise that some users may be inadvertently relying on the current undocumented behaviour when running Awake via the command line. A phased approach may be best.

Step 1 (Immediate, non-breaking): update the documentation

The documentation should be updated to reflect the current state of the application, clarifying the true default when Awake is used via the command line. A note could be added to signal that this behaviour will be changed in a future version.

Step 2 (Breaking change): change the CLI default to false

I recommend changing the command line parser's default to false.

Justification

I recognise this is a breaking change, but I think it's correct for the following reasons:

• It aligns with standard CLI conventions. The current implementation violates the "principle of least astonishment" for command line users. For boolean flags, the long-standing convention is that the presence of a flag implies true and its absence implies the default "safe" state of false. Awake's CLI handling correctly handles the flag's presence, but does the opposite of what is expected when the flag is absent by defaulting to true. Changing to a default of false would fix the logical flaw and improve predictability.
• We would have consistent behaviour between both CLI and "PowerToys-initiated" modes of operation.
• Environmental concerns: Defaulting to false in both modes is more environmentally friendly.
• It promotes users being explicit if they want their systems to use more power, and makes the intent of scripts more apparent. Currently, it is unclear whether PowerToys.Awake.exe --time-limit 3600 keeps the display on or not; the user would have to read the code and ignore the documentation to discern the current behaviour.

Mitigating the impact for existing users

The key here is good communication about the intended change.

In the release notes, we could say something like:

"The default behaviour of Awake has changed when running it via the command line. It no longer keeps the screen on by default. To retain the old behaviour, add the --display-on true argument to your scripts. This change is because of an inconsistency between the CLI and non-CLI modes of Awake, and both now perform identically."

We should also consider gathering user feedback on this proposed change. The primary edge case I can think of is a kiosk-style installation where a script relies on the current undocumented default behaviour to keep the display active.

Priority and severity

This affects users who script Awake and do not explicitly set --display-on. It causes their screens to remain on instead of respecting the system's power plan. This is inconvenient, inconsistent, and wastes power, but is not a crash bug, and is easy for a user to remedy once informed. Proposed Medium severity.

✔️ Expected Behavior

When running Awake via the command line, the default behaviour for the --display-on flag should be consistent with the documentation.

❌ Actual Behavior

The behaviour is the opposite of the documentation, and the system's display is kept on while the keep-awake mode is active.

Additional Information

No response

Other Software

No response