Company logo with the letters 'NotTooBad Software' TextPicker Blog

Cross-platform command line arguments syntax


I’m rewriting Moderator (yet another command-line argument parser), and with Swift now being available for both OS X and Linux (Ubuntu) it should support a syntax which enables applications to fit in on both platforms.

POSIX* is I think the closest thing to a standard for this, so it will be the basis, with some modifications (The Python documentation also has some good insights).

* OS X is POSIX compliant and so is Linux (mostly).

Long option names

POSIX states that all options must be of the form -a and contain only one character. But --long-name is also widely used and often preferable. After all,

transmogrify --input file1 --output file2

is easier to understand than

transmogrify -i file1 -o file2

Notably Apple does not follow this norm. Their command-line applications, like swift* and xcodebuild, use only one - in front of their long option names (as in swift -help). And, presumably to avoid ambiguity, they do not allow combining several single character options after a single -.

* but not swift build.

Option names should not begin with a number

Each option name should be a single alphanumeric character (the alnum character classification) from the portable character set.

This means that -4 is a valid option name. But what if the application also takes negative numbers as one of its arguments? This could get confusing, not necessarily for the argument parser, but for us humans. Also I don’t think any programming language allows identifiers to begin with a number.

Allow weird characters in option names

The portable character set mentioned in the previous quote seems rather restrictive (for one it’s missing 2 characters from my name). I don’t think we should restrict command-line applications to only the English alphabet, there’s no reason they can’t be in other languages too.

Allow joining option and argument together with =

It is also quite common to join options and option arguments together:

transmogrify --input=file1 --output=file2

I even prefer this to the standard syntax because it makes it clear what is an option argument and what is a stand-alone argument. Also it makes it possible to have option arguments that begin with a - without being mistaken for an option.


I think good command line syntax should be designed first and foremost with the writers and readers of commands and shell scripts in mind. It should be as clear as possible not only for computers, but also for people reading the commands, even if they are unfamiliar with the application. Hopefully these commonly used additions brings us closer to this goal.

Suggest changes to post.


Want to hear about new posts?