docs: Document the add & remove cli behaviour with pyproject.toml manifest

docs/reference/cli.md

@@ -53,6 +53,12 @@ Adds dependencies to the [manifest file](configuration.md).
 It will only add if the package with its version constraint is able to work with rest of the dependencies in the project.
 [More info](../features/multi_platform_configuration.md) on multi-platform configuration.
 
+If the project manifest is a `pyproject.toml`, adding a pypi dependency will add it to the native pyproject `project.dependencies` array, or to the native `project.optional-dependencies` table if a feature is specified:
+- `pixi add --pypi boto3` would add `boto3` to the `project.dependencies` array
+- `pixi add --pypi boto3 --feature aws` would add `boto3` to the `project.dependencies.aws` array
+
+These dependencies will be read by pixi as if they had been added to the pixi `pypi-dependencies` tables of the default or a named feature.
+
 ##### Arguments
 
 1. `<SPECS>`: The package(s) to add, space separated. The version constraint is optional.
@@ -181,6 +187,10 @@ pixi run --environment cuda python
 
 Removes dependencies from the [manifest file](configuration.md).
 
+If the project manifest is a `pyproject.toml`, removing a pypi dependency with the `--pypi` flag will remove it from either
+- the native pyproject `project.dependencies` array or the native `project.optional-dependencies` table (if a feature is specified)
+- pixi `pypi-dependencies` tables of the default or a named feature (if a feature is specified)
+
 ##### Arguments
 
 1. `<DEPS>...`: List of dependencies you wish to remove from the project.

src/cli/add.rs

@@ -22,7 +22,7 @@ use std::{
     path::PathBuf,
 };
 
-/// Adds a dependency to the project
+/// Adds dependencies to the project
 #[derive(Parser, Debug, Default)]
 #[clap(arg_required_else_help = true)]
 pub struct Args {
@@ -36,27 +36,29 @@ pub struct Args {
     ///
     /// - `pixi add python=3.9`: This will select the latest minor version that complies with 3.9.*, i.e.,
     ///   python version 3.9.0, 3.9.1, 3.9.2, etc.
-    ///
     /// - `pixi add python`: In absence of a specified version, the latest version will be chosen.
     ///   For instance, this could resolve to python version 3.11.3.* at the time of writing.
     ///
     /// Adding multiple dependencies at once is also supported:
-    ///
     /// - `pixi add python pytest`: This will add both `python` and `pytest` to the project's dependencies.
     ///
     /// The `--platform` and `--build/--host` flags make the dependency target specific.
-    ///
     /// - `pixi add python --platform linux-64 --platform osx-arm64`: Will add the latest version of python for linux-64 and osx-arm64 platforms.
-    ///
     /// - `pixi add python --build`: Will add the latest version of python for as a build dependency.
     ///
     /// Mixing `--platform` and `--build`/`--host` flags is supported
     ///
-    /// The `--pypi` option will add the package as a pypi-dependency this can not be mixed with the conda dependencies
+    /// The `--pypi` option will add the package as a pypi dependency. This can not be mixed with the conda dependencies
     /// - `pixi add --pypi boto3`
     /// - `pixi add --pypi "boto3==version"
     ///
-    #[arg(required = true)]
+    /// If the project manifest is a `pyproject.toml`, adding a pypi dependency will add it to the native pyproject `project.dependencies` array
+    /// or to the native `project.optional-dependencies` table if a feature is specified:
+    /// - `pixi add --pypi boto3` will add `boto3` to the `project.dependencies` array
+    /// - `pixi add --pypi boto3 --feature aws` will add `boto3` to the `project.dependencies.aws` array
+    /// These dependencies will then be read by pixi as if they had been added to the pixi `pypi-dependencies` tables of the default or of a named feature.
+    ///
+    #[arg(required = true, verbatim_doc_comment)]
     pub specs: Vec<String>,
 
     /// The path to 'pixi.toml' or 'pyproject.toml'

src/cli/remove.rs

@@ -13,11 +13,17 @@ use crate::project::manifest::python::PyPiPackageName;
 use crate::project::manifest::FeatureName;
 use crate::{consts, project::SpecType, Project};
 
-/// Remove the dependency from the project
+/// Removes dependencies from the project
 #[derive(Debug, Default, Parser)]
+#[clap(arg_required_else_help = true)]
 pub struct Args {
-    /// List of dependencies you wish to remove from the project
-    #[arg(required = true)]
+    /// Specify the dependencies you wish to remove from the project.
+    ///
+    /// If the project manifest is a `pyproject.toml`, removing a pypi dependency with the `--pypi` flag will remove it from either
+    /// - the native pyproject `project.dependencies` array or, if a feature is specified, the native `project.optional-dependencies` table
+    /// - pixi `pypi-dependencies` tables of the default feature or, if a feature is specified, a named feature
+    ///
+    #[arg(required = true, verbatim_doc_comment)]
     pub deps: Vec<String>,
 
     /// The path to 'pixi.toml' or 'pyproject.toml'