214

While developing the application I started to wonder - How should I design command line arguments?

A lot of programs are using formula like this -argument value or /argument value. Solution which came to my mind was argument:value. I thought it is good because with no white spaces there is no way that values and arguments can be messed up. Also it is easy to split a string into two on the first from the left : character.

My questions are:

  1. Is popular -argument value formula better than argument:value (more readable, easier to write, bugfree, easier to understand by expert developers)?
  2. Are there some commonly known rules which I should follow while designing command line arguments (other than if it works it is OK)?

Asked for some more details I will provide it. However I think they should not affect the answers. The question is about a good habits in general. I think they are all the same for all kinds of applications.

We are working on an application which will be used in public places (touch totems, tables). Applications are written using Qt Quick 5 (C++, QML, JS). Devices will have Windows 8.1/10 installed. We will provide front-end interface to manage the devices. However some advanced administrators may want to configure the application on their own. It is not very important from the side of the business but as I agree with what Kilian Foth said I do not want my application to be a pain for a user. Not finding in the Internet what I want I asked here.


To more advanced Stack Exchange users: I wanted this question to be general. Maybe it qualifies to the community wiki (I do not know if existing question can be converted with answers). As I want this question to be operating system and programming language independent the answers appearing here can be a valuable lesson for other developers.

Filip Hazubski
  • 2,013
  • 3
  • 11
  • 11
  • 17
    Look to popular command line tools. For example, the single hyphen is often used to allow combining options. e.g. you might write `ls -ltr` to combine the options `-l`, `-t` and `-r`. GNU style programs also typically allow word-based options with a double hyphen like `--reverse` instead of `-r`. There are other popular conventions like `-h` to show help, `--` to signal the end of options, specifying `-` as a filename to allow reading from stdin, etc. – Brandin Jan 15 '16 at 09:48
  • 78
    Neither `-argument value` not `-argument:value` are common. Common are `-a value`, `-avalue`, and `--argument=value`. – reinierpost Jan 15 '16 at 10:16
  • 42
    Use a popular command line parsing library (usually called something like `getopt(s)`) where you can. – reinierpost Jan 15 '16 at 10:17
  • I have noticed some downvotes. I would like to know what I can do to improve my question and ask better questions in the future. – Filip Hazubski Jan 15 '16 at 11:00
  • 1
    optional parameters are os dependant: linuxnix uses "-" and "--", Microsoft uses "/". which os and programming language are you talking about? – k3b Jan 15 '16 at 11:08
  • 5
    @k3b We are working with Qt. As [kevin cline](http://programmers.stackexchange.com/users/16929/kevin-cline) said in [his comment](http://programmers.stackexchange.com/a/307469/210140) we can use already available library. I suppose it is multi-platform and well-thought. [QCommandLineParser](http://doc.qt.io/qt-5/qcommandlineparser.html) – Filip Hazubski Jan 15 '16 at 11:26
  • 3
    @FilipHazubski Yes, use QCommandLineParser. If you follow the examples on that documentation page then your program will make sense to most users. – Brandin Jan 15 '16 at 12:48
  • 1
    @FilipHazubski: you could improve your question by giving more context (e.g. mentioning Qt) and telling what kind of software (and users) you have. So please **edit your question** again – Basile Starynkevitch Jan 15 '16 at 13:03
  • @BasileStarynkevitch Well, I have not included it because I did not wanted this question to be platform or language specific. I probably will check your answer as accepted as it is comprehensive. I like it and I have learned from it. I normally wait for about 24 hours after asking a question. Some users are not online often. Maybe they have some new interesting approaches to the problem. If you think this behavior is wrong, please make me aware of that. Keep in mind that if I would be too quick I would accept [Kilian Foth's](http://programmers.stackexchange.com/users/7422/kilian-foth) answer. – Filip Hazubski Jan 15 '16 at 13:30
  • Your behavior is not wrong, but I would be able to improve my answer if I knew more details about your software. In the details, it depends! A game player don't want as much command line options as a compiler user! A software for grandma is not the same as a software for kernel developers or datacenter sysadmins. – Basile Starynkevitch Jan 15 '16 at 13:32
  • 14
    The problem with your final blurb is that argument parsing is not a platform-independent issue. – pydsigner Jan 15 '16 at 14:57
  • 4
    If a program is cross-platform such as git, it's fine to parse arguments in the same basic way among supported platforms. – Brandin Jan 15 '16 at 16:01
  • @pydsigner It is not but the answer can mention that and advise the reader what he should do for different kinds of platforms. I do not want to sound like "I do not care that there is a problem. I want to have it done and do not want to lift a finger". Keep in mind I am no expert on a subject. I do not know how broad it is. I just wanted to receive a general advice. I must say that I have got absolutely more than I expected. – Filip Hazubski Jan 15 '16 at 16:32
  • If you don't like `-argument value`, use `--argument=value` instead, but you should most definitely keep the leading dash. – zwol Jan 16 '16 at 02:46
  • I personally hate things that use one dash, but long arguments. – Blacklight Shining Jan 16 '16 at 04:39
  • 1
    remotely related: [The Nine Facets of an Awesome Command-Line App](http://naildrivin5.com/blog/2012/04/01/the-nine-facets-of-an-awesome-command-line-app.html) – Nick Alexeev Jan 16 '16 at 07:51
  • 3
    The question [What is the general syntax of a Unix shell command](https://stackoverflow.com/questions/2160083/what-is-the-general-syntax-of-a-unix-shell-command) on Stack Overflow may be of some relevance. My answer there discusses some of the different systems of argument handling nomenclature that have been used on Unix (and elsewhere) over time. – Jonathan Leffler Jan 16 '16 at 15:35
  • 1
    And whilst we are at it, please alway allow a machine readable output format. (even if optional). Delimited, json, whatever. Just something you don't have to hand roll a parser for. – Sobrique Jan 17 '16 at 12:38
  • Why do you want to reinvent the wheel? Do you have a lot slack in your deadline for coding and debugging something which has already been coded and debugged long ago? You don't say which language you are coding in, but unless it is extremely esoteric, it probably as a port of getopt(). If not, there are command line option parsers for 21 languages at Rosetta Code http://rosettacode.org/wiki/Parse_command-line_arguments – Mawg says reinstate Monica Jan 18 '16 at 08:40
  • 1
    Please use the same conventions as everybody else. This is a good idea if you want your programs to be used by others than your self. – Thorbjørn Ravn Andersen Jan 18 '16 at 15:25
  • 1
    In addition to reading the answers here, see also The Art of Unix Programming, chapter 10. http://catb.org/esr/writings/taoup/html/ch10s05.html – Brandin Feb 04 '16 at 13:28

5 Answers5

263

On POSIX systems (e.g. Linux, MacOSX), at least for programs possibly started in a shell terminal (e.g. most of them), I would recommend using the GNU coding conventions (which also lists common argument names) and look into the POSIX utilities guidelines, even for proprietary software:

  • always handle --version and --help (even /bin/true accepts them!!). I curse the authors of software not understanding --help, I hate them (because prog --help is the first command I am trying on a new program)! Often --help can be abbreviated as -h

  • Have the --help message list all the options (unless you have too many of them... in that case list the most common ones and explicitly refer to some man page or some URL) and default values of options, and perhaps important (and program-specific) environment variables. Show these option lists on option argument error.

  • accept -a short argument (single letter) and have some equivalent --long-argument, so -a2 --long-argument=2, --long-argument 2; of course you could have (for rarely used options) some --only-long-argument name; for modal arguments without extra options -cf is generally handled as -c -f, etc. so your -argument:value proposal is weird, and I don't recommend doing that.

  • use GLIBC getopt_long or better (e.g. argp_parse, in OCaml it's Arg module, ...)

  • often use - for standard input or output (if you can't do that, handle /dev/stdin & /dev/stdout even on the few operating systems not having them)

  • mimic the behavior of similar programs by reusing most of their options conventions; in particular -n for dry run (à la make), -h for help, -v for verbosity, etc...

  • use -- as separator between options & file or other arguments

  • if your program uses isatty to test than stdin is a terminal (and behave "interactively" in that case), provide an option to force non-interactive mode, likewise if your program has a GUI interface (and tests getenv("DISPLAY") on X11 desktop) but could also be used in batch or command line.

  • Some programs (e.g. gcc) accept indirect argument lists, so @somefile.txt is meaning read program arguments from somefile.txt; this could be useful when your program might accept a very big lot of arguments (more than your kernel's ARG_MAX)

BTW, you might even add some auto-complete facilities for your program and usual shells (like bash or zsh)

Some old Unix commands (e.g. dd, or even sed) have weird command arguments for historical compatibility. I would recommend not following their bad habits (unless you are making some better variant of them).

If your software is a series of related command-line programs, take inspiration from git (which you surely use as a development tool), which accepts git help and git --help and have many gitsubcommand and gitsubcommand--help

In rare cases you might also use argv[0] (by using symlinks on your program), e.g. bash invoked as rbash has a different behavior (restricted shell). But I usually don't recommend doing that; it might make sense if your program could be used as a script interpreter using shebang i.e. #! on first line interpreted by execve(2). If you do such tricks, be sure to document them, including in --help messages.

Remember that on POSIX the shell is globbing arguments (before running your program!), so avoid requiring characters (like * or $ or ~) in options which would need to be shell-escaped.

In some cases, you could embed an interpreter like GNU guile or Lua in your software (avoid inventing your own Turing-complete scripting language if you are not expert in programming languages). This has deep consequences on the design of your software (so should be thought of early!). You should then easily be able to pass some script or some expression to that interpreter. If you take that interesting approach, design your software and its interpreted primitives with care; you could have some weird user coding big scripts for your thing.

In other cases, you might want to let your advanced users load their plugin into your software (using dynamic loading techniques à la dlopen & dlsym). Again, this is a very important design decision (so define and document the plugin interface with care), and you'll need to define a convention to pass program options to these plugins.

If your software is a complex thing, make it accept some configuration files (in addition or replacement of program arguments) and probably have some way to test (or just parse) these configuration files without running all the code. For example, a mail transfer agent (like Exim or Postfix) is quite complex, and it is useful to be able to "half-dry" run it (e.g. observing how it is handling some given email address without actually sending an email).


Notice that the /option is a Windows or VMS thing. It would be insane on POSIX systems (because the file hierarchy uses / as a directory seperator, and because the shell does the globbing). All my answer is mostly for Linux (and POSIX).


P.S. If possible, make your program a free software, you would get improvements from some users & developers (and adding a new program option is often one of the easiest things to add to an existing free software). Also, your question depends a lot on the intended audience: a game for teenagers or a browser for grandma probably does not need the same kind and amount of options than a compiler, or a network inspector for datacenter sysadmins, or a CAD software for microprocessor architects or for bridge designers. An engineer familiar with programming & scripting probably likes much more having lots of tunable options than your grandma, and probably might want to be able to run your application without X11 (perhaps in a crontab job).

nobody
  • 848
  • 7
  • 12
Basile Starynkevitch
  • 32,434
  • 6
  • 84
  • 125
  • The subcommand approach is also used by svn and cvs. Probably cvs is the originator of this approach, but definitely not git. – Brandin Jan 15 '16 at 10:00
  • 19
    Agreed, but `git` is a better example. I won't recommend even *looking* into `cvs` in 2016. – Basile Starynkevitch Jan 15 '16 at 10:01
  • 2
    For short options, try to follow conventions as well, e.g. `-h` for help,`-v` for verbose, `-n` for dry run. – reinierpost Jan 15 '16 at 10:14
  • 1
    There are some weird conventions as well, like `-v -v` to give "more verbose" options than just one "-v". I personally don't like that one. – Brandin Jan 15 '16 at 10:33
  • Not always; sometimes `-v` takes an optional verbosity level. – Basile Starynkevitch Jan 15 '16 at 10:35
  • 8
    + in case of invalid option just show help. It's SOOOO annoying to get a useless error message for example for `dd -h`. – domen Jan 15 '16 at 11:42
  • 2
    `--` signals the "end of the switches". e.g. `--foo --bar -- --baz` means that '--foo', '--bar' and '--' are switch arguments, and that '--baz' is to be considered the first non-switch argument. – Brandin Jan 15 '16 at 12:34
  • 8
    GNU programs support `--help` as a rule but often don't recognize `-h` which is annoying. I usually type -h when I forget an option to a program, it is annoying to have to retype the command with the longer option `--help`. After all, I typed -h because I forgot something. Why should the user be expected to remember which progams require '--help' and which programs require '-h' to show the help screen? Just include an option for both -h and --help. – Brandin Jan 15 '16 at 12:42
  • 4
    I would follow the composition rule that `-a -b -c` can be written `-abc` and to give arguments to options you separate them via spaces or equal signs. This also helps with autocomplete in most shells. – Darkhogg Jan 15 '16 at 13:06
  • 33
    The first part of this answer is good but somewhere along you are kind of go off on tangents. For example, configuration files, plugins and dlopen, choices of software licenses and Web browsers aren't really related to the conventions of a command line interface anymore. – Brandin Jan 15 '16 at 13:58
  • @BrandIn: configuration files & plugins need program argument support and influence on its CLI design – Basile Starynkevitch Jan 15 '16 at 14:06
  • 2
    @BasileStarynkevitch You miss the point. If you're going to mention something like plugins, why not also mention environment variables, conventions of using stdout or stderr and in which situations, which conditions should cause nonzero exit statuses to be returned, whether to supply man or info pages, etc. etc. These things are important in the right context but are only tangentially related to the actual command line arguments. – Brandin Jan 15 '16 at 14:09
  • I did mention most of that... – Basile Starynkevitch Jan 15 '16 at 14:10
  • If you want to mention absolutely everything maybe also worth mentioning is whether the program makes sense to be used as a filter in a command line pipeline, i.e. something like `cat foo | bar | baz`. Also consider whether you shouold offer your tool (additionally) as a dynamic library with popular language bindings. Also whether you should offer a C-style API, object oriented API, or both. Also... whatever else you can think of. – Brandin Jan 15 '16 at 14:16
  • 3
    @Brandin `-h` can be very bad to try, e.g. with some implementations of `shutdown` that default the time to `now`. – Residuum Jan 15 '16 at 14:54
  • 4
    git is NEVER a good example as far as CLI utilities go. it is the reference for desastrous command line standards. – Florian Heigl Jan 15 '16 at 15:11
  • 4
    @FlorianHeigl Why? git follows same patterns as other similar tools. – Brandin Jan 15 '16 at 15:32
  • 4
    @Brandin: the syntax of git is OK. The various commands and their semantics are ... hard to learn, to stay polite (my very personal stance being that they are brain damaged, competing with PHP on the inconsistency side). –  Jan 15 '16 at 15:41
  • 4
    I would argue that the basics of the POSIX format are well known enough that using them on Windows is a good idea, as well. – jpmc26 Jan 15 '16 at 22:59
  • 4
    Is `-pvalue` (without space between option and value) really a common pattern? It seems like it could also be interpreted as `-p -v -a -l -u -e`, isn't it? – kiewic Jan 16 '16 at 17:43
  • 2
    Indeed yes, so handling `-pvalue` as `--pvalue` is wrong – Basile Starynkevitch Jan 16 '16 at 17:48
  • 6
    And please. If you do format your output for screen, add an output format override. Nothing annoys me more than commands that truncate or wrap lines when I am trying to use them in a script. – Sobrique Jan 17 '16 at 12:52
  • 4
  • 3
    @kiewic One example is `gcc -Wall -obar foo.c` – Brandin Jan 20 '16 at 09:10
  • If you are a user of zsh and annoyed by the error message of GNU utils after `-h`, you might be interested in adding this to you shell's config: https://gist.github.com/joepvd/fa76322514895617fac2241377c4c1ec – joepd Oct 11 '16 at 22:16
  • 1
    @BasileStarynkevitch Actually, handling `-pvalue` as `--param=value` is such a *de facto* standard that you'll see it defined as the default, non-configurable behaviour in all sorts of declarative argument-parsing libraries. The alternative is asking people to re-type their command when they forget the space between "-p" and "value"... and that would frustrate people who just want to get work done rather than humouring your special snowflake utility. – ssokolow Dec 14 '16 at 22:27
  • It should also be possible to force interactive mode, for cases where stdin isn't a TTY but interactivity is required. – Solomon Ucko Jan 20 '19 at 14:23
  • This excellent answer applies universally nowadays. `/option` isn't really a very Windows thing any more; it was a VMS, CP/M, IBM, MS-DOS thing, but nowadays Windows is going PowerShell and the `-x` and `--option` etc. conventions are nearly ubiquitous. – debater Jan 21 '20 at 16:54
73

The fact that a data format convention is popular is its advantage.

You can easily see that using = or : or even ' ' as a separator are trivial differences that could be converted into each other by computer with little effort. What would be a big effort is for a human to remember "Now see, did this infrequently-used program delimit things with : or with = ? Hmmm..."

In other words, for the love of god, don't deviate from extremely entrenched conventions without a compelling reason. People will remember your program as "the one with the weird and annoying cmdline syntax" instead of "the one that saved my college essay".

Kilian Foth
  • 107,706
  • 45
  • 295
  • 310
  • 19
    for almost all languages there are library functions to handle command line arguments. Use one of them. – kevin cline Jan 15 '16 at 08:43
  • 9
    Good advice, but what are those conventions? -1 – RubberDuck Jan 15 '16 at 10:20
  • My answer mentions the GNU coding convention – Basile Starynkevitch Jan 15 '16 at 10:24
  • 14
    There is an interesting example of a commonly used UNIX tool which violates this convention intentionally: [`dd`](http://linux.die.net/man/1/dd) uses a `key=value` syntax. The reason for this design decision is that this tool (nickname: **d**ata **d**estroyer) can cause a lot of damage when used incorrectly. By forcing the user to abandon their usual habit they force the user to think more closely about what they are doing. – Philipp Jan 15 '16 at 11:32
  • 18
    Are you sure that is the reason for `dd`? I believe that it simply was coded at a time (1970s?) when the kernel's ARG_MAX was small, shells had no auto-completions, and `--long-arguments` did not exist. Since then better `dd` remained backward compatible – Basile Starynkevitch Jan 15 '16 at 11:43
  • +1. I have struggled with programs that use both `:`, `::`, and ` ` for different options, with no apparent pattern. – Davidmh Jan 15 '16 at 12:16
  • 1
    The reason for using `-` is that it's unlikely to be at the beginning of a filename. And if it is, you can use either `-- -foo` (GNU programs) or `./-foo` to specify the filename. Avoid other special symbols because they might be shell metacharacters. For example if your program wants me to type backtick characters or `$` characters in the actual arguments, that would make it difficult to use from most shells. – Brandin Jan 15 '16 at 12:18
  • 10
    `dd` originated from another OS (than UNIX) - a scripting-language (JCL) on IBM's OS/360 - where the conventions were different, before being ported more or less unchanged to UNIX - partly because those likely to use it, knew it from the previous system. – Baard Kopperud Jan 15 '16 at 12:47
  • In addition to GNU, POSIX also mentions conventions/requirements on command line switches. They are typically (always?) single character switches. If using both -1 and -l as switches, make the distinction clear in your help text, e.g. "-1 (one) and -l (ell)". – Brandin Jan 15 '16 at 12:55
  • 1
    Relevant [xkcd](https://xkcd.com/927/) – DJMcMayhem Jan 15 '16 at 17:53
  • @DJMcMayhem Even more relevant: https://xkcd.com/1168 – Kilian Foth Jan 17 '16 at 11:11
30

In layman's terms

When in Rome, do as the Romans do.

  • If your CLI app is intended for Linux/Unix use the -p value or --parameter value convention. Linux has tools for parsing such parameters and flags in an easy way.

I usually do something like this:

while [[ $# > 0 ]]
do
key="$1"
case $key in
    --dummy)
    #this is a flag do something here
    ;;
    --audit_sessiones)
    #this is a flag do something here
    ;;
    --destination_path)
    # this is a key-value parameter
    # the value is always in $2 , 
    # you must shift to skip over for the next iteration
    path=$2
    shift
    ;;
    *)
    # unknown option
    ;;
esac
shift
done
  • If your CLI app is intended for Windows, then use /flag and /flag:value conventions.

  • Some apps like Oracle use neither though. Oracle utilities use PARAMETER=VALUE.

  • One thing I like to do is, besides accepting parameters in the command line, providing the option of using a parfile, which is a key-value pair file to avoid lengthy parameter chains. For that you should provide an additional --parfile mifile.par parameter. Obviously if --parfile is used, all other parameters are discarded in favor of what's inside the parfile.

  • An additional suggestion is allowing the use of some custom environment variables, for example, setting environment variable MYAPP_WRKSPACE=/tmp would make it unnecessary to always set --wrkspace /tmp.

  • In Linux don't forget to add parameter auto-completion, meaning users can type half a switch, hit TAB and then shell would complete it for them.
Tulains Córdova
  • 39,201
  • 12
  • 97
  • 154
  • 1
    Well, several GNU utilities (e.g. `gcc`) handle `@mifile.par` like your `--parfile mifile.par` suggestions. – Basile Starynkevitch Jan 15 '16 at 12:04
  • 7
    Are you sure about ignoring all other options if there's a parameter file? It sounds counterintuitive to me, at best. – Jonathan Leffler Jan 15 '16 at 14:56
  • 9
    I agree with Jonathan about parameter files. If the parameter file is present, then I would expect it to be used for default values, with arguments given on the command line applied overtop those in the parfile. If for some reason the use of a parfile precludes the use of additional command line arguments, then the presence of additional arguments should be an error. – Eldritch Cheese Jan 15 '16 at 23:12
  • @EldritchCheese In the CLI apps I've written, when a parfile is given, any aditional parameter generates an error. – Tulains Córdova Jan 16 '16 at 00:04
  • @user61852 Be wary of treating Oracle's exotic behaviors as canonical. Oracle cleaves its own path through UI spaces, but few follow in its wake. Behavior when providing a config file as a commandline argument is one such space. – Dewi Morgan Jan 16 '16 at 01:08
  • @DewiMorgan Oracle's parfile parameters are acummulative, meaning they add to aditional parameters passed into the command line. In my programs, I make them mutually excusive, you give a parfile or you give parameters. – Tulains Córdova Jan 16 '16 at 02:11
  • If not Oracle, then WHAT possible program permits, and then silently ignores, commandline args when a config file param is given? – Dewi Morgan Jan 16 '16 at 02:34
  • 1
    If using a capable shell, this kind of "config file parameter" option is not necessary. e.g. you just write `fooCmd -opt1 -opt2 $(cat more_options.opts)`. Therefore I would expect a "config file parameter" option, if provided, should basically work in the same way. – Brandin Jan 16 '16 at 06:50
22

One thing that didn't come up yet:

Try to design your software from the command line arguments upwards. Meaning:

Before designing the functionality, design the user interface.

This will allow you to drill down on edge cases and common cases early on. Of course you'll still abstract the outside and the inside, but it's going to give much better result than just writing all the code and then slamming a CLI to it.

Furthermore, check out docopt (http://docopt.org/).

docopt is a great help with that in many languages, especially for python where you have severely limited, user-adverse argument parsers like argparse still being considered as "OK". Instead of having parsers and subparsers and conditional dicts, you just define the syntax help (according to the matching POSIX standard) and it does the rest.

Florian Heigl
  • 337
  • 1
  • 5
  • 1
    I love this answer, and thank you for it, because I am currently frustrated at `argparse` being none of programmer, user-interface or user friendly. – cat Jan 15 '16 at 22:14
  • 1
    I tried docopt, and I don't like it. [click](http://click.pocoo.org/5/) results in *much* cleaner code, although there is a little wonkiness with options when you have subcommands. – jpmc26 Jan 15 '16 at 23:03
  • 3
    This is too much like an advertisement. Mention the resource just once if it's relevant.. But as it is now, 50% of your answer just sounds like promoting an external resource. – Brandin Jan 16 '16 at 06:52
  • 1
    I would word it as 'design the use model first'. Separating the user experience from the functionality can be an artificial distinction in many cases (tool limitations affect the interface). – copper.hat Jan 16 '16 at 18:41
  • @brandin sorry: I meant that part to be funny, but it couldn't be. It had taken me easily a year between reading about and then trying this library. I could have saved myself a lot of time if I had just done it right at the first moment. :-) – Florian Heigl Jan 19 '16 at 23:41
  • 1
    +1 for Docopt. It solved all my CLI dilemmas, completely pain free. Sometimes it is hard to tell advertisement from genuine enthusiasm, but here it is - I have been a Docopt enthusiast for years now, not affiliated in any way ;) – frnhr Jan 21 '16 at 21:41
  • I've actually found argparse to be quite capable. doctocpt is nifty too, but having the ground truth be plain text is limiting in itself; what if you want to dynamically create an argument parser based on e.g a yaml file (real use case for me)? Would you then output a plain text file and re-parse it? – Karl Rosaen Apr 08 '17 at 17:48
  • Please let me know how that relates to well designed CLI. Please let me know what's more important - a very good user interface that'll used for all the time the software is used, or how you on the implementation end gain some options, etc. pp. Your answer doesn't contribute anything, at all. – Florian Heigl Apr 09 '17 at 20:04
4

Some valuable comments provided already (@Florian, Basile), but let me add ... OP says,

We will provide front-end interface to manage the devices. However some advanced administrators may want to configure the application on their own

But also remarks:

I did not want this question to be platform or language specific

You must consider your target audience - advanced administrators. What platform do they normally work on - Win/ Unix/ Mac? And what platform does you app run on? Follow whatever CLI conventions have already been established for that platform. Do your "advanced" admins want/ need a GUI based tool?

You want the interface to be consistent internally and with other admin tools. I don't want to stop and think is it cmd -p <arg> or cmd -p:<arg> or cmd /p <arg>. Do I need quotes 'cos there's a space? Can I cmd -p <val1> <val2> or cmd -p <val1> -p <val2> for multiple targets? Are they order specific? Overloadable? Does cmd -p2 <arg> -p1 <arg> work too? Does ls -l -r -t dir1 dir2 == ls -trl dir1 dir2 ?

For my Unix admin tools, I have always kept the guidance provided by Heiner's Shelldorado in mind along with the other references mentioned.

As important as designing the CLI is to make sure your application is designed to work with command line arguments the same as from the GUI - ie: no business logic in the GUI or use the common command called from both GUI and CLI.

Most UNIX based administrative tools are actually designed first as command lines tools and the provided GUI simply facilitates "populating" the options for the command line. That approach allows for automation, use of response files, etc. and hands-off management (less work for me!)

As classic toolset used w/this approach is Tcl/Tk. Not suggesting you switch tools; just consider design approach from writing a GUI-based administrative app to the app as a command line tool first; then layer the GUI on top for convenience. At some point you'll likely discover the GUI is a pain (and error prone) if you have to do multiple configs and re-entering generally the same options over and over and you'll look for an automated approach.

Remember your admin likely has to type in the correct values in the correct boxes anyway, so how much effort are you relieving anyway w/GUI ?

Ian W
  • 141
  • 3