{"record":{"id":"531ecc2b1303f129","repo":"apple/pkl","slug":"prints-command-help","errorCode":null,"errorMessage":"<prints command help>","messagePattern":"<prints command help>","errorType":"console","errorClass":"PrintHelpMessage","httpStatus":null,"severity":"info","filePath":"pkl-cli/src/main/kotlin/org/pkl/cli/commands/RunCommand.kt","lineNumber":67,"sourceCode":"  private val showHelp by option(\"-h\", \"--help\", help = \"Show this message and exit\").flag()\n\n  val module: URI? by\n    argument(\n        name = \"module\",\n        help = \"Root pkl:Command module to invoke.\",\n        completionCandidates = CompletionCandidates.Path,\n      )\n      .convert { BaseOptions.parseModuleName(it) }\n      .optional()\n\n  val args: List<String> by argument(name = \"args\").multiple()\n\n  private val projectOptions by ProjectOptions()\n\n  override fun run() {\n    // if no module is specified but --help is show help, otherwise error becuase module is missing\n    if (module == null)\n      if (showHelp) throw PrintHelpMessage(currentContext)\n      else throw MissingArgument(registeredArguments().find { it.name == \"module\" }!!)\n\n    val reservedFlagNames = mutableSetOf(\"help\")\n    val reservedFlagShortNames = mutableSetOf(\"h\")\n    registeredOptions().forEach { opt ->\n      (opt.names + opt.secondaryNames).forEach {\n        if (it.startsWith(\"--\")) reservedFlagNames.add(it.trimStart('-'))\n        else reservedFlagShortNames.add(it.trimStart('-'))\n      }\n    }\n    CliCommandRunner(\n        baseOptions.baseOptions(listOf(module!!), projectOptions),\n        reservedFlagNames,\n        reservedFlagShortNames,\n        if (showHelp) args + listOf(\"--help\") else args,\n      )\n      .run()\n  }","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-cli/src/main/kotlin/org/pkl/cli/commands/RunCommand.kt#L49-L85","documentation":"In RunCommand.run(), if no module argument was given the command distinguishes two cases: if --help/--version style showHelp was requested it throws PrintHelpMessage(currentContext), which prints the command help and exits normally; otherwise it falls through to the MissingArgument error. This entry covers the help-printing branch.","triggerScenarios":"Running `pkl run` with no module but with the help flag (e.g. `pkl run --help` or a showHelp condition set), so instead of an error message the full command help is printed.","commonSituations":"Users typing `pkl run --help` to learn usage; CI wrappers probing available flags; mistyping arguments so module is null while a help-ish flag was consumed.","solutions":["Read the printed help to see required arguments and options","Re-run with the module argument, e.g. `pkl run script.pkl`","If help was unintended, check flag parsing of your wrapper (an accidental help flag was passed)"],"exampleFix":"// before\npkl run --help\n// after\npkl run script.pkl","handlingStrategy":"fallback","validationCode":"// if help was requested, print usage instead of failing\n[[ \" $* \" == *\" --help \"* ]] && { pkl run --help; exit 0; }","typeGuard":null,"tryCatchPattern":"try { runCmd.run() }\ncatch (e: PrintHelpMessage) { printHelp(e.context); } // normal exit path","preventionTips":["Treat `--help` output as the source of truth for required args","Don't pass stray help-like flags in automation","After seeing help, re-run with the module argument"],"tags":["cli","pkl","help","usage"],"backgroundTag":"missing-cli-argument","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}