{"id":17722,"date":"2007-05-16T14:19:50","date_gmt":"2007-05-16T22:19:50","guid":{"rendered":"http:\/\/devblogs.microsoft.com\/powershell\/?p=17722"},"modified":"2019-05-16T14:22:34","modified_gmt":"2019-05-16T22:22:34","slug":"microsoft-command-line-standard","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell\/microsoft-command-line-standard\/","title":{"rendered":"Microsoft Command Line Standard"},"content":{"rendered":"

The Microsoft Command Line Standard is now published HERE. I wrote the draft of this document (Dean Tsaltas did the editing) to define the operational standard for any command line tool independent of the technology that is implemented in. Clearly the preferred implementation is Windows PowerShell. There is no cheaper way to implement the standard than by providing PowerShell Cmdlets (because the PowerShell engine implements the standards for you). That said, as long as you implement the standards in this document, you’ll be delivering our common customers a common experience and that is what counts at the end of the day.\nI really like the structure of the document because it provides an introduction and then does multiple passes on the guidance with progressively more information. The first pass is very pithy and is meant to fit one or two pieces of paper that you can keep next to your keyboard. The next pass provides details about the guidance. The last pass is a series of Appendixes with very concrete detailed information about the requirements. I hope you like the structure.\nHere is the Introduction and the first pass of the guidelines so you get a feel for the content.\nNOTE: PowerShell V1.0 implements almost all of this standard but not 100% (in particular the support for TCSV is absent in V1). (“To ship is to choose.”)\n Joel pointed out (in a comment and then on his BLOG) a mismatch between the standard verbs in this document and the ones we posted earlier on this blog (HERE). The command line standard needs to be updated. We thought it was up to date but we were wrong – apologizes. We’ll update it in a couple of weeks with these and the new verbs as well. 10,000 thanks to Joel for pointing this out! Also – thanks to jmanning for pointing out my typo (now corrected).\nCheers!\nJeffrey Snover [MSFT]\nWindows Management Partner Architect\nVisit the Windows PowerShell Team blog at: http:\/\/blogs.msdn.com\/PowerShell\nVisit the Windows PowerShell ScriptCenter at: http:\/\/www.microsoft.com\/technet\/scriptcenter\/hubs\/msh.mspx\nIntroduction\nIn order to provide a consistent, composable user experience, across a wide range of commands, this document provides guidance on:<\/p>\n

1.\nConsistent verb and parameter naming conventions.\n2.\nConsistent command syntax\n3.\nCommon behaviors.\n4.\nConsistent error messages and exit codes.\n5.\nSchema-enhanced data-streams and formatting.\nThis document builds upon the traditional command line compositional model. That traditional model had the following three characteristics:<\/p>\n

\u2022\nCommands are standalone processes that accept a sequence of text parameters (that might have been typed on a command line), accept data from STDIN, write results to STDOUT, write error messages to STDERR, and exit with a code indicating success or failure.\n\u2022\nCommands are focused on performing specific operations. The user composes a sequence of commands to implement a task or user-scenario.\n\u2022\nComposition is achieved by picking out the important elements of one command’s output and providing as parameters or data to another command.\nIf you create command-line tools that have these three characteristics, you will have achieved UNIX level interoperability. Building upon that, there are Enhanced and Optimal levels of interoperability. This document primarily focuses on the Optimal level of interoperability, but guidelines for Enhanced interoperability are available in Appendix H \u2013 Enhanced Interoperability Guidance . Enhanced interoperability provides a stepping stone for existing commands. As a first step, you can elevate them to Enhanced interoperability on the way to achieving Optimal interoperability.\nThis document is structured as a progressive disclosure: The Summary List of Guidance section is a two page summary. The Details section provides details and background for each guideline in the summary. The Appendixes provide reference material necessary to implement the guidelines.\nSummary List of Guidance\nCommand Names\nRequired:<\/p>\n

\u2022\nCommand names must be well-formed names consisting of a noun and a verb in the form: verb-noun.\nVerbs\nRequired:<\/p>\n

\u2022\nCommands must use verbs from the list of standard verbs in Appendix A.\nRecommended:<\/p>\n

\u2022\nDevelopers should implement as many verbs in the defined Verb groupings (Verb Sets) as makes sense for their feature.\nNoun Names\nRecommended:<\/p>\n

\u2022\nCommands should avoid using the noun names Windows PowerShell has reserved (See Section 3.3 Nouns).\n\u2022\nCommands should use their product or feature name (or abbreviation) to prefix their noun.\nConsistent Syntax\nRequired:<\/p>\n

\u2022\nCommands must use the “-” character for parameter delimitation; a colon (:) or whitespace to separate the parameter name and its arguments and a comma (,) to separate multiple values within an argument.\nInput\nRequired:<\/p>\n

\u2022\nCommands must accept text or CliXml input (using CliXmlDataStream Schema defined in Appendix E \u2013 Standardized Data Schema ) in STDIN.\nRecommended:<\/p>\n

\u2022\nCommands should accept Typed-CSV (TCSV) input in STDIN.\n\u2022\nCommands should provide a \u2013InputFormat [XML | TCSV | TEXT ] parameter to allow the user to identify what type of data will be coming in on STDIN.\nParameters\nRequired:<\/p>\n

\u2022\nCommands must support -?, \u2013Help, -Version, \u2013Verbose, and \u2013Debug for all commands.\n\u2022\nCommands must support \u2013WhatIf and -Confirm for any operation which has a side-effect.\n\u2022\nCommands must support \u2013ErrorAction to determine behavior when errors occur.\n\u2022\nParameter names must be case-insensitive.\n\u2022\nPasswords must not be accepted as a parameter argument.\nRecommended:<\/p>\n

\u2022\nCommands should choose parameters from the standards specified in Appendix B.\n\u2022\nCommands should support \u2013SelectProperty to specify which properties to output on STDOUT.\n\u2022\nCommands should allow the user to specify just enough of a parameter name to disambiguate it from other parameter names and provide a one or two character shortcut to specify a verbose parameter name.\n\u2022\nCommands should document their parameter names using Pascal casing rules (capitalize the start of every word).\nTargeting\nRecommended:<\/p>\n

\u2022\nCommands should use wildcard expansion for input globbing (Appendix D – Globbing).\n\u2022\nCommands should use common parameters for specifying the target of a command (e.g. \u2013Name, -ID, -File, -ComputerName) .\n\u2022\nCommands should support multi-value targets as well as the \u2013Include and \u2013Exclude parameters.\n\u2022\nCommands should support the \u2013Filter parameter to specify a domain-specific query or filter.\nOutput Formatting\nRequired:<\/p>\n

\u2022\nOutput must be written using the logic illustrated in Appendix I: Win32 code to write output to properly address globalization requirements.\n\u2022\nCommands must support the \u2013OutputFormat parameter to allow users to specify their desired format and the \u2013OutputPreamble to configure schema enhanced data streams\n\u2022\nCommands must use the value of the environmental variable CliDataStreamSchema when \u2013OutputFormat is not specified.\n\u2022\nCommands must support at least one format of schema-enhanced dataStreams (TCSV or CliXml).\nRecommended:<\/p>\n

\u2022\nCommands should support CliXml Appendix F \u2013 CliXmlDataStream Data Schema and Appendix K \u2013 Error Record Schema and tag which stream (DEBUG, ERROR, OUTPUT VERBOSE, or WARNING) the data came from. Commands must output CliXml when the environmental variable CliXmlStreams is set to TRUE. Commands must output XML using CliXmlDataStream schema.\n\u2022\nCommands should support other XML schemas where there is a community of tools that will consume that output (e.g. CimXml).\nExit, Errors, and Others\nRequired:<\/p>\n

\u2022\nError messages (as well as VERBOSE and DEBUG messages) must be written to STDERR.\n\u2022\nCommands must terminate with an exit code indicating success (0) or failure (non-zero).\nRecommended:<\/p>\n

\u2022\nCommands should use the exit codes and standardized error messages defined in Appendix C. Augment those standardized error messages with specific detailed error messages.\n\u2022\nCommands should tell the user (on STDERR) the Syntax of a command if they specify a syntactically invalid command.<\/p>\n","protected":false},"excerpt":{"rendered":"

The Microsoft Command Line Standard is now published HERE. I wrote the draft of this document (Dean Tsaltas did the editing) to define the operational standard for any command line tool independent of the technology that is implemented in. Clearly the preferred implementation is Windows PowerShell. There is no cheaper way to implement the standard […]<\/p>\n","protected":false},"author":2,"featured_media":13641,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[],"class_list":["post-17722","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell"],"acf":[],"blog_post_summary":"

The Microsoft Command Line Standard is now published HERE. I wrote the draft of this document (Dean Tsaltas did the editing) to define the operational standard for any command line tool independent of the technology that is implemented in. Clearly the preferred implementation is Windows PowerShell. There is no cheaper way to implement the standard […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/17722","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/comments?post=17722"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/17722\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media\/13641"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media?parent=17722"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/categories?post=17722"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/tags?post=17722"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}