CLI argument to `poetry add` to add the dependency to `[tool.poetry.extras]`

Issue Kind

Brand new capability

Description

• Add an info to the poetry add help that states that dependency groups aren't equivalent to groups of extras and have no parallel in pip.

• Add an argument to poetry add which requires --optional let's say for the sake of argument -i --include-in.
  Providing that argument, adds the dependency into the list of dependencies of an extra:

So doing something like poetry add --optional -i cuda cupy would now additionally:

1. Add the section [tool.poetry.extras] if it doesn't exist.
2. Add the extra cuda if it doesn't exits.
3. Add cupy into the dependency list of cuda if it doesn't exist. So you end up with:

[tool.poetry.extras]
cuda = ["cupy"]

• Maybe add a command to edit, remove, add, list the extras of the project you're working on.

Impact

How it should affect other users

• The improved documentation for the dependency groups as well as potentially highlighting the word "dependency" in the poetry add help should reduce frustration for new users of poetry which also primarily look at the help of commands and not the docs online. (Also poetry doesn't have a man page you could consult).
• Adding the option to add a dependency to the pip extras of the package you're currently working on gives you the changes in the pyproject.toml that you could figure out afterwards how to change the config manually. (So once again, no requirement to read the docs online)
• Adding commands to edit the [tool.poetry.extras] would seem to be inline with the purpose of poetry which is, as far as I understand: Managing / Resolving Dependencies and Facilitating easier Packaging for Python Projects.

Lastly, it's my conviction that cli tools should contain everything needed to operate them in their help section. And not require the user to leave the shell and look up the docs in a browser.

---

How it affected me

I've sadly spent an entire day trying to get my package to have an optional dependency. It also may be very well possible that I'm stupid and just didn't read the docs and only referred to the help of poetry in the cli.

It firstly took me some time to figure out that if you poetry add -E some-extra package will add some-package[some-extra] to your install dependencies. That's my bad for not reading the documentation closely enough. Tho maybe the formulation of the help could be improved or the word "dependency" could be highlighted?

Another thing that took me for a ride were the dependency groups. I thought they were equivalent to the extras you can define for your package.

Since, when not using poetry, you have something like:

[project.optional-dependencies]
gui = ["PyQt5"]
cli = [
  "rich",
  "click",
]

I accidentally equated the poetry dependency groups to the project.optional-dependencies. I was mostly looking at the output of poetry [build, add, install] --help for information. I think it might be useful to put in the note that dependency groups are something unique to poetry and they have no parallel with pip / pypi.

(It would be also a cool idea to have dependency groups be marked as an extra for pip but I think that diverges too much from the established ux that poetry has)

After figuring out that dependency groups and the -E flag for poetry add weren't the right way to go, I finally left my terminal and looked at the docs to finally learn that you can only add extras to your package the following way:

1. Add the dependency as optional to the main group so poetry add --optional some-package
2. Modify the pyproject.toml to contain the following:

[tool.poetry.extras]
extra_name = ["list-of-extra-deps-in-main-section"]

I had the preconceived notion that everything regarding configs with poetry is only handled through the shell. I was not expecting to manually edit config files. Now this can be argued as an me issue and being an new poetry user.

Workarounds

1. Add the dependency as optional to the main group so poetry add --optional some-package
2. Modify the pyproject.toml to contain the following:

[tool.poetry.extras]
extra_name = ["list-of-extra-deps-in-main-section"]

The somewhat confusing part is having to edit the pyproject.toml yourself.

Start by reviewing the current poetry add --help, the existing --optional and -E behavior, and the documented pyproject.toml extras workflow. Clarify which parts of the request are in scope, including help text, adding dependencies to [tool.poetry.extras], and possible extras management commands. Done means the agreed CLI behavior and help or documentation changes are covered by appropriate tests.