What causes "invalid cli token %q" in larksuite/cli?

Write every token as key=value with no spaces around tokens or semicolons.

invalid cli token %q

Error message

invalid cli token %q

What it means

parseCLITag parses the `cli` struct tag's semicolon-separated tokens. Each token must be `key=value`, non-empty on the value side, and free of surrounding whitespace. A token missing '=', with an empty value, or with leading/trailing spaces is rejected with this error at compile time.

Source

Thrown at shortcuts/common/typed_compile_args.go:524

	if result.minimum != nil && result.maximum != nil && *result.minimum > *result.maximum {
		return result, fmt.Errorf("minimum exceeds maximum")
	}
	if result.minItems != nil && result.maxItems != nil && *result.minItems > *result.maxItems {
		return result, fmt.Errorf("minItems exceeds maxItems")
	}
	return result, nil
}

func parseCLITag(raw string) (typedCLIInput, error) {
	var result typedCLIInput
	if raw == "" {
		return result, nil
	}
	seen := make(map[string]struct{})
	for _, token := range strings.Split(raw, ";") {
		key, value, ok := strings.Cut(token, "=")
		if !ok || value == "" || token != strings.TrimSpace(token) {
			return result, fmt.Errorf("invalid cli token %q", token)
		}
		if _, duplicate := seen[key]; duplicate {
			return result, fmt.Errorf("cli token %q is duplicated", key)
		}
		seen[key] = struct{}{}
		switch key {
		case "sources":
			for _, source := range strings.Split(value, "|") {
				result.ValueSources = append(result.ValueSources, typedValueSource(source))
			}
		case "encoding":
			result.Encoding = typedCLIEncoding(value)
		default:
			return result, fmt.Errorf("unknown cli token %q", key)
		}
	}
	return result, nil
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Write every token as key=value with no spaces around tokens or semicolons.
Provide a non-empty value for every token, e.g. cli:"encoding=json".
Remove tokens that need no value; use the schema tag for required/optional style flags.

Example fix

// before
Payload string `schema:"required" cli:"sources=stdin; encoding=json"`
// after
Payload string `schema:"required" cli:"sources=stdin;encoding=json"`

Defensive patterns

Strategy: validation

Validate before calling

func cliTagTokensWellFormed(tag string) bool {
	for _, tok := range strings.Split(tag, ";") {
		if tok != strings.TrimSpace(tok) {
			return false
		}
		_, v, ok := strings.Cut(tok, "=")
		if !ok || v == "" {
			return false
		}
	}
	return true
}

Prevention

Never put spaces after semicolons in the cli tag; the grammar is strict.
Every token must be key=value with a non-empty value.
Copy an existing valid cli tag as a template when adding new fields.

When it happens

Trigger: Tags like cli:"sources" (no =), cli:"encoding=" (empty value), or cli:" encoding=json" (untrimmed) on a typed shortcut input field.

Common situations: Formatting the tag with spaces after semicolons for readability (e.g. "sources=env; encoding=json"), forgetting the value, or using the wrong separator order.

Related errors

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