{"record":{"id":"be7d66ce07f7f96a","repo":"alibaba/open-code-review","slug":"q-s-positional-signature-valid-values-usa","errorCode":null,"errorMessage":"\"%q %s\" (+ positional signature, valid values, usage line, example) + \"Run '<command-path> --help' for more information.\"","messagePattern":"\"%q (.+?)\" \\(\\+ positional signature, valid values, usage line, example\\) \\+ \"Run '<command-path> --help' for more information\\.\"","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/opencodereview/arg_errors.go","lineNumber":73,"sourceCode":"\n\tif len(cmd.ValidArgs) > 0 {\n\t\tb.WriteString(\"\\n\\nValid values: \")\n\t\tb.WriteString(strings.Join(validArgNames(cmd.ValidArgs), \", \"))\n\t}\n\n\tb.WriteString(\"\\n\\nUsage:\\n  \")\n\tb.WriteString(cmd.UseLine())\n\n\tif example := strings.TrimRight(cmd.Example, \"\\n\"); example != \"\" {\n\t\tb.WriteString(\"\\n\\nExample:\\n\")\n\t\tb.WriteString(example)\n\t}\n\n\tb.WriteString(\"\\n\\nRun '\")\n\tb.WriteString(path)\n\tb.WriteString(\" --help' for more information.\")\n\n\treturn errors.New(b.String())\n}\n\n// positionalSignature extracts the positional-argument part of cmd.Use, e.g.\n// \"<key> <value>\" from \"set <key> <value>\" and \"<path...>\" from\n// \"rule [flags] <path...>\". Bracketed fields are not placeholders the user\n// types, so \"[flags]\" and inline enumerations such as \"[bash|zsh]\" are dropped;\n// enumerated values are reported from ValidArgs instead.\nfunc positionalSignature(cmd *cobra.Command) string {\n\tfields := strings.Fields(cmd.Use)\n\tif len(fields) < 2 {\n\t\treturn \"\"\n\t}\n\n\tparts := make([]string, 0, len(fields)-1)\n\tfor _, f := range fields[1:] {\n\t\tif strings.HasPrefix(f, \"<\") {\n\t\t\tparts = append(parts, f)\n\t\t}","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/alibaba/open-code-review/blob/5cf97d0d15cbd41b602513c4be3bfec3cee5bf7f/cmd/opencodereview/arg_errors.go#L55-L91","documentation":"argCountError builds a rich usage error: the invalid invocation with positional signature, valid values, usage line and an example, terminated by a pointer to '<command-path> --help'. It is thrown when a cobra command receives the wrong number of positional arguments.","triggerScenarios":"Invoking any ocr subcommand with a positional count that violates its Args validation — e.g. 'ocr rule' with no path, or 'ocr set' with fewer than two arguments.","commonSituations":"Typos that make a flag value look like a positional argument; forgetting an argument entirely; quoting mistakes splitting one argument into many; scripting with stale command syntax after an upgrade.","solutions":["Run the exact suggested command, e.g. 'ocr <command-path> --help', to see the canonical usage line and example.","Re-run with the correct number of positional arguments as shown in the usage line.","Quote arguments containing spaces so they count as a single positional.","Check the release notes/changelog for renamed or restructured subcommands if the syntax used to work."],"exampleFix":"// before\nocr rule\n// after\nocr rule .config/ocr/rules.yml   # see: ocr rule --help","handlingStrategy":"validation","validationCode":"// shell pre-check before invoking\ncase $# in\n  0) echo \"error: missing arguments; run 'ocr <command> --help'\" >&2; exit 2;;\nesac\nocr rule \"$@\"","typeGuard":null,"tryCatchPattern":"try:\n    subprocess.run(['ocr', 'rule', path], check=True)\nexcept subprocess.CalledProcessError as e:\n    print(e.stderr)  # contains the usage line and --help pointer\n    sys.exit(2)","preventionTips":["Run 'ocr <command> --help' before scripting a new subcommand","Quote arguments containing spaces so they count as single positionals","Pin the ocr version in CI to avoid silent CLI syntax changes","Count positionals against the cmd.Use signature shown in help"],"tags":["cli","argument-parsing","go"],"backgroundTag":"invalid-cli-argument","analyzedSha":"5cf97d0d15cbd41b602513c4be3bfec3cee5bf7f","analyzedAt":"2026-09-02T02:08:09.116Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}