Basic conan run docs

reference/commands.rst

@@ -30,6 +30,7 @@ and these :ref:`custom command examples <examples_extensions_custom_commands>`
    commands/search
    commands/version
    commands/workspace
+   commands/run
 
 - :doc:`conan cache <commands/cache>`: Return the path of recipes and packages in the cache
 - :doc:`conan config <commands/config>`: Manage Conan configuration (remotes, settings, plugins, etc)
@@ -45,6 +46,7 @@ and these :ref:`custom command examples <examples_extensions_custom_commands>`
 - :doc:`conan search <commands/search>`: Search packages matching a name
 - :doc:`conan version <commands/version>`: Give information about the Conan client version
 - :doc:`conan workspace (incubating) <commands/workspace>`: Manage Conan workspaces
+- :doc:`conan run <commands/run>`: Execute binaries with automatic environment activation
 
 
 **Creator commands:**

reference/commands/run.rst

@@ -0,0 +1,31 @@
+.. _reference_commands_run:
+
+conan run
+=========
+
+.. include:: ../../common/experimental_warning.inc
+
+.. autocommand::
+    :command: conan run -h
+
+
+The ``conan run`` command lets you directly execute a binary from a Conan package, automatically resolving and installing
+all its dependencies. There’s no need to manually activate any environments generated by Conan: just pass the executable
+to run, and Conan will activate the necessary environments and execute it.
+
+The command can receive either a ``conanfile.py``/``conanfile.txt`` or have the requirements specified directly from the CLI via ``--requires`` and ``--tool-requires`` arguments.
+
+For example, if we call a specific version of ``openssl`` we would:
+
+.. code-block:: bash
+
+    $ conan run "openssl --version" --tool-requires=openssl/3.5.4
+
+    Installing and building dependencies, this might take a while...
+    OpenSSL 3.5.4 30 Sep 2025 (Library: OpenSSL 3.5.4 30 Sep 2025)
+
+This command is useful when you want to execute some specific binary from any package.
+
+.. note::
+    This command activates both the ``host`` and ``build`` contexts, so that both contexts binaries are made available at once.
+    In case that a package exists in both contexts, the ``host`` context binaries take precedence.