apple/pkl · info · PrintHelpMessage

<prints command help>

Error message

<prints command help>

What it means

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.

Solutions

1. Read the printed help to see required arguments and options
2. Re-run with the module argument, e.g. `pkl run script.pkl`
3. If help was unintended, check flag parsing of your wrapper (an accidental help flag was passed)

Example fix

// before
pkl run --help
// after
pkl run script.pkl

// if help was requested, print usage instead of failing
[[ " $* " == *" --help "* ]] && { pkl run --help; exit 0; }

try { runCmd.run() }
catch (e: PrintHelpMessage) { printHelp(e.context); } // normal exit path

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

• <prints command help and exits with code 1>
• commandArgumentsMultipleRepeated
• commandArgumentUnexpectedNonRepeatedNullableType
• commandFlagInvalidType
• commandFlagNameCollision

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/531ecc2b1303f129. Report an issue: GitHub.

Appendix: source

Thrown at pkl-cli/src/main/kotlin/org/pkl/cli/commands/RunCommand.kt:67

  private val showHelp by option("-h", "--help", help = "Show this message and exit").flag()

  val module: URI? by
    argument(
        name = "module",
        help = "Root pkl:Command module to invoke.",
        completionCandidates = CompletionCandidates.Path,
      )
      .convert { BaseOptions.parseModuleName(it) }
      .optional()

  val args: List<String> by argument(name = "args").multiple()

  private val projectOptions by ProjectOptions()

  override fun run() {
    // if no module is specified but --help is show help, otherwise error becuase module is missing
    if (module == null)
      if (showHelp) throw PrintHelpMessage(currentContext)
      else throw MissingArgument(registeredArguments().find { it.name == "module" }!!)

    val reservedFlagNames = mutableSetOf("help")
    val reservedFlagShortNames = mutableSetOf("h")
    registeredOptions().forEach { opt ->
      (opt.names + opt.secondaryNames).forEach {
        if (it.startsWith("--")) reservedFlagNames.add(it.trimStart('-'))
        else reservedFlagShortNames.add(it.trimStart('-'))
      }
    }
    CliCommandRunner(
        baseOptions.baseOptions(listOf(module!!), projectOptions),
        reservedFlagNames,
        reservedFlagShortNames,
        if (showHelp) args + listOf("--help") else args,
      )
      .run()
  }

View on GitHub (pinned to f3efcbfc9b)