Quotes required to use the built-in help command with a nested subcommand

[paul-papacz]

• I am on the latest Poetry version.
• I have searched the issues of this repo and believe that this is not a duplicate.
• If an exception occurs when executing a command, I executed it again in debug mode (-vvv option).

• OS version and name: Ubuntu 22.04
• Poetry version: 1.2.0
• Link of a Gist with the contents of your pyproject.toml file: NOT RELEVANT

Issue

After installing poetry via curl -sSL https://install.python-poetry.org | python3 - when running

$ poetry help env

the following error occurs:

The command "env" does not exist.

Did you mean one of these?
    env use
    env info
    env list
    env remove

When running

$ poetry help env use

the exact same error occurs.

When running

$ poetry help "env use"

the help message is shown correctly:

Description:
  Activates or creates a new virtualenv for the current project.

Usage:
  env use [options] [--] <python>

Arguments:
  python                The python executable to use.

Options:
  -h, --help            Display help for the given command. When no command is given display help for the list command.
  -q, --quiet           Do not output any message.
  -V, --version         Display this application version.
      --ansi            Force ANSI output.
      --no-ansi         Disable ANSI output.
  -n, --no-interaction  Do not ask any interactive question.
      --no-plugins      Disables plugins.
      --no-cache        Disables Poetry source caches.
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.

[ulisesojeda]

I think you missed this step from the installation script

To get started you need Poetry's bin directory (/root/.local/bin) in your PATH
environment variable.
Add export PATH="/root/.local/bin:$PATH" to your shell configuration file.
Alternatively, you can call Poetry explicitly with /root/.local/bin/poetry.

[neersighted]

@ulisesojeda Thanks for trying to help, but in this case Poetry is invoked correctly and the usage of poetry help is surprising.

I'm migrating this to a Cleo issue as ultimately this related to Cleo nested subcommands and command parsing.

[neersighted]

Cleo needs to parse subcommands during <app> help the same way they are parsed during <app> <category> <command>, as well as possibly offer category-level help (though that is tangential and the existing hints are decent).

[L01i74]

I just installed Poetry and noticed the same issue. Since this issue is still open, I examined the code.

It seems like the invocation of:

$ poetry help env use

results in the following execution flow, ultimately causing this behavior:

• Default Definition Handling: Poetry sets its _default_definition (from poetry.console.application) to the Definition returned by cleo.application.Application._default_definition, supplemented with additional options.

• Command Execution Flow: The flow progresses to cleo.application.Application._run → cleo.application.Application._run_command, which then invokes command.merge_application_definition() that merges the definition args: "command" (cleo.application.Application._default_definition) and "command_name" (HelpCommand).

• Argument Parsing: Consequently, the cleo.io.inputs.argv_input.ArgvInput.arguments dictionary (self.arguments in cleo.io.inputs.argv_input.ArgvInput._parse_argument) evaluates to {'command': ..., 'command_name': ...}. Initially, cleo.io.inputs.argv_input.ArgvInput._arguments is empty ({}), and the local variable next_argument in _parse_argument evaluates sequentially to 0 and 1 for cleo.io.inputs.argv_input.ArgvInput.arguments._tokens[:2]. Also:

  The first if clause (if self._definition.has_argument(next_argument)) succeeds when next_argument is less than 2 (len({'command': ..., 'command_name': ...}) = 2).
  However, tokens beyond the first two (cleo.io.inputs.argv_input.ArgvInput.arguments._tokens[2:]) all evaluate to False. They fail the second elif clause because the Argument defined in cleo.commands.help_command.HelpCommand isn’t a list, causing self._definition.argument(last_argument).is_list() to return False.

  In other words, every argument whose position is greater than or equal to 2 (starting at 1, right after 'help') is treated as an 'Unexpected argument'.

The following code modifications worked for me:

• The arguments in HelpCommand could be modified as follows:

    arguments: ClassVar[list[Argument]] = [
    	Argument(
    		"command_name",
    		required=False,
    		description="The command name",
    		default=["help"],
    		is_list=True
    	)
    ]
  

• Additionally, I changed self._command = self._application.find(self.argument("command_name")) to:

    command_name = " ".join(self.argument("command_name"))
    self._command = self._application.find(command_name)
  

These changes made $ poetry help env use and $ poetry help "env use" yield the same results.
However, I didn’t review the entire Cleo codebase, so there’s a possibility this modification could introduce inconsistencies elsewhere.