Current limitations and gotchas

How do I...? · Commands · Options

These are current v1.6.1 boundaries verified against the public source and tests. They are intentionally easy to find so a limitation does not look like an undocumented feature.

Command model

• Positional arguments are not supported.
• The -- option terminator is not supported because positional arguments are not supported yet.
• Root-command options belong only to the root action. Named commands and subcommands do not inherit them.
• The framework has no persistent/global option model across a command tree.
• A command group does not inherit child options.
• Built-in -v/--version are reserved case-insensitively at every scope and skip execution. This is independent of the lack of inherited user options.

Values and validation

• GetParameterValue returns strings. Convert validated integers, floats, and Booleans in your command code.
• An absent AddFlag normally yields the default string false; inspect the returned value rather than treating the helper's Boolean result as a “was supplied” indicator.
• AddBooleanParameter accepts true/false; bare presence is also interpreted as true for 1.x compatibility.
• A Path parameter validates only that a value was provided. Check existence, permissions, and path policy in your command.
• A password is an ordinary string after retrieval. Framework debug output redacts registered password values, but your output and external logging must redact them too.
• A URL validator accepts only values beginning with http://, https://, git://, or ssh://.
• Registered integer and float options accept negative values in either --count=-1 or --count -1 form. For another value beginning with -, use the equals form so it is not read as a new option.
• Option flags are matched case-insensitively. If an option appears more than once, the last occurrence wins across short and long aliases. Equals syntax is supported for long options; short aliases take separated values.
• Float parsing uses the process locale's decimal separator.
• An omitted Boolean without a default returns False from lookup but places 'false' in the output. Empty non-Boolean values fall back to a non-empty default; otherwise lookup returns False with an empty string.

Completion

• Built-in completion covers registered commands, subcommands, options, Boolean values, and enum choices.
• Dynamic/custom completion callbacks are deprecated no-op methods in the 1.x API. They do not supply filesystem, database, or API candidates.

If one of these boundaries blocks your design, use a small application-level parser around the framework or open an issue with a concrete desired command line and expected behavior. Do not rely on a roadmap item as though it were a released feature.