Cli-microsoft365: Enhancement: deprecation warning should be written to stderr instead of stdout

[alexandair]

Description

Command 'accesstoken get' is deprecated, but it still works and outputs wrongly the warning message in stdout stream and invalidates the token.

Steps to reproduce

$ token=$(o365 accesstoken get --resource https://graph.microsoft.com)

$ echo $token
Command 'accesstoken get' is deprecated. Please use 'util accesstoken get' instead eyJ0eXAiOiJKV1QiLCJub25jZSI6ImVKSnlKTkFzNlI3N1libTJWaTFWVExoOXp1dFE1djA1YUxtc3JhcmVvLUkiLCJhbGciOiJSUzI1NiIsIng1dCI6IkN0VHVoTUpt...

Expected result

$ echo $token
eyJ0eXAiOiJKV1QiLCJub25jZSI6ImVKSnlKTkFzNlI3N1libTJWaTFWVExoOXp1dFE1djA1YUxtc3JhcmVvLUkiLCJhbGciOiJSUzI1NiIsIng1dCI6IkN0VHVoTUpt...

Actual result

$ echo $token
Command 'accesstoken get' is deprecated. Please use 'util accesstoken get' instead eyJ0eXAiOiJKV1QiLCJub25jZSI6ImVKSnlKTkFzNlI3N1libTJWaTFWVExoOXp1dFE1djA1YUxtc3JhcmVvLUkiLCJhbGciOiJSUzI1NiIsIng1dCI6IkN0VHVoTUpt...

[waldekmastykarz]

This is indeed the current behavior. Would you say that outputting deprecation messages to stderr would be a better choice?

[alexandair]

The current behavior breaks scripts. So, the message needs to go into some stream other than stdout. I know that "accesstoken get" is depricated, but it still works and it's actually mentioned in help as an alias for "util acceestoken get". We need to assume that people will continue to use it.

[waldekmastykarz]

We have a number of choices how we could inform people about deprecation. Our goal is to give everyone enough time to update their scripts before we remove the command in the next major version.

We could print the deprecation in stderr rather than stdout but I'm not sure if that would change the exit code which might be undesirable as well. We could show the message only in verbose or debug mode, with the risk that it's not seen and people are surprised by the command being removed. Does any of these options seem better than what we have now? Do you have other ideas that we should consider to communicate deprecation?

[alexandair]

I've had a conversation with the Azure CLI team. They are printing the deprecation and other warning messages to stderr.
I would suggest to do the same in Office 365 CLI.

[waldekmastykarz]

Thank you for checking with them and I appreciate your help. We'll adjust accordingly to follow the az cli behavior.

[alexandair]

Azure CLI team has shared the doc about deprecating commands and arguments and some links to code examples (I know they are developing in Python and Office 365 CLI is based on Node.js, but it still might be useful, I hope.)

A doc about deprecating commands and arguments.

"Our CLI repo depends on knack, which is a basic command-line interface framework. Deprecated information is handled in knack. Azure CLI output it to stderr for normal commands and to stdout for help commands."

You can reference the code here:

Output to stderr for normal commands
Output to stdout for help commands

[waldekmastykarz]

Thank you for the pointer. That's helpful 👍

[waldekmastykarz]

We're working on removing Vorpal which gives us more control about CLI's output. Once we've closed #1737, we'll be able to look into this issue.

[waldekmastykarz]

We've just release a preview version where all secondary output is sent to stderr and only the main command output is sent to stdout. Once again, thank you for your suggestion @alexandair 👏