Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsTo let users choose an implementation from the command line, add an explicit option that names the alternatives, document the accepted values and the default in the help output, and define which source wins when a flag and a saved configuration disagree. The command-line argument should have the highest precedence, so a user can override a project or personal default for a single run without editing any file. The sections below cover how to pick the mechanism, how precedence should work, and how to change the interface without breaking scripts.
Start with how often the choice changes
The first decision is not syntax. Ask how often the value changes and who it belongs to. The Command Line Interface Guidelines classify configuration along these lines: settings that vary between invocations belong in flags, settings that are stable but personal belong in user-level configuration, and settings every contributor should share belong in version-controlled, command-specific files in the project.
| Scope | Typical mechanism | How often it changes | Who it affects | Example |
|---|---|---|---|---|
| Invocation-specific choice | Command-line option | Every run | The single run | tool run --implementation fast |
| User-local default | User-level configuration file | Stable across projects | One developer | A personal setting in the user’s config directory |
| Shared project setting | Version-controlled project configuration | Stable across the project | Every contributor and CI run that reads the file | A committed project file that names the default implementation |
Putting a per-run experiment into a committed file creates version-control churn, and putting a team-wide default only in a personal file means each contributor has to configure it separately. Match the mechanism to the scope.
Choose between a switch and a keyed option
The Fuchsia Command-line Tools Rubric draws the distinction directly: a switch turns behavior on or off, while a keyed option takes a value. As the rubric puts it, “Unlike keyed options, a switch does not accept a value.”
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
- Use a switch only when the choice is genuinely binary, such as one alternative versus the built-in default (for example,
--use-native). - Use a keyed option when there are two or more named implementations, such as
--implementation fastor--implementation safe. Document the accepted names in one place and reject unknown names with an error that lists them. - Avoid one switch per implementation (
--fast,--safe,--legacy). It works for two alternatives, but it makes conflicts hard to express: what happens when a user passes two of them? - Avoid optional values. If
--implementationcan be given with or without a name, parsers and users both have to guess what a bare flag means. The Fuchsia rubric discourages optional keys and optional values for this reason.
Define precedence before users hit a conflict
When more than one source can set the implementation, the Command Line Interface Guidelines give this order, highest first:
- Command-line flags
- Variables set in the running shell environment
- Project-level configuration
- User-level configuration
- System-wide configuration
The first source that sets a value wins. Suppose the project file contains implementation = "fast". Running tool run --implementation safe uses safe for that run, and the project file stays unchanged. The same logic applies to a variable exported in the shell: it overrides the committed project file, which is useful for CI runners but surprising if a developer forgot an export from an earlier session.
Precedence is only useful if users can see it. Consider having the tool print the resolved value and the source that supplied it in a verbose or diagnostic mode, so a user can tell whether a flag, an environment variable, or a file produced the result.
Give users a negative form for config loading
If your tool loads configuration files by default, some users will need to skip them: to reproduce a bug on a clean setup, or to ignore a stale personal setting. The Fuchsia rubric recommends a distinct negative form such as --no-config for this, rather than having an omitted option or a special value mean “disabled.” Keep the two mechanisms separate: a keyed option such as --config path selects a file, and --no-config skips loading.
Document what --no-config does to the implementation choice. Does it fall back to the built-in default, or does an explicit --implementation flag still apply? Either can be right, but the help text must state which.
Write help text that makes the choice discoverable
The Fuchsia guidance says switches should be documented, and the same applies to keyed options. A reader should be able to learn the alternatives, the default, and the precedence from --help alone. An example of help output for a hypothetical tool:
Rank #4
Usage: tool run [--implementation <name>] [--no-config]
--implementation <name> Implementation to use: fast, safe.
Default: fast when no other source sets it.
Overrides project and user configuration.
--no-config Ignore project and user configuration files.
Check that the help output covers these points:
- Every accepted implementation name, listed explicitly
- The default, and what it applies to when nothing else is set
- Which configuration sources can change the value, and that the flag overrides them
- What each alternative trades off, stated only for claims you have verified for your own implementations
- A pointer to the reference documentation for the full precedence rules
Keep existing scripts working
Scripts depend on whatever behavior they observed. Adding a new option is usually safe. Renaming it, changing its default, or changing what a name selects is a compatibility change, and it can silently alter results in automation that nobody is watching. The Command Line Interface Guidelines recommend warning users from within the program before a flag is deprecated, because a script may depend on its current behavior.
- Add the new option, and keep the existing behavior as the default for the first release.
- When a deprecated spelling is used, print a warning to standard error that names the replacement and the release in which the old form will be removed.
- Change the default only after the warning period, and call the change out in the release notes.
Scripts can also protect themselves. An explicit --implementation flag in a script pins its behavior against changes to the defaults and against edits to project or user configuration, because the flag has the highest precedence. The trade-off is that the script will not pick up a deliberate upgrade of the default, so pinned scripts should be reviewed when the tool changes.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWhat the sources do not settle
The Command Line Interface Guidelines and the Fuchsia rubric establish the scope, semantics, precedence, documentation, and compatibility considerations. They do not prescribe a universal flag spelling, and they do not say whether your application should use a string option, a fixed set of named choices, a dependency-injection setting, or a subcommand. Those decisions depend on how many implementations exist, whether they share one interface, and whether they can change at runtime.
Microsoft’s ASP.NET Core 9.0 configuration documentation shows how command-line arguments can set configuration keys, and how a switch-mapping dictionary can translate short arguments into those keys. That is a feature of one framework, not a general command-line convention, and its details can change between framework versions, so confirm the current API before adopting the pattern. The examples in this article are conceptual and have not been run against a particular argument parser.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
