{"record":{"id":"3f279d8efdd3d50d","repo":"larksuite/cli","slug":"positional-arguments-are-not-supported-got-q-p","errorCode":null,"errorMessage":"positional arguments are not supported (got %q); pass values via flags","messagePattern":"positional arguments are not supported \\(got %q\\); pass values via flags","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"shortcuts/common/runner.go","lineNumber":1420,"sourceCode":"\t\tFormat:      rctx.Format,\n\t\tJqExpr:      rctx.JqExpr,\n\t\tCommandPath: rctx.Cmd.CommandPath(),\n\t\tIdentity:    rctx.As(),\n\t\tOut:         f.IOStreams.Out,\n\t\tErrOut:      f.IOStreams.ErrOut,\n\t})\n}\n\n// rejectPositionalArgs returns a cobra.PositionalArgs that rejects any\n// positional arguments. It returns a plain cobra usage error; the root\n// handler classifies it into the typed validation envelope (exit 2), the\n// same path as other cobra usage failures.\nfunc rejectPositionalArgs() cobra.PositionalArgs {\n\treturn func(cmd *cobra.Command, args []string) error {\n\t\tif len(args) == 0 {\n\t\t\treturn nil\n\t\t}\n\t\treturn fmt.Errorf(\"positional arguments are not supported (got %q); pass values via flags\", args)\n\t}\n}\n\n// registerShortcutFlags adds the shortcut's declared flags to its Cobra command.\nfunc registerShortcutFlags(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut) {\n\tregisterShortcutFlagsWithContext(context.Background(), cmd, f, s)\n}\n\n// shortcutDeclaresJSONFlag reports whether the shortcut itself declares a flag\n// named \"json\" in its Flags list (custom semantics, e.g. event +subscribe's\n// pretty-print switch or base +record-search's request-body payload).\n// Framework-injected flags never appear in s.Flags, so this cleanly separates\n// \"self-declared json\" from \"injected shorthand\".\nfunc shortcutDeclaresJSONFlag(s *Shortcut) bool {\n\tfor _, fl := range s.Flags {\n\t\tif fl.Name == \"json\" {\n\t\t\treturn true\n\t\t}","sourceCodeStart":1402,"sourceCodeEnd":1438,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/shortcuts/common/runner.go#L1402-L1438","documentation":"Cobra positional-args validator rejectPositionalArgs rejects any non-flag argument. Lark CLI shortcuts require all values to be passed as named flags; bare words are rejected with the offending args quoted (%q of the []string).","triggerScenarios":"Invoking a shortcut like `lark-cli doc create mydoc` instead of `lark-cli doc create --title mydoc`; shell word-splitting or unquoted spaces adding extra tokens; pasting examples that use positional syntax from other CLIs.","commonSituations":"Muscle memory from other CLIs; forgetting --flag= before a value; unquoted paths with spaces producing extra positional tokens.","solutions":["Convert every value to its declared flag form: --flag value or --flag=value","Quote values containing spaces so they stay one token","Run the command with --help to see the exact flag names"],"exampleFix":"// before\nlark-cli doc create \"My Doc\"\n// after\nlark-cli doc create --title \"My Doc\"","handlingStrategy":"validation","validationCode":"lark-cli <cmd> --help   # confirm all values are flags before running","typeGuard":"if len(os.Args) > 1 && !strings.HasPrefix(os.Args[len(os.Args)-1], \"-\") { /* last token is positional — likely wrong */ }","tryCatchPattern":"cmd.SilenceUsage = false // let cobra print usage alongside the validator error","preventionTips":["Always use --flag value syntax for shortcut inputs","Quote arguments containing spaces","Run --help first when copying examples from other CLIs"],"tags":["cli-usage","arguments","cobra"],"backgroundTag":"unexpected-positional-argument","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"}