larksuite/cli · error

alias[%d] name %q is invalid

Error message

alias[%d] name %q is invalid

What it means

Each alias declared in the cli tag must match aliasNamePattern (a restricted flag-name grammar). An alias name with illegal characters, leading/trailing dashes, spaces, or uppercase characters is rejected with its index and value.

Source

Thrown at shortcuts/common/typed_compile_args.go:344

			return fmt.Errorf("encoding comma_or_repeated only supports string or integer arrays")
		}
		if field.nullable != nil {
			return fmt.Errorf("encoding comma_or_repeated does not allow nullable/nonnullable")
		}
	case typedEncodingJSON:
		if kind != reflect.Slice && kind != reflect.Array && kind != reflect.Struct && kind != reflect.Map && kind != reflect.Interface {
			return fmt.Errorf("encoding json requires array, object, oneOf, or custom JSON input")
		}
		if isNilCapable(field.valueType) && field.nullable == nil && !field.shapeExplicit && !shapeExplicitlyNullable(field.shape) {
			return fmt.Errorf("nil-capable encoding=json input must declare nullable or nonnullable")
		}
	default:
		return fmt.Errorf("unknown CLI encoding %q", field.cli.Encoding)
	}
	seenAliases := make(map[string]struct{})
	for i, alias := range field.cli.Aliases {
		if !aliasNamePattern.MatchString(alias.Name) {
			return fmt.Errorf("alias[%d] name %q is invalid", i, alias.Name)
		}
		if alias.Name == field.name {
			return fmt.Errorf("alias[%d] duplicates canonical flag --%s", i, field.name)
		}
		if _, duplicate := seenAliases[alias.Name]; duplicate {
			return fmt.Errorf("duplicate alias --%s", alias.Name)
		}
		seenAliases[alias.Name] = struct{}{}
		switch alias.Mode {
		case typedAliasNormalize:
			if alias.Conflict != "" {
				return fmt.Errorf("normalize alias --%s cannot declare Conflict", alias.Name)
			}
			if alias.Deprecated {
				return fmt.Errorf("deprecated alias --%s must use independent mode so Cobra can emit its warning", alias.Name)
			}
		case typedAliasIndependent:
			switch alias.Conflict {

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Rewrite the alias to a lowercase kebab-style flag name matching aliasNamePattern (no -- prefix, no spaces/symbols beyond the allowed set).
2. Check the pattern definition near the top of typed_compile_args.go for the exact grammar.
3. Drop the alias if a legal name is not needed; the canonical flag already works.

Example fix

// before
cli:"alias=Camel Alias"
// after
cli:"alias=camel-alias"

var aliasNamePattern = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`) // confirm exact pattern in typed_compile_args.go
func validAliasName(name string) error {
	if !aliasNamePattern.MatchString(name) {
		return fmt.Errorf("alias %q invalid: use lowercase kebab, no -- prefix", name)
	}
	return nil
}

When it happens

Trigger: cli tag declares an alias like `-t` (extra leading dash), `my Alias` (space), `CamelCase`, or `user.email`; aliasNamePattern.MatchString fails during validateInputCLI.

Common situations: Hand-writing aliases with punctuation or mixed case; assuming alias names follow the same leniency as arbitrary strings; including the -- prefix in the alias name.

Related errors

• alias[%d] duplicates canonical flag --%s
• duplicate alias --%s
• normalize alias --%s cannot declare Conflict
• encoding comma_or_repeated requires an array or slice
• encoding comma_or_repeated only supports string or integer a

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/4ecae9dba6d24ab8. Report an issue: GitHub.