What causes "unknown shorthand flag: %q in -%s" in JanDeDobbeleer/oh-my-posh?

Use the correct registered shorthand (check the command's help output under Flags).

unknown shorthand flag

Error message

unknown shorthand flag: %q in -%s

What it means

parseShort walks each character of a '-abc' shorthand group and looks each one up in the FlagSet's shorthand map. If a character has no registered shorthand and ParseErrorsAllowlist.UnknownFlags is false, the parser stops with this error naming the offending character and the remaining group.

Solutions

Use the correct registered shorthand (check the command's help output under Flags).
Spell the flag in long form (--name) which is often easier to get right.
Register the shorthand via StringVarP/BoolVarP/etc. if you control the CLI.
Set ParseErrorsAllowlist.UnknownFlags = true to ignore unknown shorthand groups instead of failing.

Example fix

// before
args := []string{"-z"} // unknown shorthand flag: 'z' in -z
// after
args := []string{"--config", "file"} // or register: fs.StringVarP(&cfg, "config", "c", "", "config file")

Defensive patterns

Strategy: validation

Validate before calling

func validateShorthands(fs *cmdflag.FlagSet, args []string) error {
    for _, a := range args {
        if len(a) > 1 && a[0] == '-' && a[1] != '-' {
            for _, c := range a[1:] {
                ch := string(c)
                if ch != "=" && fs.ShorthandLookup(ch) == nil {
                    return fmt.Errorf("shorthand -%s is not registered", ch)
                }
            }
        }
    }
    return nil
}

Type guard

func hasShorthand(fs *cmdflag.FlagSet, short string) bool {
    return fs.ShorthandLookup(short) != nil
}

Try / catch

if err := cmd.Execute(); err != nil {
    if strings.HasPrefix(err.Error(), "unknown shorthand flag:") {
        fmt.Fprintf(os.Stderr, "%v\nTip: use the long form (--name) or check -h.\n", err)
        os.Exit(2)
    }
    return err
}

Prevention

Check the Flags section of --help for exact shorthand letters before scripting.
Prefer long flags in scripts; they are self-documenting and typo-resistant.
Re-verify shorthands after CLI upgrades - they can change between versions.
Note shorthands are single characters; combining them in clusters requires each to be registered.

When it happens

Trigger: Parse called with a '-x...' token where character x (or any later character in the cluster) was never registered via a *VarP shorthand parameter, and UnknownFlags allowlisting is off.

Common situations: Muscle-memory from other CLIs (-v meaning something else here, or being long-only); scripts combining shorthands that don't exist; typos like -V vs -v; users of the old cobra/flag-based CLI using shorthands that were dropped in a rewrite.

Related errors

AI-assisted analysis of JanDeDobbeleer/oh-my-posh@0976794618 (2026-08-31). Data as JSON: /api/errors/5d1654882c3eda24. Report an issue: GitHub.

Appendix: source

Thrown at src/cmdflag/cmdflag.go:327

}

func (f *FlagSet) parseShort(shorthands string, rest []string) ([]string, error) {
	for len(shorthands) > 0 {
		c := shorthands[0]

		flag := f.shorthands[c]
		if flag == nil {
			if f.ParseErrorsAllowlist.UnknownFlags {
				// drop the remainder of the group and a
				// separate value token unless it is itself a flag
				if len(shorthands) == 1 && len(rest) > 0 && !strings.HasPrefix(rest[0], "-") {
					return rest[1:], nil
				}

				return rest, nil
			}

			return rest, fmt.Errorf("unknown shorthand flag: %q in -%s", c, shorthands)
		}

		value := ""

		switch {
		case len(shorthands) > 2 && shorthands[1] == '=':
			value = shorthands[2:]
			shorthands = ""
		case flag.Value.Type() == boolType:
			value = trueStr
			shorthands = shorthands[1:]
		case len(shorthands) > 1:
			value = shorthands[1:]
			shorthands = ""
		case len(rest) > 0:
			value = rest[0]
			rest = rest[1:]
			shorthands = ""

View on GitHub (pinned to 0976794618)