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: %q in -%s

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.

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)

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.