{"record":{"id":"039796d5070cd3df","repo":"larksuite/cli","slug":"s-input-must-explicitly-declare-cli-encoding","errorCode":null,"errorMessage":"%s input must explicitly declare CLI encoding","messagePattern":"(.+?) input must explicitly declare CLI encoding","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"shortcuts/common/typed_compile_args.go","lineNumber":302,"sourceCode":"\t\t\treturn fmt.Errorf(\"unknown value source %q\", source)\n\t\t}\n\t\tif _, duplicate := seenSources[source]; duplicate {\n\t\t\treturn fmt.Errorf(\"duplicate value source %q\", source)\n\t\t}\n\t\tseenSources[source] = struct{}{}\n\t}\n\tif len(field.cli.ValueSources) > 0 {\n\t\tif _, ok := seenSources[typedSourceFlag]; !ok {\n\t\t\treturn fmt.Errorf(\"ValueSources must include flag\")\n\t\t}\n\t\tif (len(seenSources) > 1) && indirectKind(field.valueType) != reflect.String && field.cli.Encoding != typedEncodingJSON {\n\t\t\treturn fmt.Errorf(\"file/stdin sources require string input or encoding=json\")\n\t\t}\n\t}\n\tkind := indirectKind(field.valueType)\n\tif kind == reflect.Slice || kind == reflect.Array || kind == reflect.Struct || kind == reflect.Map || kind == reflect.Interface {\n\t\tif field.cli.Encoding == \"\" {\n\t\t\treturn fmt.Errorf(\"%s input must explicitly declare CLI encoding\", kind)\n\t\t}\n\t}\n\tswitch field.cli.Encoding {\n\tcase \"\":\n\t\tif kind == reflect.Slice || kind == reflect.Array || kind == reflect.Struct || kind == reflect.Map || kind == reflect.Interface {\n\t\t\treturn fmt.Errorf(\"complex input requires encoding\")\n\t\t}\n\tcase typedEncodingRepeated:\n\t\tif kind != reflect.Slice && kind != reflect.Array {\n\t\t\treturn fmt.Errorf(\"encoding repeated requires an array or slice\")\n\t\t}\n\t\tif indirectType(field.valueType).Elem().Kind() != reflect.String {\n\t\t\treturn fmt.Errorf(\"encoding repeated only supports string arrays\")\n\t\t}\n\t\tif field.nullable != nil {\n\t\t\treturn fmt.Errorf(\"encoding repeated does not allow nullable/nonnullable\")\n\t\t}\n\tcase typedEncodingCommaOrRepeated:","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/shortcuts/common/typed_compile_args.go#L284-L320","documentation":"Complex value types (slice, array, struct, map, interface) cannot be converted from a single CLI string without an explicit encoding rule. validateInputCLI requires such fields to declare field.cli.Encoding explicitly; an empty encoding on a complex kind is rejected with the kind named in the message.","triggerScenarios":"Declaring an input field whose indirect kind is slice/array/struct/map/interface via the cli tag or InputField.CLI while leaving Encoding empty. Raised by compileInput during shortcut compilation.","commonSituations":"Adding a []string or struct input to a shortcut and forgetting to say how CLI text maps to it; relying on a default encoding that no longer exists after a library change; auto-generating fields where the encoding field was skipped.","solutions":["Declare the encoding explicitly: \"json\" for JSON bodies, \"repeated\" for string arrays, or \"comma_or_repeated\" for string/integer arrays","Change a simple []string field to encoding repeated instead of json if each element is a separate flag occurrence","If the field is actually scalar, simplify the value type so no encoding is needed"],"exampleFix":"// before\ncli:\"--items\" // []string field with no encoding\n// after\ncli:\"--items,encoding=repeated\"","handlingStrategy":"validation","validationCode":"func needsEncoding(t reflect.Type) bool {\n\tk := t\n\tfor k.Kind() == reflect.Ptr {\n\t\tk = k.Elem()\n\t}\n\tswitch k.Kind() {\n\tcase reflect.Slice, reflect.Array, reflect.Struct, reflect.Map, reflect.Interface:\n\t\treturn true\n\t}\n\treturn false\n}\n// if needsEncoding(t) { require cli.Encoding != \"\" }","typeGuard":null,"tryCatchPattern":"if err := compileInput(...); err != nil {\n\tif strings.Contains(err.Error(), \"must explicitly declare CLI encoding\") {\n\t\t// add encoding=json / repeated / comma_or_repeated to the tag\n\t}\n\treturn err\n}","preventionTips":["Whenever adding a slice/struct/map input, decide the encoding at the same time","Run `lark-cli <cmd> --help` and `schema` after changes to confirm the field compiles","Keep a compile-all-shortcuts test in CI"],"tags":["cli","shortcut-input","encoding","complex-types"],"backgroundTag":"cli-input-encoding-required","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}