Skip to content

CLI improvements

Waldek Mastykarz edited this page Mar 21, 2019 · 12 revisions

CLI exists over a year now. Over time we picked up some things that we could improve. Here is a list of things that we could consider. Most of them are breaking changes that would lead to a v2.0 of the CLI. At this stage, it's just a list of things that we could consider. Nothing specific is planned yet.


  • ❌: breaking change
  • ✅: non-breaking change


  • ❌ align short options across commands for consistency, eg. -l, --listId vs. -i, --listId
  • ❌ review command naming: we have some deprecated names which we could clean up, but perhaps some command names can be shortened as well. In some cases we should also consider simpler names, eg. spo site groupify instead of spo site office365group set
  • ✅ update documentation to consistently refer to SPSite and SPWeb as site collection and site (rather than site and subsite, subweb or anything alike)
  • ❌ from the command name, remove the API used to communicate with particular service, eg. azmgmt flow list would become flow list. The fact that we use the Azure Management Service to communicate with the Flow API is a technicality irrelevant to CLI users that unnecessarily bothers them and requires them to know which API we use for which service
  • ❌ have users connect to a service instead of the API we use to communicate with that service, eg. flow login and flow list instead of azmgmt login and azmgmt flow list. This way we abstract away the internal implementation which isn't relevant to users and prevent breaking changes in case our implementation needs to change (for example from AAD Graph to Microsoft Graph). The downside is that users will need to login multiple times even if behind the scenes the CLI uses the same API (eg. Microsoft Graph). This shortcoming could be however addressed using the next point
  • ❌ have users login once in the CLI and reuse the login information for all services, eg. o365 login and then use the AAD Multi-Resource Refresh Tokens for connecting to other services. Upside: no need to login separately for each service. Downside: not possible to login to different services using different accounts. Consideration needed: communication with SharePoint complicates things because it requires the user to specify SharePoint URL. So if initially the user would connect to communicate with Microsoft Graph and would then want to use SharePoint commands, they would fail. An option could be to do either something like o365 login [url] (optional URL parameter) or o365 spo login <url>, which could be used only to set the tenant URL without issuing a login prompt (re-consider command name).
  • ✅ centralize issuing http requests. This will allow us to simplify building commands, ensure consistency across all commands in the CLI and implement changes in the future if necessary
  • ✅ we should make all requests use gzip compression to minimize the amount of data going over the wire to improve the performance of operations that work with big request/response payloads
  • ✅ add support for handling throttling
  • ✅ replace custom logging of requests and responses in debug mode with the standard logging provided by the request module (require('request').debug = true). This will simplify building commands and allow logging across all requests

Questions, comments, suggestions? Let's talk @

Clone this wiki locally
You can’t perform that action at this time.