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

@@ -52,10 +52,16 @@ pub struct Args {
     ///
     /// 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"
     ///
+    /// 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.
+    ///
     #[arg(required = true)]
     pub specs: Vec<String>,
 
@@ -87,7 +93,7 @@ pub struct Args {
     #[arg(long, short)]
     pub platform: Vec<Platform>,
 
-    /// The feature for which the dependency should be added
+    /// The feature for which the dependency should be added.
     #[arg(long, short)]
     pub feature: Option<String>,
 

src/cli/remove.rs

@@ -14,6 +14,11 @@ use crate::project::manifest::FeatureName;
 use crate::{consts, project::SpecType, Project};
 
 /// Remove the dependency 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 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)
+///
 #[derive(Debug, Default, Parser)]
 pub struct Args {
     /// List of dependencies you wish to remove from the project