CLI Reference

Dolphin installs two console commands:

• dolphin: project scaffolding, diagnostics, inspection, recording, trace utilities, and backend information.
• dolphin-run: run another command on a hidden Windows desktop.

dolphin

dolphin [-h] COMMAND ...

Commands:

Command	Purpose
init	Bootstrap a new Dolphin test project
doctor	Check Python, dependencies, UIA access, and environment variables
spy	Inspect a window UI tree or pick an element interactively
record	Record mouse and keyboard interactions into a Python test
trace list	List recent Dolphin trace runs
trace view	Generate and open a trace HTML viewer
selfheal-stats	Show fallback selector usage
info backends	List registered automation backends

dolphin init

dolphin init [NAME] [--template {minimal,standard,enterprise}] [--yes] [--install] [--git]

Option	Description
NAME	Project directory to create. If omitted, Dolphin prompts for a name.
--template {minimal,standard,enterprise}	Choose the scaffold template.
--yes, -y	Non-interactive defaults: my-dolphin-tests and standard.
--install	Run pip install for scaffold dependencies after creation.
--git	Run git init in the new project directory.

Examples:

dolphin init my-tests
dolphin init my-tests --yes
dolphin init my-tests --template enterprise --yes --install --git

dolphin doctor

dolphin doctor

Prints:

• Dolphin and Python versions.
• Windows platform information.
• Required and optional dependency status.
• UIA access status.
• DOLPHIN_* environment variables used by runtime configuration.

dolphin spy

dolphin spy [--window TITLE] [--exact TITLE] [--class CLASS] [--pid PID]
            [--depth N] [--json] [--pick] [--image-pick] [--output-dir DIR]
            [--backend {uia,win32}]

Examples:

dolphin spy --window "Notepad" --depth 3
dolphin spy --window "Notepad" --json
dolphin spy --pick
dolphin spy --image-pick --output-dir templates

Use --pick to select an element interactively. Use --image-pick to capture a template PNG for image fallback.

dolphin record

dolphin record --output FILE [--app TITLE] [--backend {uia,win32}] [--func-name NAME]

Examples:

dolphin record --output tests/test_recorded.py
dolphin record --output tests/test_login.py --app "Login" --func-name test_login_workflow

The recorder prints a generated pytest function. Press Ctrl+F12 to stop recording.

dolphin trace list

dolphin trace list
dolphin trace list --last 50
dolphin trace list --dir dolphin-traces

Options:

Option	Default	Description
--last N	20	Number of recent runs to show
--dir PATH	dolphin-traces	Trace directory

dolphin trace view

dolphin trace view --last
dolphin trace view RUN_ID
dolphin trace view --last --dir dolphin-traces

trace view generates an HTML viewer for a trace run and opens it with the default browser.

dolphin selfheal-stats

dolphin selfheal-stats
dolphin selfheal-stats --last 20
dolphin selfheal-stats --file .dolphin-selfheal.jsonl

Options:

Option	Default	Description
--last N	10	Number of recent events
--file PATH	.dolphin-selfheal.jsonl	Telemetry log to read

dolphin info backends

dolphin info backends

Lists registered backend IDs, platforms, availability, source, and description.

dolphin-run

dolphin-run <command> [args...]

Examples:

dolphin-run pytest tests/
dolphin-run pytest tests/ -k test_notepad --dolphin-backend=uia

dolphin-run creates a hidden Windows desktop named DolphinHidden, sets DOLPHIN_HEADLESS=1 for the child process, runs the command there, waits for it to finish, and returns the child exit code.