Microsoft Command Line Standard

Microsoft Command Line Standard

  • Comments 16

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.

I 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.

Here is the Introduction and the first pass of the guidelines so you get a feel for the content.

NOTE: 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.")

<UPDATE 5/17 -jps>  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).

Cheers!

Jeffrey Snover [MSFT]
Windows Management Partner Architect
Visit the Windows PowerShell Team blog at: http://blogs.msdn.com/PowerShell
Visit the Windows PowerShell ScriptCenter at: http://www.microsoft.com/technet/scriptcenter/hubs/msh.mspx

Introduction

In order to provide a consistent, composable user experience, across a wide range of commands, this document provides guidance on:

1.

Consistent verb and parameter naming conventions.

2.

Consistent command syntax

3.

Common behaviors.

4.

Consistent error messages and exit codes.

5.

Schema-enhanced data-streams and formatting.

This document builds upon the traditional command line compositional model. That traditional model had the following three characteristics:

Commands 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.

Commands are focused on performing specific operations. The user composes a sequence of commands to implement a task or user-scenario.

Composition is achieved by picking out the important elements of one command's output and providing as parameters or data to another command.

If 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 – 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.

This 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.

Summary List of Guidance

Command Names

Required:

Command names must be well-formed names consisting of a noun and a verb in the form: verb-noun.

Verbs

Required:

Commands must use verbs from the list of standard verbs in Appendix A.

Recommended:

Developers should implement as many verbs in the defined Verb groupings (Verb Sets) as makes sense for their feature.

Noun Names

Recommended:

Commands should avoid using the noun names Windows PowerShell has reserved (See Section 3.3 Nouns).

Commands should use their product or feature name (or abbreviation) to prefix their noun.

Consistent Syntax

Required:

Commands 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.

Input

Required:

Commands must accept text or CliXml input (using CliXmlDataStream Schema defined in Appendix E – Standardized Data Schema ) in STDIN.

Recommended:

Commands should accept Typed-CSV (TCSV) input in STDIN.

Commands should provide a –InputFormat [XML | TCSV | TEXT ] parameter to allow the user to identify what type of data will be coming in on STDIN.

Parameters

Required:

Commands must support -?, –Help, -Version, –Verbose, and –Debug for all commands.

Commands must support –WhatIf and -Confirm for any operation which has a side-effect.

Commands must support –ErrorAction to determine behavior when errors occur.

Parameter names must be case-insensitive.

Passwords must not be accepted as a parameter argument.

Recommended:

Commands should choose parameters from the standards specified in Appendix B.

Commands should support –SelectProperty to specify which properties to output on STDOUT.

Commands 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.

Commands should document their parameter names using Pascal casing rules (capitalize the start of every word).

Targeting

Recommended:

Commands should use wildcard expansion for input globbing (Appendix D - Globbing).

Commands should use common parameters for specifying the target of a command (e.g. –Name, -ID, -File, -ComputerName) .

Commands should support multi-value targets as well as the –Include and –Exclude parameters.

Commands should support the –Filter parameter to specify a domain-specific query or filter.

Output Formatting

Required:

Output must be written using the logic illustrated in Appendix I: Win32 code to write output to properly address globalization requirements.

Commands must support the –OutputFormat parameter to allow users to specify their desired format and the –OutputPreamble to configure schema enhanced data streams

Commands must use the value of the environmental variable CliDataStreamSchema when –OutputFormat is not specified.

Commands must support at least one format of schema-enhanced dataStreams (TCSV or CliXml).

Recommended:

Commands should support CliXml Appendix F – CliXmlDataStream Data Schema and Appendix K – 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.

Commands should support other XML schemas where there is a community of tools that will consume that output (e.g. CimXml).

Exit, Errors, and Others

Required:

Error messages (as well as VERBOSE and DEBUG messages) must be written to STDERR.

Commands must terminate with an exit code indicating success (0) or failure (non-zero).

Recommended:

Commands should use the exit codes and standardized error messages defined in Appendix C. Augment those standardized error messages with specific detailed error messages.

Commands should tell the user (on STDERR) the Syntax of a command if they specify a syntactically invalid command.

Leave a Comment
  • Please add 6 and 8 and type the answer here:
  • Post
  • This is a very useful document. In my opinion this would have been even more useful if it had been available as a downloadable doc as well

  • Tip/Trick: Supporting Full Screen Mode with Silverlight Microsoft Command Line Standard New "Orcas" Language

  • Looks like some of the old "official" verbs are gone ... (ie: Write, Read ...

    http://blogs.msdn.com/powershell/archive/2006/04/25/583257.aspx) should we consider renaming things to match the standard, or do we consider it "too late"?  The PowerShell Community Extensions, for instance, has shipped a whole bunch of Write- and Out- commands ...

  • I find a typo!

    s/To ship is the choose/To ship is to choose/

    :)

    One thing I'd fix up in the actual doc is that for G H and I, it's Appendix x: title and the others are Appendix x - title

    Thanks for the doc - it'll help to at least cut short a lot of the debates on how command-line interfaces should look, and in particular it'll help seal the deal for those of us trying to push our teams more heavily into cmdlets :)

    Good work, jps!

  • I *like* "To ship is the choose"!

  • So I had mentioned this on the PSCX forums ( http://www.codeplex.com/PowerShellCX/Thread/View.aspx?ThreadId=10423 ) and Keith Hill said "The omission of 'Out' as a standard verb has to be incorrect." ... and I wondered if he's right, or if all the "out" verbs ought to be migrated to ... "write" or something.

    Also, "Where" is mentioned as an obsolete version of "Resolve" ... is that for real?  I mean, will PowerShell consider changing (and aliasing, one presumes) Where-Object to Resolve-Object to meet this spec?

  • Oops, Write isn't in the list either ... I guess Out-Printer would have to be ... (*drumroll please*) Add-ToPrinter (since "Add" replaces "Write" which is clearly the only logical replacement for Out in that command).

    Yeah ... so ... I think I agree with Keith.

  • You can name it whatever you want, but if you are looking for consistency I'd start here: [link]

  • What ever happened to updating this list?

  • We are reviewing some proposed changes now and expect to update the list.  We may wait a while to publish the updates.  The issue is that as a bunch of teams start using PowerShell, they are asking for changes.  We want to keep the list up to date but we don't want it to change too frequently either.  We'll probably publish an update with a month or two.

    Jeffrey Snover [MSFT]

    Windows Management Partner Architect

    Visit the Windows PowerShell Team blog at:    http://blogs.msdn.com/PowerShell

    Visit the Windows PowerShell ScriptCenter at:  http://www.microsoft.com/technet/scriptcenter/hubs/msh.mspx

  • The Microsoft PowerShell team published an important standard: Microsoft Command Line Standard. As PM...

  • Ping! Guess what I still want. :)

  • I've just come across these standards, and I'm a bit horrified. To me these standards are over-engineered - I would never use them.

    I'll run through a few criticisms in document order speaking from the perspective of a developer of a cli app.

    Structured parameters need some explaination: e.g. a set - do the quotes go around the entries or around the whole set. nExample8 indicates it's around the set, and that my users need to escape all commas in strings somehow.

    Input formats: Why should my cli need to know how to accept CliXML input (and csv)? My cli accepts input in *it's* specified format. It will explain what this is in its help. If you want to give it something else, pipeline a transform.

    CliXML seems a bad idea - I would expect to be able to use a standard set of streams the OS , not serialise them all to one stream.

    Required Parameters:

    -Help is useful.

    Version is in the exe header.

    -Verbose and -Debug are not appropriate for all commands; what about other debug-levels? Standard seems to be debug, info, warn, error nowadays.

    Implementing -WhatIf and -Confirm are ridiculous demands to make of consumers of the standards.

    -ErrorAction should be handled by the callee.

    -SelectProperty: Again, transform the output.

    Minimalist parameters, let me choose what I support - and I will let the user know exactly what I support. Smallest unambiguous abbreviation will cause major problems if new parameters added to later versions.

    The output hoop-jumping should not be my commands concern. It will output a stream of bytes to stdout in the format specified in its help file. If this isn't unicode the docu will say and consumers can transform if they need to.

    -OutputFormat and -OutputPreamble again aren't my concern, this is for the user to transform. My outputstream format is my concern. I may use XML or TCSV. I may use JSON. But I'm only going to write the code to produce one format. As for an environment variable to control my output format? No thanks.

    Personally (although I don't like to dictate) I'd make writing a usage to stderror if the parameters aren't correct required.

    The help XML format is rather clumsy - Is the help file really going to be machine interpreted? Plain text or a readme (in various languages) would surely be more appropriate. Man pages anybody?

    I can see the need for the error XML format, but it needs to usable in a simple form. The xsd seems a bit out-of-kilter as it doesn't specify the sequence/grouping of the complex types; as a result I can't see which sections I have to implement.

    Those are a few of my concerns. We certainly do need a cli standard to ease use of command line tools and shell usage. But these standards are trying to bundle too many additional concerns together a real barrier to adoption: The responsibility for all of these concerns is passed to the cli command implementor, this makes creating command line interfaces to applications unecessarily complicated. It also means the consumer of my command needs to know exactly what parts of the broad reaching standard are implemented, rather than composing multiple components each with simple well defined concerns.

  • Very sophisticated :)

  • Suggested parameter - key

    /?? which could work as web help with more examples, or only examples and simple code fragments

Page 1 of 2 (16 items) 12