diff --git a/reference/commands.rst b/reference/commands.rst index 70e74ca7c92..24e8aac7c6e 100644 --- a/reference/commands.rst +++ b/reference/commands.rst @@ -30,6 +30,7 @@ and these :ref:`custom command examples ` commands/search commands/version commands/workspace + commands/run - :doc:`conan cache `: Return the path of recipes and packages in the cache - :doc:`conan config `: Manage Conan configuration (remotes, settings, plugins, etc) @@ -45,6 +46,7 @@ and these :ref:`custom command examples ` - :doc:`conan search `: Search packages matching a name - :doc:`conan version `: Give information about the Conan client version - :doc:`conan workspace (incubating) `: Manage Conan workspaces +- :doc:`conan run `: Execute binaries with automatic environment activation **Creator commands:** diff --git a/reference/commands/run.rst b/reference/commands/run.rst new file mode 100644 index 00000000000..44c94807809 --- /dev/null +++ b/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.