Overhauled CLI. (#963)

* Overhauled CLI.

* Avoid profiling by system libraries by default.

* Linter clean.

* Updated CLI syntax.

* Updated CLI syntax.

* Updated.

* Updated major version.

Author: emeryberger

.github/workflows/test-smoketests.yml

@@ -47,7 +47,7 @@ jobs:
 
       # Note: test/smoketest.py only handles single JSON, rather than multiple in sequence.
     - name: profile-interval smoke test
-      run: python -m scalene --cli --profile-interval=2 test/testme.py
+      run: python -m scalene run --profile-interval=2 test/testme.py && python -m scalene view --cli
 
     - name: decorator smoke test
       run: python test/smoketest_profile_decorator.py
@@ -70,4 +70,4 @@ jobs:
     - name: -m invocation smoketest
       run: |
         python -m pip install git+https://github.com/sternj/import_stress_test
-        python -m scalene --cli --- -m import_stress_test
+        python -m scalene run --- -m import_stress_test && python -m scalene view --cli

CLAUDE.md

@@ -256,6 +256,83 @@ Key runtime dependencies:
 
 See `requirements.txt` for full list.
 
+## CLI Structure
+
+Scalene uses a verb-based CLI with two main subcommands:
+
+```bash
+# Profile a program (saves to scalene-profile.json by default)
+scalene run [options] yourprogram.py
+
+# View an existing profile
+scalene view [options] [profile.json]
+```
+
+### Run Subcommand Options
+
+```bash
+scalene run prog.py                      # profile, save to scalene-profile.json
+scalene run -o my.json prog.py           # save to custom file
+scalene run --cpu-only prog.py           # profile CPU only (faster)
+scalene run -c config.yaml prog.py       # load options from config file
+scalene run prog.py --- --arg            # pass args to program
+```
+
+### View Subcommand Options
+
+```bash
+scalene view                             # open in browser
+scalene view --cli                       # view in terminal
+scalene view --html                      # save to scalene-profile.html
+scalene view myprofile.json              # open specific profile
+```
+
+### YAML Configuration
+
+Create a `scalene.yaml` file with options:
+
+```yaml
+outfile: my-profile.json
+cpu-only: true
+profile-only: "mypackage,utils"
+cpu-percent-threshold: 5
+```
+
+Load with: `scalene run -c scalene.yaml prog.py`
+
+### Advanced Options
+
+Use `scalene run --help-advanced` to see all options including:
+- `--profile-all` - profile all code, not just the target program
+- `--profile-only PATH` - only profile files containing these strings
+- `--profile-exclude PATH` - exclude files containing these strings
+- `--profile-system-libraries` - profile Python stdlib and installed packages (skipped by default)
+- `--gpu` - profile GPU time and memory
+- `--memory` - profile memory usage
+- `--stacks` - collect stack traces
+- `--profile-interval N` - output profiles every N seconds
+
+### Smoke Tests
+
+Smoke tests in `test/` use the new CLI syntax:
+
+```python
+# test/smoketest.py
+cmd = [sys.executable, "-m", "scalene", "run", "-o", str(outfile), *rest, fname]
+```
+
+### GitHub Workflows
+
+Workflows in `.github/workflows/` use the new CLI:
+
+```yaml
+# Profile with interval, then view
+- run: python -m scalene run --profile-interval=2 test/testme.py && python -m scalene view --cli
+
+# Profile with module invocation
+- run: python -m scalene run --- -m import_stress_test && python -m scalene view --cli
+```
+
 ## Profiling Guide
 
 See [Scalene-Agents.md](Scalene-Agents.md) for detailed information about interpreting Scalene's profiling output, including Python vs C time, memory metrics, and optimization strategies.

README.md

@@ -80,23 +80,75 @@ First, install <a href="https://marketplace.visualstudio.com/items?itemName=Emer
 Commonly used command-line options:
 </summary>
 
+Scalene uses a verb-based command structure with two main commands: `run` (to profile) and `view` (to display results).
+
+```console
+# Profile a program (saves to scalene-profile.json)
+scalene run your_prog.py
+python3 -m scalene run your_prog.py              # equivalent alternative
+
+# View a profile
+scalene view                                     # open profile in browser
+scalene view --cli                               # view in terminal
+scalene view --html                              # save to scalene-profile.html
+
+# Common profiling options
+scalene run --cpu-only your_prog.py              # only profile CPU (faster)
+scalene run -o results.json your_prog.py         # custom output filename
+scalene run -c config.yaml your_prog.py          # load options from config file
+
+# Pass arguments to your program (use --- separator)
+scalene run your_prog.py --- --arg1 --arg2
+
+# Get help
+scalene --help                                   # main help
+scalene run --help                               # profiling options
+scalene run --help-advanced                      # advanced profiling options
+scalene view --help                              # viewing options
+```
+
+</details>
+
+<details>
+<summary>
+Using a YAML configuration file:
+</summary>
+
+You can store Scalene options in a YAML configuration file and load them with `-c` or `--config`:
+
 ```console
-scalene your_prog.py                             # full profile (outputs to web interface)
-python3 -m scalene your_prog.py                  # equivalent alternative
+scalene run -c scalene.yaml your_prog.py
+```
+
+Example `scalene.yaml`:
+
+```yaml
+# Output options
+outfile: my-profile.json
 
-scalene --cli your_prog.py                       # use the command-line only (no web interface)
+# Profiling mode (use only one)
+cpu-only: true              # CPU profiling only (faster)
+# gpu: true                 # Include GPU profiling
+# memory: true              # Include memory profiling
 
-scalene --cpu your_prog.py                       # only profile CPU
-scalene --cpu --gpu your_prog.py                 # only profile CPU and GPU
-scalene --cpu --gpu --memory your_prog.py        # profile everything (same as no options)
+# Filter what gets profiled
+profile-only: "mypackage,mymodule"    # Only profile these paths
+profile-exclude: "tests,venv"          # Exclude these paths
+profile-all: false                     # Profile all code, not just target
 
-scalene --reduced-profile your_prog.py           # only profile lines with significant usage
-scalene --profile-interval 5.0 your_prog.py      # output a new profile every five seconds
+# Performance tuning
+cpu-percent-threshold: 1     # Min CPU% to report (default: 1)
+cpu-sampling-rate: 0.01      # Sampling interval in seconds
+malloc-threshold: 100        # Min allocations to report
 
-scalene (Scalene options) --- your_prog.py (...) # use --- to tell Scalene to ignore options after that point
-scalene --help                                   # lists all options
+# Other options
+use-virtual-time: false      # Measure CPU time only (not I/O)
+stacks: false                # Collect stack traces
+memory-leak-detector: true   # Detect likely memory leaks
 ```
 
+Command-line arguments override config file settings.
+
 </details>
 
 <details>
@@ -259,57 +311,86 @@ scalene test/testme.py
  </summary>
 
 ```console
-    % scalene --help
-     usage: scalene [-h] [--outfile OUTFILE] [--html] [--reduced-profile]
-                    [--profile-interval PROFILE_INTERVAL] [--cpu-only]
-                    [--profile-all] [--profile-only PROFILE_ONLY]
-                    [--use-virtual-time]
-                    [--cpu-percent-threshold CPU_PERCENT_THRESHOLD]
-                    [--cpu-sampling-rate CPU_SAMPLING_RATE]
-                    [--malloc-threshold MALLOC_THRESHOLD]
-     
-     Scalene: a high-precision CPU and memory profiler.
-     https://github.com/plasma-umass/scalene
-     
-     command-line:
-        % scalene [options] yourprogram.py
-     or
-        % python3 -m scalene [options] yourprogram.py
-     
-     in Jupyter, line mode:
-        %scrun [options] statement
-     
-     in Jupyter, cell mode:
-        %%scalene [options]
-        code...
-        code...
-     
-     optional arguments:
-       -h, --help            show this help message and exit
-       --outfile OUTFILE     file to hold profiler output (default: stdout)
-       --html                output as HTML (default: text)
-       --reduced-profile     generate a reduced profile, with non-zero lines only (default: False)
-       --profile-interval PROFILE_INTERVAL
-                             output profiles every so many seconds (default: inf)
-       --cpu-only            only profile CPU time (default: profile CPU, memory, and copying)
-       --profile-all         profile all executed code, not just the target program (default: only the target program)
-       --profile-only PROFILE_ONLY
-                             profile only code in filenames that contain the given strings, separated by commas (default: no restrictions)
-       --use-virtual-time    measure only CPU time, not time spent in I/O or blocking (default: False)
-       --cpu-percent-threshold CPU_PERCENT_THRESHOLD
-                             only report profiles with at least this percent of CPU time (default: 1%)
-       --cpu-sampling-rate CPU_SAMPLING_RATE
-                             CPU sampling rate (default: every 0.01s)
-       --malloc-threshold MALLOC_THRESHOLD
-                             only report profiles with at least this many allocations (default: 100)
-     
-     When running Scalene in the background, you can suspend/resume profiling
-     for the process ID that Scalene reports. For example:
-     
-        % python3 -m scalene [options] yourprogram.py &
-      Scalene now profiling process 12345
-        to suspend profiling: python3 -m scalene.profile --off --pid 12345
-        to resume profiling:  python3 -m scalene.profile --on  --pid 12345
+% scalene --help
+Scalene: a high-precision CPU and memory profiler, version 1.5.51 (2025.01.29)
+https://github.com/plasma-umass/scalene
+
+commands:
+  run     Profile a Python program (saves to scalene-profile.json)
+  view    View an existing profile in browser or terminal
+
+examples:
+  % scalene run your_program.py              # profile, save to scalene-profile.json
+  % scalene view                             # view scalene-profile.json in browser
+  % scalene view --cli                       # view profile in terminal
+
+in Jupyter, line mode:
+  %scrun [options] statement
+
+in Jupyter, cell mode:
+  %%scalene [options]
+   your code here
+
+% scalene run --help
+Profile a Python program with Scalene.
+
+examples:
+  % scalene run prog.py                 # profile, save to scalene-profile.json
+  % scalene run -o my.json prog.py      # save to custom file
+  % scalene run --cpu-only prog.py      # profile CPU only (faster)
+  % scalene run -c scalene.yaml prog.py # load options from config file
+  % scalene run prog.py --- --arg       # pass args to program
+  % scalene run --help-advanced         # show advanced options
+
+options:
+  -h, --help            show this help message and exit
+  -o, --outfile OUTFILE output file (default: scalene-profile.json)
+  --cpu-only            only profile CPU time (no memory/GPU)
+  -c, --config FILE     load options from YAML config file
+  --help-advanced       show advanced options
+
+% scalene run --help-advanced
+Advanced options for scalene run:
+
+background profiling:
+  Use --off to start with profiling disabled, then control it from another terminal:
+    % scalene run --off prog.py          # start with profiling off
+    % python3 -m scalene.profile --on  --pid <PID>   # resume profiling
+    % python3 -m scalene.profile --off --pid <PID>   # suspend profiling
+
+options:
+  --profile-all         profile all code, not just the target program
+  --profile-only PATH   only profile files containing these strings (comma-separated)
+  --profile-exclude PATH exclude files containing these strings (comma-separated)
+  --profile-system-libraries  profile Python stdlib and installed packages (default: skip)
+  --gpu                 profile GPU time and memory
+  --memory              profile memory usage
+  --stacks              collect stack traces
+  --profile-interval N  output profiles every N seconds (default: inf)
+  --use-virtual-time    measure only CPU time, not I/O or blocking
+  --cpu-percent-threshold N  only report lines with at least N% CPU (default: 1%)
+  --cpu-sampling-rate N CPU sampling rate in seconds (default: 0.01)
+  --allocation-sampling-window N  allocation sampling window in bytes
+  --malloc-threshold N  only report lines with at least N allocations (default: 100)
+  --program-path PATH   directory containing code to profile
+  --memory-leak-detector  EXPERIMENTAL: report likely memory leaks
+  --on                  start with profiling on (default)
+  --off                 start with profiling off
+
+% scalene view --help
+View an existing Scalene profile.
+
+examples:
+  % scalene view                    # open in browser
+  % scalene view --cli              # view in terminal
+  % scalene view --html             # save to scalene-profile.html
+  % scalene view myprofile.json     # open specific profile in browser
+
+options:
+  -h, --help     show this help message and exit
+  --cli          display profile in the terminal
+  --html         save to scalene-profile.html (no browser)
+  -r, --reduced  only show lines with activity (--cli mode)
 ```
 </details>
 
@@ -410,7 +491,11 @@ Can I use Scalene with PyTest?
 
 **A:** Yes! You can run it as follows (for example):
 
-`python3 -m scalene --- -m pytest your_test.py` 
+`scalene run -m pytest your_test.py`
+
+or
+
+`python3 -m scalene run -m pytest your_test.py` 
 
 </details>
 
@@ -424,15 +509,15 @@ Is there any way to get shorter profiles or do more targeted profiling?
 1. Use `--reduced-profile` to include only lines and files with memory/CPU/GPU activity.
 2. Use `--profile-only` to include only filenames containing specific strings (as in, `--profile-only foo,bar,baz`).
 3. Decorate functions of interest with `@profile` to have Scalene report _only_ those functions.
-4. Turn profiling on and off programmatically by importing Scalene profiler (`from scalene import scalene_profiler`) and then turning profiling on and off via `scalene_profiler.start()` and `scalene_profiler.stop()`. By default, Scalene runs with profiling on, so to delay profiling until desired, use the `--off` command-line option (`python3 -m scalene --off yourprogram.py`).
+4. Turn profiling on and off programmatically by importing Scalene profiler (`from scalene import scalene_profiler`) and then turning profiling on and off via `scalene_profiler.start()` and `scalene_profiler.stop()`. By default, Scalene runs with profiling on, so to delay profiling until desired, use the `--off` command-line option (`scalene run --off yourprogram.py`).
 </details>
 
 <details>
 <summary>
 How do I run Scalene in PyCharm?
 </summary>
 
-**A:**  In PyCharm, you can run Scalene at the command line by opening the terminal at the bottom of the IDE and running a Scalene command (e.g., `python -m scalene <your program>`). Use the options `--cli`, `--html`, and `--outfile <your output.html>` to generate an HTML file that you can then view in the IDE.
+**A:**  In PyCharm, you can run Scalene at the command line by opening the terminal at the bottom of the IDE and running a Scalene command (e.g., `scalene run <your program>`). Then use `scalene view --html` to generate an HTML file (`scalene-profile.html`) that you can view in the IDE.
 </details>
 
 <details>