diff --git a/docs/edit/usage.rst b/docs/edit/usage.rst index 169fa3d7d..80805bf36 100644 --- a/docs/edit/usage.rst +++ b/docs/edit/usage.rst @@ -58,6 +58,61 @@ The command line could also works without internet by providing the country code codecarbon monitor --offline --country-iso-code FRA +Running Any Command with CodeCarbon +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to track emissions while running any command or program (not just Python scripts), you can use the ``codecarbon run`` command. +This allows non-Python users to measure machine emissions during the execution of any command: + +.. code-block:: console + + codecarbon run -- + +**Examples:** + +.. code-block:: console + + # Run a shell script + codecarbon run -- ./benchmark.sh + + # Run a command with arguments (use quotes for special characters) + codecarbon run -- bash -c 'echo "Processing..."; sleep 30; echo "Done!"' + + # Run Python scripts + codecarbon run -- python train_model.py + + # Run Node.js applications + codecarbon run -- node app.js + + # Run tests with output redirection + codecarbon run -- npm run test > output.txt + +**Output:** + +When the command completes, CodeCarbon displays a summary report and saves the emissions data to a CSV file: + +.. code-block:: console + + 🌱 CodeCarbon: Starting emissions tracking... + Command: bash -c echo "Processing..."; sleep 30; echo "Done!" + + Processing... + Done! + + ============================================================ + 🌱 CodeCarbon Emissions Report + ============================================================ + Command: bash -c echo "Processing..."; sleep 30; echo "Done!" + Emissions: 0.0317 g CO2eq + Saved to: /home/user/emissions.csv + ⚠️ Note: Measured entire machine (includes all system processes) + ============================================================ + +.. note:: + The ``codecarbon run`` command tracks **machine-level emissions** (entire system), not just the specific command. + This means it measures the total power consumption of your computer while the command is running, including all background processes. + For process-specific tracking, instrument your code with the CodeCarbon Python library. + Implementing CodeCarbon in your code allows you to track the emissions of a specific block of code. Explicit Object