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

Replace the unknown token with a supported key: `sources` or `encoding`

unknown cli token %q

Error message

unknown cli token %q

What it means

parseCLITag only accepts the tokens `sources` (pipe-separated value list) and `encoding`; any other key in a `cli:"..."` tag is rejected with this error. This keeps the typed-input CLI metadata grammar closed so typos cannot silently become no-op options. It surfaces as a build-time declaration error when the command set is compiled.

Source

Thrown at shortcuts/common/typed_compile_args.go:538

	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
}

func parseFiniteFloat(value string) (float64, error) {
	return parseFiniteFloatBits(value, 64)
}

func parseFiniteFloatBits(value string, bits int) (float64, error) {
	parsed, err := strconv.ParseFloat(value, bits)
	if err != nil {
		return 0, err
	}
	if math.IsNaN(parsed) || math.IsInf(parsed, 0) {
		return 0, fmt.Errorf("must be finite")
	}
	return parsed, nil

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Replace the unknown token with a supported key: `sources` or `encoding`
Check spelling against the supported keys in typed_compile_args.go
Move any non-tag configuration to a supported struct tag or code, not the cli tag

Example fix

// before
Field string `cli:"source=a|b"`
// after
Field string `cli:"sources=a|b"`

Defensive patterns

Strategy: validation

Validate before calling

var allowedCLITokens = map[string]bool{"sources": true, "encoding": true}
func validateCLITagTokens(raw string) error {
	for _, tok := range strings.Split(raw, ";") {
		key, _, ok := strings.Cut(tok, "=")
		if !ok || !allowedCLITokens[key] { return fmt.Errorf("unknown cli token %q", key) }
	}
	return nil
}

Prevention

Only use the documented keys: sources and encoding
Copy tag examples from the repository rather than inventing syntax
Add a compile-time test that parses all cli tags in the package

When it happens

Trigger: Writing an unrecognized token in a cli tag, e.g. `cli:"source=a|b"` (singular) or `cli:"env=prod"`; a misspelling like `encodings=json`.

Common situations: Typo when hand-writing tags; inventing options that the tag grammar does not support; copying tag syntax from a different framework.

Related errors

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