{"record":{"id":"e851bd2f650355fe","repo":"apple/pkl","slug":"prints-command-help-and-exits-with-code-1","errorCode":null,"errorMessage":"<prints command help and exits with code 1>","messagePattern":"<prints command help and exits with code 1>","errorType":"console","errorClass":"PrintHelpMessage","httpStatus":null,"severity":"warning","filePath":"pkl-cli/src/main/kotlin/org/pkl/cli/CliCommandRunner.kt","lineNumber":255,"sourceCode":"\n      val opts =\n        registeredOptions()\n          .mapNotNull {\n            val opt = it as? OptionWithValues<*, *, *> ?: return@mapNotNull null\n            return@mapNotNull if (it.names.contains(\"--help\")) null\n            else it.names.last().trimStart('-') to opt.value\n          }\n          .toMap() +\n          registeredArguments()\n            .mapNotNull { it as? ArgumentDelegate<*> }\n            .associateBy({ it.name }, { it.value })\n\n      val state = spec.apply.apply(opts, currentContext.obj as CommandSpec.State?)\n      currentContext.obj = state\n\n      if (currentContext.invokedSubcommand != null) return\n      if (spec.subcommands.isNotEmpty() && spec.noOp) {\n        throw PrintHelpMessage(currentContext, true, 1)\n      }\n\n      val result = state.evaluate()\n      runner.writeOutput(result.outputBytes)\n      runner.writeMultipleFileOutput(result.outputFiles)\n    }\n  }\n}\n\nfun CommandSpec.CompletionCandidates.toClikt(): CompletionCandidates =\n  when (this) {\n    CommandSpec.CompletionCandidates.PATH -> CompletionCandidates.Path\n    is CommandSpec.CompletionCandidates.Fixed -> CompletionCandidates.Fixed(values)\n    else -> throw PklBugException.unreachableCode()\n  }\n","sourceCodeStart":237,"sourceCodeEnd":271,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-cli/src/main/kotlin/org/pkl/cli/CliCommandRunner.kt#L237-L271","documentation":"When a command that only dispatches to subcommands is invoked without choosing a subcommand, run() throws PrintHelpMessage(currentContext, true, 1): the CLI prints the command's help text and exits with status code 1. It is a controlled error, not a crash — the library uses it to tell the user which subcommands exist.","triggerScenarios":"Invoking a group command with noOp=true and non-empty subcommands without specifying any subcommand, e.g. `pkl` with no verb, or `pkl project` alone; spec.apply succeeds but invokedSubcommand is null.","commonSituations":"Running the bare command in scripts expecting default behavior; typo in the subcommand name so no subcommand was matched; users exploring the CLI interactively.","solutions":["Specify a subcommand, e.g. `pkl eval ...` or `pkl test ...`","Run `pkl --help` (or `<command> --help`) to list available subcommands","Fix script/alias that omitted the subcommand name"],"exampleFix":"// before\npkl\n// after\npkl eval script.pkl","handlingStrategy":"fallback","validationCode":"// only proceed when a subcommand is present\nif [ $# -eq 0 ]; then echo \"usage: pkl <subcommand> ...\"; exit 1; fi","typeGuard":null,"tryCatchPattern":"// PrintHelpMessage is control flow: catch and treat exit code 1 as usage help\ntry { cmd.execute(args) }\ncatch (e: PrintHelpMessage) { print(e.helpText); exitProcess(1) }","preventionTips":["Always pass an explicit subcommand (eval, test, run, project...)","Read the printed help instead of retrying the bare command","Wrap group commands so a missing subcommand surfaces usage text"],"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"}