Defining CLI Flag Naming Conventions

[knqyf263]

Description

I’d like to open a discussion around formalizing our CLI flag naming conventions, particularly focusing on two key questions:

1. Singular vs. Plural
2. Abbreviations vs. Full Names

They are mixed up in Trivy now.

     --sbom-sources strings        [EXPERIMENTAL] try to retrieve SBOM from the specified sources (oci,rekor)
     --image-src strings               image source(s) to use, in priority order (docker,containerd,podman,remote) (default [docker,containerd,podman,remote])

Singular vs. Plural

When should we use --flag vs. --flags?

For instance, Docker consistently uses the singular form:

  -e, --env list                         Set environment variables
      --cap-add list                     Add Linux capabilities
      --cap-drop list                    Drop Linux capabilities

In contrast, the AWS CLI always uses the plural form for list inputs:

       --instance-ids (list)
          The instance IDs.

Kubectl shows mixed usage; for example, although the --filename flag accepts multiple values, it is named in the singular form:

    -f, --filename=[]:
    -L, --label-columns=[]:

Abbreviations vs. Full Names

Where do we draw the line between concise flags (e.g., --rm, --db) and more descriptive flags (--remove, --database)? Popular tools vary in their approaches. Docker often uses short forms (--rm, --env).

These questions came up in a recent PR #8269, where we have several options, like

• --vuln-severity-src
• --vuln-severity-srcs
• --vuln-severity-source
• --vuln-severity-sources

Our goal is to define a clear, maintainable guideline that balances brevity with clarity.

Points for Discussion

• Does using singular vs. plural alter the perceived scope or functionality of a flag?
• When are abbreviations acceptable, and when do they hinder readability for new users?
• Are there established best practices we can adopt from widely used CLI tools (Docker, Helm, Kubectl, etc.)?
• Why might some flags, such as --db-repository, inherently “feel right” for me (maybe @DmitriyLewen as well) in singular form?

I’d love to hear everyone’s thoughts, examples, and experiences to help us build a more consistent and intuitive CLI across our projects.

[simar7]

My 2c:

Singular vs. Plural

Often times the flag is more extensible if pluralized from the beginning. An example of this are those flags where lists (multiple inputs) are involved. We may only have one input for the flag today but if tomorrow things change and now we require to pass in multiple inputs, we don't need to change the flag (or add aliases) we've seen this before in Trivy when renaming the flags for checks.

One could argue that a singular flag could also support taking in a list of inputs but to me it feels a bit odd to specify a list for a flag that is singular to read.

Another point somewhat related to this are boolean flags. They are quite limiting in nature and should be used sparingly. A recent example of that could be found here in this discussion: #8360 (comment)

In this case I actually suggested the use of a boolean flag at first but I realized that there's a better way for us to restructure it by making it into a flag that accepts a list as @nikpivkin suggested.

Abbreviations vs. Full Names

I would vote for long flags to always be fully spelt out and for their short aliases to be compacted. For example: --remove for long flag vs. --rm for its short equivalent.

I say this as the IMHO the main reason why long flags exist is to help the relatively new user understand the functionality fully, given the high readability and verbosity of the long flags. Power users (and/or automation) can benefit from the short flags where readability isn't a key concern but brevity might be preferred.

[knqyf263]

Thank you for your comment—I agree with your reasoning. In summary:

• Using Plural Forms for Lists:

  • When a flag accepts a list, use its plural form.
  • However, if a flag is later extended to accept multiple values, there’s no need to change its name.
    • For example, although --db-repository originally accepted only one value and later allowed multiple values, there’s no need to change it to --db-repositories or add an alias.

• Fully Spelling Out Flag Names:

  • Flag names should generally be fully spelled out.
  • It’s acceptable to add a shorter alias.
    • For example, the primary flag could be --remove with --rm as its alias.

One point of concern is whether to change --db-repository to --database-repository. Personally, I feel that “DB” is a well-known abbreviation among engineers, but this is subjective. To eliminate any ambiguity, should we use --database-repository and add an alias such as --db-repo? Additionally, is using "EOL" acceptable? The flag --exit-on-eol seems preferable to the longer --exit-on-end-of-life. I think we need further discussion on how much of the flag name should be fully written out.

[itaysk]

I'm still thinking, just an observation - you summarized:

if a flag is later extended to accept multiple values, there’s no need to change its name.

I'm not sure what @simar7 meant? there are conflicting statements:

if tomorrow things change and now we require to pass in multiple inputs, we don't need to change the flag (or add aliases) we've seen this before in Trivy when renaming the flags for checks.

One could argue that a singular flag could also support taking in a list of inputs but to me it feels a bit odd to specify a list for a flag that is singular to read.

[simar7]

I'm not sure what @simar7 meant? there are conflicting statements:

if tomorrow things change and now we require to pass in multiple inputs, we don't need to change the flag (or add aliases) we've seen this before in Trivy when renaming the flags for checks.

One could argue that a singular flag could also support taking in a list of inputs but to me it feels a bit odd to specify a list for a flag that is singular to read.

What I had meant is that the flags should be plural from the beginning so that if we change the inputs we accept from single value to a list of values, we don't have to change the flag. A plural flag implies at least one value can be provided vs. a singular flag implies at most one value to me.

Of course this is subjective as we've seen contrary behavior in the case of Docker cli.

[itaysk]

About plural/singular

I think there are 3 issues:

1. the cardinality of the configuration being set by the flag
2. the cardinality of the component being configured by the flag
3. abbrevating plurals

For example, the flag --module{s}-dir{s} - may accept one or many directories (issue 1), may relate to a one or many modules (issue 2), and directories may be abbrivated as dir/dirs.

The reference you gave of Docker is supporting my claim that these issues are conflated. You presented it as singular but the examples aren't decisive. --cap-add refers to: 1) adding a capability (singular)? 2) adding capabilities (plural)? 3) adding a capability to the capabilities set (both)? we don't know, since cap is abbrivated, and add is a verb. I'm saying this only to support my breakdown in to 3 issues, I don't think we need to discuss the docker example further.

Issue 1
This is what you and Simar discuss here. I think your summary makes sense. But I want to point out that it won't solve the inconsistency issue you started with (fine with me, I don't think we can formalize everything).

Issue 2
This is what prompted this discussion I believe (--render-cause{s}). I'll try to articulate my intuition here so I'm not sure how accurate this will be: when referring the to the component itself, it's more intuitive to use plural: Trivy loads Modules, Trivy evaluates Checks, Trivy finds Vulnerabilities, The report shows Findings. When referring to a property of the component, it's more intuitive to use singular: directory of a Module, schema of a check , score of a vulnerability, cause of a finding. Notice that aligns with our previous choices so far: --module-dir, --check-namespaces, --severity and more --registry-token, --file-pattern, --license-confidence-level... I guess that's why I suggested --render-cause, this flag controls if we should render the cause of the finding.

Issue 3
IMO we should always try to indicate plurality even in abbrivations. so --environment-variables might be abbrivated as --env-vars. And if further abbrivated then to --envs.

[knqyf263]

I kind of understand your explanation, but I still haven’t fully grasped the difference between a component and an attribute of a component. For example, in the case of a flag that specifies the source of an image, would that be considered an attribute of the component? In other words, does that mean that using --image-source is preferable? I also felt, for some reason, that the singular form was better in this case (and I chose singular), but I can’t quite articulate why I felt that way.

[itaysk]

About Abbreviations vs. Full Names

I think we should use full names, unless an abbrivation is globally ubiquitous or defined as such by us; in which case it can be used, but consistently. For example, source shouldn't be abbrivated IMO. directory might be abbrivated to dir, since it's ubiquitious (directories should be abbrivated to dirs given my other comment about plurality). I also think it's fine to abbrivate misconfiguration to misconfig since we use it often, but not to misconf since it's inconsistent.

Note that this isn't related to short flags (for example, --interactive -> -i) which can still be made available for convenience.

[knqyf263]

an abbrivation is globally ubiquitous

Linux has a directory called "/src", and Go also has a directory named "src". Personally, I think that using the abbreviation "source → src" is widely recognized.

However, I'm not trying to argue about this specific abbreviation; rather, my point is that whether an abbreviation is considered ubiquitous is subjective and can vary among developers. So, who should decide when abbreviations are acceptable and when they are not, and based on what criteria?

[DmitriyLewen]

We also use pkg, dev, deps.
This is logical abbreviations for me. But I think not all users, especially those who are just beginning to understand vulnerability search, know this abbreviation.

Perhaps we should still choose the path with the most complete names, but use more aliases.

But we don't currently show aliases in docs and help.
It can be a small problem.

[knqyf263]

I searched for a standard abbreviation list defined somewhere but didn't find it. So, I created a small list for Trivy. What do you think?
#8453

[knqyf263]

ChatGPT o1 pro put into words what I couldn't articulate.

---

CLI Flags: Singular vs. Plural

1. Why the Distinction Matters

Deciding whether a CLI flag (option) should be in singular or plural form may seem trivial, but it has significant implications for usability, consistency, and clarity. Key considerations include:

• Does the flag represent a single conceptual unit (e.g., one file) or a list (e.g., multiple files)?
• How will users specify multiple values? By repeating the flag, or by providing multiple values in one go (comma-separated, space-separated, etc.)?

Many OSS projects (e.g., Docker, Kubernetes, Git) often use singular nouns for flags—even when multiple values are possible—because the mental model is “you specify one item each time you use the flag.” For example, Docker’s --env or Kubernetes’s --image are singular, but they can be repeated to supply multiple values.

2. Common Guidelines & Examples

2.1 OSS Examples

• Docker
  • --env KEY=VALUE (singular): repeated for multiple environment variables.
  • --env-file FILE (singular): repeated for multiple env files.
• Kubernetes (kubectl)
  • --filename (-f) FILE: although multiple files can be specified, the flag is singular and repeated as needed.
  • --image: typically references one image at a time, but can appear multiple times in certain contexts.
• Git
  • git commit -m MESSAGE: singular flag (-m) can be used repeatedly, each adding to the commit message.

These projects suggest that singular is often chosen when each instance of the flag represents “adding one item.” Repetition then naturally allows multiple items.

2.2 General Criteria for Singular vs. Plural

1. Conceptual Unit
   • If each flag corresponds to one logical entity (a file, an environment variable, a message, etc.), it is usually singular.
2. Specification Method
   • If the CLI design expects the user to repeat the flag to add multiple items, singular is more common.
   • If the design expects a single use of the flag with a list of values (e.g., comma-separated), a plural form may be more intuitive.
3. “List” vs. “Add One Item Repeatedly”
   • If the main concept is a list (e.g., --hosts implies multiple hosts specified at once), use plural.
   • If the main concept is adding one entity at a time (--host repeated), use singular.
4. Consistency & Simplicity
   • Often, projects standardize on singular forms for ease of documentation and familiarity.
   • If a single flag can accept multiple values in a single invocation, ensure the help text clarifies that possibility.
5. Documentation & Help
   • Whichever approach, be explicit in --help or usage docs about whether multiple entries are possible and how to specify them.

3. Handling Both Repeated and Batched Specifications

Sometimes, you might allow both repeated usage and batched (comma-/space-separated) usage. For example:

• --label KEY=VALUE (singular) can be repeated multiple times
• Also: --label KEY1=VALUE1,KEY2=VALUE2 in a single usage

In that scenario, there is no absolute rule for singular or plural; it depends on which method is considered “primary” or more intuitive. Two approaches:

1. Singular Flag as Primary
   • Use singular (--label), typically repeated for multiple values.
   • Mention in documentation that you can also provide multiple items in one go (comma-separated).
   • This approach is consistent with Docker, Kubernetes, and Git.
2. Plural Flag as Primary
   • Use a plural form (--hosts), which accepts a list in one invocation.
   • Optionally allow the flag to be repeated if a user wants to specify additional lists.
   • Example: --hosts host1,host2 --hosts host3,host4.

In both cases, clear documentation is crucial. For instance:

--label <key=value>[,<key=value>...]
    Specify a label (can be used multiple times).
    Alternatively, provide a comma-separated list in one go, e.g.:
      --label key1=val1,key2=val2

4. Proposed Rules for an OSS Project

1. Default to Singular
   • If each use of the flag represents adding one conceptual item, use singular. Repeated usage yields multiple items.
2. Use Plural If a Single Invocation Implies a List
   • If your design encourages specifying all items in one line, consider a plural form.
3. Don’t Overthink Short Flags
   • For single-letter flags (-f, -m, etc.), tradition and available letters often matter more than singular/plural consistency.
4. Document Thoroughly
   • Indicate clearly how to pass multiple values: repeated flags, comma separation, etc.

[knqyf263]

As long as the flag usage is clearly explained in the documentation and there is a certain level of consistency within the project, either approach is fine with me. Initially, I thought that if a flag accepts a list, it would be better to have a plural default as @simar7 suggested; however, after reading the explanation above, I reconsidered that a singular default would be preferable, using a list only when it’s absolutely necessary to explicitly indicate that it is a list.

I wasn’t even sure why --image-source felt more natural to me than --image-sources, but the above explanation resonated with me. The idea is to have a flag that enables one image source, and by specifying it repeatedly, users can ultimately enable multiple image sources.

@aquasecurity/trivy Since this inevitably involves some subjectivity, I believe that a certain degree of variation is acceptable. If no one else has a strong preference, would it be alright to adopt the above proposal as the project guideline?

[DmitriyLewen]

overall it sounds logical.
i agree to use this guide 👍

[simar7]

sounds good to me

[itaysk]

I'm fine with the conclusion (but not with the reasoning 🙂 but that doesn't matter)