Commands run

run: inject + run

run injects profiler code and launches the app in one step, always in --profile mode. It connects to the Dart VM Service and saves profiler events to JSONL as the app runs.

Usage

# Minimal: inject + flutter run --profile
spm run --jsonl results.jsonl

# Specify repo root and output file
spm run -j results.jsonl -r ./my-app -o profiler.jsonl

# Custom flutter subcommand (everything after --flutter is forwarded)
spm run -j results.jsonl --flutter drive \
         --driver=test_driver/integration_driver.dart \
         --target=integration_test/integration_test.dart

# Run on a specific device
spm run -j results.jsonl -r ./my-app --flutter run -d <device-id>

# Skip injection when the project is already instrumented
spm run --no-inject --flutter run

Options and flags

Flag / Option	Short	Description
--jsonl <path>	-j	JSONL manifest from analyze. Required unless --no-inject is set.
--repo <path>	-r	Flutter project root (defaults to ., the current directory).
--output <path>	-o	Output JSONL for profiler data (defaults to spm/profiler_<timestamp>.jsonl).
--no-inject		Skip the inject/revert steps; assumes the project is already instrumented.
--verbose	-v	Print progress to stdout.
--flutter [args…]		Separator. Everything after it is forwarded to the Flutter CLI.

There is no --mode flag. run always launches in --profile, so it collects performance_metric events. To collect dataflow-metric events instead, inject the project and launch it yourself in --debug (see Output Formats).

The forwarded Flutter command is assembled as <subcommand> --profile <extra-args>; with no --flutter block it defaults to run --profile.

What happens at runtime

1. SPM runs flutter analyze (on lib), injects the profiler code, then launches flutter <subcommand> --profile [extra-args] in the repo directory.
2. It scans stdout for the Dart VM Service URI (e.g. http://127.0.0.1:8181/…).
3. It connects over WebSocket and subscribes to the ext.spm.profiler extension stream.
4. Each profiler event emitted by SpmProfiler in the running app is written as a JSONL record.
5. On app exit, SPM reports the total event count, reverts the injection (unless --no-inject), and closes.

If the VM Service can't be reached, SPM logs that no profiler data will be captured and still runs the app.

Output

Output Formats defines the performance_metric event schema. run always runs in --profile, so this is what it produces.

Related

• inject is the transformation step run performs before launching.
• analyze produces the --jsonl manifest run requires (unless --no-inject).