Process mode

Author: benoit-cty

codecarbon/cli/main.py

@@ -347,36 +347,43 @@ def config():
 )
 def run(
     ctx: typer.Context,
+    log_level: Annotated[
+        str, typer.Option(help="Log level (critical, error, warning, info, debug)")
+    ] = "error",
 ):
     """
     Run a command and track its carbon emissions.
 
-    This command wraps any executable and measures the machine's total power
+    This command wraps any executable and measures the process's total power
     consumption during its execution. When the command completes, a summary
     report is displayed and emissions data is saved to a CSV file.
 
-    Note: This tracks machine-level emissions (entire system), not just the
-    specific command. For process-specific tracking, the command must be
-    instrumented with the CodeCarbon Python library.
+    Note: This tracks process-level emissions (only the specific command), not the
+    entire machine. For machine-level tracking, use the `monitor` command.
 
     Examples:
 
-        # Run any shell command
+        Do not use quotes around the command. Use -- to separate CodeCarbon args.
+
+        # Run any shell command:
         codecarbon run -- ./benchmark.sh
 
-        # Commands with arguments (use single quotes for special chars)
+        # Commands with arguments (use single quotes for special chars):
         codecarbon run -- python -c 'print("Hello World!")'
 
-        # Pipe the command output
+        # Pipe the command output:
         codecarbon run -- npm run test > output.txt
 
+        # Display the CodeCarbon detailed logs:
+        codecarbon run --log-level debug -- python --version
+
     The emissions data is appended to emissions.csv (default) in the current
     directory. The file path is shown in the final report.
     """
     # Suppress all CodeCarbon logs during execution
     from codecarbon.external.logger import set_logger_level
 
-    set_logger_level("critical")
+    set_logger_level(log_level)
 
     # Get the command from remaining args
     command = ctx.args
@@ -388,8 +395,10 @@ def run(
         )
         raise typer.Exit(1)
 
-    # Initialize tracker with minimal logging
-    tracker = EmissionsTracker(log_level="error", save_to_logger=False)
+    # Initialize tracker with specified logging level
+    tracker = EmissionsTracker(
+        log_level=log_level, save_to_logger=False, tracking_mode="process"
+    )
 
     print("🌱 CodeCarbon: Starting emissions tracking...")
     print(f"   Command: {' '.join(command)}")

docs/edit/usage.rst

@@ -58,7 +58,67 @@ The command line could also works without internet by providing the country code
 
     codecarbon monitor --offline --country-iso-code FRA
 
-Implementing CodeCarbon in your code allows you to track the emissions of a specific block of code.
+
+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 -- <your_command>
+
+Do not surround ``<your_command>`` with quotes. The double hyphen ``--`` indicates the end of CodeCarbon options and the beginning of the command to 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
+
+    # Display the CodeCarbon detailed logs
+    codecarbon run --log-level debug -- python --version
+
+**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 process-level emissions (only the specific command), not the
+    entire machine. For machine-level tracking, use the ``codecarbon monitor`` command.
+
+For more fine-grained tracking, implementing CodeCarbon in your code allows you to track the emissions of a specific block of code.
 
 Explicit Object
 ~~~~~~~~~~~~~~~