CLI Principles
CLI Principles Section 3 Draft

Command grammar

Source 03-command-grammar.md

Back to the spec index

  • <cli> <noun> <verb> [parameters] is the recommended grammar, not a requirement. A CLI may shape commands another way.
  • Verbs shared by all CLIs, with a fixed meaning: list, get, search, create, update, delete, replace (whole-object replace, 6a), upsert (create or update in one command, 6a), and set-<field> (change one named field, for example set-status, 6a). Other verbs are allowed but have no fixed meaning.
  • Command and parameter names are singular. See rule 8 in 3a. <cli> task list, not <cli> tasks list.
  • Named parameters over positional arguments. Order-independent. Rules for parameters are in 3a.
  • Standard parameters on every CLI: -help, -output {text,json,yaml,md}, -field (repeatable), -quiet (hides warnings and human messages, never the result or an error), -no-input (accepted, no effect, since no command prompts, see 6), -no-color, -dry-run (mutation only), -confirm (mutation only).
  • version is a command, not a parameter. Every CLI has <cli> version. There is no -version parameter (one way to ask, see 3a rule 2).
    • It is a query with no parameters of its own. The standard output parameters still apply.
    • The result holds cli (the CLI’s name) and version (the CLI’s own version, for example 1.4.2). Example: {"result": {"cli": "tracker", "version": "1.4.2"}}.
    • In text format it prints one line: tracker 1.4.2.
    • It is unrelated to -if-version (6a), which carries the version of a piece of data, not of the CLI.
  • Standard input is chosen with the -stdin parameter, never with a bare - as a value (see 3a). Output goes to stdout by default.