docs: update some of the cli and add osx rosetta mention (#1760)

docs/reference/cli.md

@@ -56,14 +56,15 @@ It will only add if the package with its version constraint is able to work with
 [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.
+1. `[SPECS]`: The package(s) to add, space separated. The version constraint is optional.
 
 ##### Options
 
@@ -77,24 +78,48 @@ These dependencies will be read by pixi as if they had been added to the pixi `p
 - `--no-lockfile-update`: Don't update the lock-file, implies the `--no-install` flag.
 - `--platform <PLATFORM> (-p)`: The platform for which the dependency should be added. (Allowed to be used more than once)
 - `--feature <FEATURE> (-f)`: The feature for which the dependency should be added.
+- `--editable`: Specifies an editable dependency, only use in combination with `--pypi`.
 
 ```shell
-pixi add numpy
-pixi add numpy pandas "pytorch>=1.8"
-pixi add "numpy>=1.22,<1.24"
-pixi add --manifest-path ~/myproject/pixi.toml numpy
-pixi add --host "python>=3.9.0"
-pixi add --build cmake
-pixi add --pypi requests[security]
-pixi add --pypi "boltons @ https://files.pythonhosted.org/packages/46/35/e50d4a115f93e2a3fbf52438435bb2efcf14c11d4fcd6bdcd77a6fc399c9/boltons-24.0.0-py3-none-any.whl"
-pixi add --pypi "exchangelib @ git+https://github.com/ecederstrand/exchangelib"
-pixi add --pypi "project @ file:///absolute/path/to/project"
-pixi add --platform osx-64 --build clang
-pixi add --no-install numpy
-pixi add --no-lockfile-update numpy
-pixi add --feature featurex numpy
+pixi add numpy # (1)!
+pixi add numpy pandas "pytorch>=1.8" # (2)!
+pixi add "numpy>=1.22,<1.24" # (3)!
+pixi add --manifest-path ~/myproject/pixi.toml numpy # (4)!
+pixi add --host "python>=3.9.0" # (5)!
+pixi add --build cmake # (6)!
+pixi add --platform osx-64 clang # (7)!
+pixi add --no-install numpy # (8)!
+pixi add --no-lockfile-update numpy # (9)!
+pixi add --feature featurex numpy # (10)!
+
+# Add a pypi dependency
+pixi add --pypi requests[security] # (11)!
+pixi add --pypi Django==5.1rc1 # (12)!
+pixi add --pypi "boltons>=24.0.0" --feature lint # (13)!
+pixi add --pypi "boltons @ https://files.pythonhosted.org/packages/46/35/e50d4a115f93e2a3fbf52438435bb2efcf14c11d4fcd6bdcd77a6fc399c9/boltons-24.0.0-py3-none-any.whl" # (14)!
+pixi add --pypi "exchangelib @ git+https://github.com/ecederstrand/exchangelib" # (15)!
+pixi add --pypi "project @ file:///absolute/path/to/project" # (16)!
+pixi add --pypi "project @ file:///absolute/path/to/project" --editable # (17)!
 ```
 
+1. This will add the `numpy` package to the project with the latest available for the solved environment.
+2. This will add multiple packages to the project solving them all together.
+3. This will add the `numpy` package with the version constraint.
+4. This will add the `numpy` package to the project of the manifest file at the given path.
+5. This will add the `python` package as a host dependency. There is currently no different behavior for host dependencies.
+6. This will add the `cmake` package as a build dependency. There is currently no different behavior for build dependencies.
+7. This will add the `clang` package only for the `osx-64` platform.
+8. This will add the `numpy` package to the manifest and lockfile, without installing it in an environment.
+9. This will add the `numpy` package to the manifest without updating the lockfile or installing it in the environment.
+10. This will add the `numpy` package in the feature `featurex`.
+11. This will add the `requests` package as `pypi` dependency with the `security` extra.
+12. This will add the `pre-release` version of `Django` to the project as a `pypi` dependency.
+13. This will add the `boltons` package in the feature `lint` as `pypi` dependency.
+14. This will add the `boltons` package with the given `url` as `pypi` dependency.
+15. This will add the `exchangelib` package with the given `git` url as `pypi` dependency.
+16. This will add the `project` package with the given `file` url as `pypi` dependency.
+17. This will add the `project` package with the given `file` url as an `editable` package as `pypi` dependency.
+
 !!! tip
     If you want to use a non default pinning strategy, you can set it using [pixi's configuration](./pixi_configuration.md#pinning-strategy).
     ```
@@ -281,6 +306,7 @@ If the project manifest is a `pyproject.toml`, removing a pypi dependency with t
 - `--platform <PLATFORM> (-p)`: The platform from which the dependency should be removed.
 - `--feature <FEATURE> (-f)`: The feature from which the dependency should be removed.
 - `--no-install`: Don't install the environment, only remove the package from the lock-file and manifest.
+- `--no-lockfile-update`: Don't update the lock-file, implies the `--no-install` flag.
 
 ```shell
 pixi remove numpy
@@ -907,6 +933,7 @@ This command installs package(s) into its own environment and adds the binary to
 ##### Options
 
 - `--channel <CHANNEL> (-c)`: specify a channel that the project uses. Defaults to `conda-forge`. (Allowed to be used more than once)
+- `--platform <PLATFORM> (-p)`: specify a platform that you want to install the package for. (default: current platform)
 
 ```shell
 pixi global install ruff
@@ -922,8 +949,17 @@ pixi global install python=3.9.*
 pixi global install "python [version='3.11.0', build_number=1]"
 pixi global install "python [version='3.11.0', build=he550d4f_1_cpython]"
 pixi global install python=3.11.0=h10a6764_1_cpython
+
+# Install for a specific platform, only useful on osx-arm64
+pixi global install --platform osx-64 ruff
 ```
 
+!!! tip
+    Running `osx-64` on Apple Silicon will install the Intel binary but run it using [Rosetta](https://developer.apple.com/documentation/apple-silicon/about-the-rosetta-translation-environment)
+    ```
+    pixi global install --platform osx-64 ruff
+    ```
+
 After using global install, you can use the package you installed anywhere on your system.
 
 ### `global list`
@@ -960,6 +996,7 @@ This command upgrades a globally installed package (to the latest version by def
 - `--channel <CHANNEL> (-c)`: specify a channel that the project uses.
   Defaults to `conda-forge`. Note the channel the package was installed from
   will be always used for upgrade. (Allowed to be used more than once)
+- `--platform <PLATFORM> (-p)`: specify a platform that you want to upgrade the package for. (default: current platform)
 
 ```shell
 pixi global upgrade ruff

docs/reference/project_configuration.md

@@ -66,6 +66,12 @@ platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]
 
 The available platforms are listed here: [link](https://docs.rs/rattler_conda_types/latest/rattler_conda_types/enum.Platform.html)
 
+!!! tip "Special MacOS behavior"
+    MacOS has two platforms: `osx-64` for Intel Macs and `osx-arm64` for Apple Silicon Macs.
+    To support both, include both in your platforms list.
+    Fallback: If `osx-arm64` can't resolve, use `osx-64`.
+    Running `osx-64` on Apple Silicon uses [Rosetta](https://developer.apple.com/documentation/apple-silicon/about-the-rosetta-translation-environment) for Intel binaries.
+
 ### `version` (optional)
 
 The version of the project.
@@ -648,7 +654,7 @@ This will create an environment called `test` that has `pytest` installed.
 The `feature` table allows you to define the following fields per feature.
 
 - `dependencies`: Same as the [dependencies](#dependencies).
-- `pypi-dependencies`: Same as the [pypi-dependencies](#pypi-dependencies-beta-feature).
+- `pypi-dependencies`: Same as the [pypi-dependencies](#pypi-dependencies).
 - `pypi-options`: Same as the [pypi-options](#the-pypi-options-table).
 - `system-requirements`: Same as the [system-requirements](#the-system-requirements-table).
 - `activation`: Same as the [activation](#the-activation-table).