Drive.NET CLI

Running The CLI

From source:

dotnet run --project src/DriveNet.Cli -- <command> [options]

From a published executable:

DriveNet.Cli.exe <command> [options]

Validated Integration Workflow

When you need high-confidence validation of CLI behavior against real desktop targets, use the repository's integration path instead of ad hoc manual checks.

dotnet build tests/DriveNet.TestApp.WinForms/DriveNet.TestApp.WinForms.csproj -c Release
dotnet build tests/DriveNet.TestApp.WinUI/DriveNet.TestApp.WinUI.csproj -c Release -p:Platform=x64
dotnet test tests/DriveNet.Tests.Integration/DriveNet.Tests.Integration.csproj -c Release -p:Platform=x64

• Build the desktop test apps first because the integration fixture launches their executables directly.
• Run the integration project in Release; its MCP client starts DriveNet.Server with dotnet run -c Release --no-build.
• The WinUI target should be built with -p:Platform=x64 to match the validated integration path.

Shared Conventions

• Process-targeting commands require exactly one of --process-name (-n) or --process-id (-p).
• Use pick when several matching processes exist and you want one exact PID before a later command attaches.
• Different VS Code or terminal controller processes can automate different target processes at the same time, but the same target process can only be attached by one Drive.NET controller at a time.
• Batch same-process work into one batch command whenever possible so the attach cost and 1-second warning toast happen only once.
• Use playback as the CLI replay entry point for recorded batch JSON, YAML suites, and YAML manifests.
• After the first user-visible warning has already been shown, continuation CLI commands can pass --continuation (alias: --no-session-start-warning) to skip the repeated warning for that command.
• Process-targeting commands also accept --session-start-warning-mode toast|persistent to choose the warning UI. The persistent mode keeps the bottom-right warning card visible for the lifetime of the command's session, and providing a mode also enables the warning unless --no-session-start-warning is present.
• In text mode, one-shot process-targeting commands print a reuse hint after attach so terminal users get nudged toward batch, playback, or --continuation.
• Process-targeting commands also accept --session-start-warning to force the warning back on for a specific command.
• Selector-based commands accept either flat selectors (--automation-id, --name, --control-type, --class-name) or a hierarchical --path; do not mix them in the same command.
• Use --match-index only when duplicate matches are expected and stable in order.
• find and wait_for support --explain for diagnostics-first selector debugging without spending time on a real action or wait.
• Add --json to any command for machine-readable output instead of terminal tables.
• inspect, interact, selector-based capture, and selector-resolved wait_for conditions require the selector to resolve to exactly one element.
• batch runs all steps inside one short-lived session so saved element IDs and ${name} variables remain valid across the whole command.
• Artifact-writing commands such as capture --output, report, and snapshot normalize output beneath the workspace-root .drive-net directory.
• Use the CLI for the failing step itself, but prefer MCP session workflows when you need durable post-crash inspection of a dead target process.

Commands

doctor

Check whether the current Windows session can access UI Automation.

DriveNet.Cli.exe doctor
DriveNet.Cli.exe doctor --json

Reports uiAutomationAccessible, OS description, process architecture, whether the session is interactive, and any recent persisted crash evidence for Drive.NET Helper or Drive.NET Companion. Use this first when diagnosing environment or privilege problems, or when Helper/Companion crashed on a previous run and you need the saved crash log, WER dump paths, or correlated Windows Application log entries.

discover

List running processes with visible windows.

DriveNet.Cli.exe discover
DriveNet.Cli.exe discover --dotnet-only
DriveNet.Cli.exe discover --filter WinForms --json
DriveNet.Cli.exe discover --filter SpectraWrite --include-windows --hierarchical --json

• Use --include-windows when you need exact HWNDs and titles before connecting, capturing, or comparing window inventories.
• Use --hierarchical when multi-process apps spawn helper processes or separate visible windows under one parent app.

pick

Resolve a deterministic process candidate and emit the exact --process-id suggestion for later commands.

DriveNet.Cli.exe pick --process-name DriveNet.TestApp.WinForms --newest --json
DriveNet.Cli.exe pick --process-name firefox --window-title-regex "Profile Manager" --index 1

Use pick before capture, interact, demo mouse-move, or any repeated manual CLI flow when a plain process-name match is ambiguous.

desktop

Query desktop-wide monitor layout, the current foreground window, and cross-process visible-window state without attaching to a process.

DriveNet.Cli.exe desktop --action monitors
DriveNet.Cli.exe desktop --action foregroundWindow --json
DriveNet.Cli.exe desktop --action topLevelWindows --json

Use desktop when the workflow needs monitor bounds, DPI scale, the current foreground window, or a cross-process snapshot of all visible top-level windows before targeting a specific application.

windows

List or manage visible windows for a target process.

DriveNet.Cli.exe windows -n DriveNet.TestApp.WinForms
DriveNet.Cli.exe windows -n DriveNet.TestApp.WinForms --action blockers --json
DriveNet.Cli.exe windows -n DriveNet.TestApp.WinForms --action dismissBlocker --button-name Continue --json
DriveNet.Cli.exe windows -p 12345 --json
DriveNet.Cli.exe windows -n DriveNet.TestApp.WinForms --action bringToFront --window-handle 0x2A

Output includes window handle, state, bounds, title, and in --json mode the same native-vs-UIA-vs-DWM-vs-app-metadata bounds provenance exposed by the MCP window list tool (boundsSource, boundsNote, nativeWindowRect, optional uiaBoundingRect, optional boundsDeltaFromNative, optional dwmExtendedFrameBounds, optional appMetadataBounds). On reused popup hosts, boundsSource can be uiaBoundingRect, dwmExtendedFrameBounds, or appMetadata when the native rect still exposes the hidden-popup origin sentinel rather than the anchored popup position. When suspectReusedPopup is true and appMetadataBounds is absent, inspect app-emitted helpText or itemStatus directly for authoritative popup geometry. For --action blockers, the command returns a focused blocking-window assessment and exits with code 1 when a blocking window is present.

For popup-hosted drags, diff windows --json before and after mouseUp. If the same popup host moved while held but comes back hidden at its anchor after release, the app rejected or reverted the drop during its own release or capture handling.

find

Find UI elements matching selectors.

DriveNet.Cli.exe find -n MyApp --automation-id SubmitButton
DriveNet.Cli.exe find -n MyApp --path 'Pane[automationId=MainPanel] > Button[name=Save]' --match-index 2 --json
DriveNet.Cli.exe find -n MyApp --path 'Pane[automationId=MainPanel] > Button[name=Save]' --explain
DriveNet.Cli.exe find -n MyApp --window-handle 0x1A4F --automation-id ConfirmButton --json
DriveNet.Cli.exe find -n MyApp --automation-id SaveButton --fallback --json

• Prefer --automation-id when available.
• Use --path when repeated siblings make flat selectors ambiguous.
• Equivalent duplicate matches with the same selector-visible identity and bounds are collapsed before find prints or returns them.
• Run --explain before a risky inspect or interact when the selector is uncertain.

If all you need is a fresh element id after a visual refresh, rerun find with a stable selector such as --automation-id; do not dump a full tree just to reacquire one control.

inspect

Inspect one uniquely matched element with verbose detail. Use the same selectors as find, but the selector must resolve to exactly one element.

DriveNet.Cli.exe inspect -n MyApp --automation-id SubmitButton
DriveNet.Cli.exe inspect -p 12345 --name "Open" --control-type MenuItem --json

If the selector matches more than one element, run find with --explain first and tighten the selector.

interact

Perform one action against a uniquely matched element, or use the clipboard, mouseDown, mouseUp, or mouseMove without attaching to an element.

DriveNet.Cli.exe interact -n MyApp --action click --automation-id SubmitButton
DriveNet.Cli.exe interact -n MyApp --action type --automation-id SearchBox --value "fictional query"
DriveNet.Cli.exe interact -n MyApp --action hover --automation-id SubmitButton --dwell-ms 1000
DriveNet.Cli.exe interact --action clipboard --clipboard-action read
DriveNet.Cli.exe interact --action mouseDown --mouse-button left
DriveNet.Cli.exe interact --action mouseUp --destination-x 920 --destination-y 460 --mouse-button left
DriveNet.Cli.exe interact --action mouseMove --destination-x 500 --destination-y 300
DriveNet.Cli.exe interact --action mouseMove --source-x 100 --source-y 200 --destination-x 800 --destination-y 600 --mouse-button left --duration-ms 1000
DriveNet.Cli.exe interact --action mouseMove --destination-x 900 --destination-y 420 --duration-ms 800 --motion-profile exaggerated --motion-exaggeration 85
DriveNet.Cli.exe interact -n MyApp --action hover --automation-id SubmitButton --dwell-ms 1000 --motion-profile hesitant --motion-exaggeration 70
DriveNet.Cli.exe interact -n MyApp --action hover --automation-id SubmitButton --hover-mode transit --approach-from left --velocity-ms 300 --dwell-ms 1000
DriveNet.Cli.exe interact -n MyApp --action moveTo --automation-id SubmitButton --position outside-right --offset-px 24 --duration-ms 400 --motion-profile steady

Use --target-* selector options for dragTo, --highlight to flash the source element before the action, and --dwell-ms to control hover duration. mouseDown and mouseUp are useful for held-button workflows such as crosshair pickers or multi-step drags; when you omit coordinates, Drive.NET uses the current cursor position. --motion-profile and --motion-exaggeration tune the humanized pointer path for mouseMove, hover, and moveTo: steady stays straighter, natural is the default, exaggerated adds broader arcs and correction, and hesitant introduces more uneven cadence. Set --mouse-button left to simulate a held drag during mouseMove. --hover-mode transit plus --approach-from and --velocity-ms gives the CLI the same authentic boundary-crossing hover path as MCP interact. --position and --offset-px make moveTo useful for parking the pointer outside a control without raw coordinates. For top-edge appbar elements, Drive.NET automatically uses a horizontal approach path to avoid crossing the popup zone below; for neighbouring flyout panels, the smooth exit path ensures clean WM_MOUSELEAVE triggering for popup handoff.

Generic held-button drags are supported, but popup-hosted flyouts can still apply app-specific release or capture logic on mouseUp. Prefer one MCP session or a batch flow when you need to compare windows --json before and after release and re-query popup content against the popup --window-handle.

Standalone CLI interact returns a lightweight hover result rather than the richer MCP observation blocks. Use MCP interact when you need sameWindowEffect, effectObservation, replacedWindowPairs, or windowTimeline diagnostics.

Use --secret to read --value from stdin instead of passing it on the command line (avoids logging sensitive text). Use --fallback to try alternative selector strategies when the primary selector yields no results.

tree

Render the UI Automation tree for a process root or a specific matched subtree.

DriveNet.Cli.exe tree -n MyApp --max-depth 2
DriveNet.Cli.exe tree -n MyApp --max-depth 4 --max-nodes 150 --json
DriveNet.Cli.exe tree -n MyApp --automation-id MainTabs --max-depth 4 --detail verbose
DriveNet.Cli.exe tree -n MyApp --json

When no selector is given, the tree starts from the process root. When a selector is given, it must match exactly one element which becomes the subtree root.

JSON tree output now includes queryRoot, nodeCount, truncated, maxNodes, and continuationHints. When truncated is true, rerun tree against one of the hinted subtree elementId roots instead of re-dumping the whole window.

wait_for

Wait for a UI or window condition against a target process.

DriveNet.Cli.exe wait_for -n MyApp --condition elementExists --automation-id SuccessLabel
DriveNet.Cli.exe wait_for -n MyApp --condition elementExists --path 'Pane[automationId=MainPanel] > Button[name=Save]' --match-index 2
DriveNet.Cli.exe wait_for -n MyApp --condition elementExists --automation-id SuccessLabel --explain
DriveNet.Cli.exe wait_for -n MyApp --condition textEquals --automation-id StatusText --expected-value "Saved"
DriveNet.Cli.exe wait_for -n MyApp --condition windowOpened --timeout-ms 10000 --json

• The command exits with 0 when the condition is met and 1 on timeout or unmet conditions.
• Use --explain when a selector-based wait is timing out and you need diagnostics before spending the timeout budget again.
• Prefer --path for repeated controls whose parent chain matters.

batch

Execute a JSON array of query, interact, wait_for, and assert steps inside one short-lived process session.

On Windows PowerShell, prefer --steps-file for multi-step flows. If you use inline JSON with --steps, wrap the whole JSON array in single quotes.

DriveNet.Cli.exe batch -n MyApp --steps-file .\login-flow.json --json
DriveNet.Cli.exe batch -n MyApp --steps-file .\wizard.json --start-delay-ms 1000 --json
DriveNet.Cli.exe batch -n MyApp --steps '[{"tool":"query","action":"explain","path":"Pane[automationId=MainPanel] > Button[name=Submit]"},{"tool":"query","action":"find","automationId":"SubmitButton","saveAs":"submit"},{"tool":"interact","action":"click","elementId":"${submit}"}]'

Exactly one of --steps or --steps-file is required.

The CLI batch contract matches the MCP batch tool contract, including saveAs, save, ${name} substitution, when, retry, continueOnError, per-step delayBeforeMs / delayAfterMs, and the batch-only pointerPath action.

Query batch steps also support action: "resolve" when you want one fresh element id or a fast ambiguity error instead of a larger find result.

playback

Replay recorded batch JSON or YAML assets from one CLI entry point.

DriveNet.Cli.exe playback --input .\recorded-batch.json --process-name MyApp --json
DriveNet.Cli.exe playback --input tests\definitions\companion\querying.yaml --result-json .\artifacts\querying-results.json
DriveNet.Cli.exe playback --input tests\definitions\companion\manifest.yaml --fail-fast --junit-xml .\artifacts\results.xml

Use playback when you want the simplest CLI rerun path for what record produced. Batch JSON playback keeps one session alive across the full file, so it is also a clean way to avoid repeated attach overhead in terminal-driven workflows.

capture

Capture a window or one matched element. Window captures automatically trim invisible non-client resize borders when DWM reports a tighter visible frame. Supports optional border, drop shadow, and PNG (default) or JPEG encoding.

DriveNet.Cli.exe capture -n MyApp
DriveNet.Cli.exe capture -n MyApp --automation-id SubmitButton --json
DriveNet.Cli.exe capture -n MyApp --automation-id SubmitButton --padding 20 -o submit-btn.png
DriveNet.Cli.exe capture -n MyApp --format base64 --json
DriveNet.Cli.exe capture -p 12345 --window-handle 0x1A4F2 -o evidence/dialog.png
DriveNet.Cli.exe capture -n MyApp --border-thickness 3 --border-color "#336699"
DriveNet.Cli.exe capture -n MyApp --shadow --image-format jpg -o evidence/screenshot.jpg

When no selector or window handle is given, the command captures the main window. Window captures automatically trim invisible non-client resize borders when DWM reports a tighter visible frame. Use --format base64 --json when a workflow needs the inline image payload and metadata instead of a file write. --border-thickness and --shadow can be combined; shadow is rendered first, then the border frames the result. For README assets shown on GitHub, prefer omitting --shadow unless you verify the rendered page. --image-format jpg flattens transparency onto white; file extensions are adjusted automatically. After capturing, visually inspect the screenshot for personally identifiable information (real names, emails, file paths with usernames, tokens). If PII is found, note the full file path and prompt the user before keeping or discarding the image.

report

Run the shared Automation Readiness and Accessibility Compliance analysis pipeline against a live process target and write a report artifact.

DriveNet.Cli.exe report -n MyApp
DriveNet.Cli.exe report -n MyApp --format sarif --output reports/latest.sarif --json
DriveNet.Cli.exe report -n MyApp --format plan
DriveNet.Cli.exe report -n MyApp --remediation
DriveNet.Cli.exe report -n MyApp --label before-fix
DriveNet.Cli.exe report -n MyApp --label after-fix --save-snapshot

Use this when you need durable findings rather than a transient tree dump or screenshot. Use --format plan when the remediation plan itself is the primary artifact, or --remediation when you want the standard report plus a companion remediation-plan artifact. --remediation cannot be combined with --format plan.

Reports span both suites. DNC022 (small click/touch target) is reported only under Accessibility Compliance because it maps to WCAG 2.5.8 target size.

Use --label to tag output filenames (e.g. analysis-report-before-fix.md). Combine --save-snapshot with --label to capture a .dncsnap baseline alongside the report for later comparison.

snapshot

Create a live analysis snapshot or compare two existing snapshots.

DriveNet.Cli.exe snapshot create -n MyApp --output snapshots/latest.dncsnap --json
DriveNet.Cli.exe snapshot compare --baseline baseline.dncsnap --current current.dncsnap --format json --output comparisons/diff.json

Use snapshot create to capture a stable baseline, then snapshot compare to quantify regressions or improvements across runs.

lifecycle

Launch, stop, or inspect a target application's process state directly from the terminal.

DriveNet.Cli.exe lifecycle --action launch --executable-path C:\Apps\MyApp\MyApp.exe --startup-wait-ms 10000
DriveNet.Cli.exe lifecycle --action launch --executable-path C:\Apps\MyApp\MyApp.exe --arguments=--debug --working-directory C:\Apps\MyApp
DriveNet.Cli.exe lifecycle --action launch --executable-path C:\Apps\MyApp\MyApp.exe --single-instance reuse --process-name MyApp
DriveNet.Cli.exe lifecycle --action launch --executable-path C:\Apps\MyApp\MyApp.exe --no-session-start-warning
DriveNet.Cli.exe lifecycle --action status --process-id 12345 --json
DriveNet.Cli.exe lifecycle --action stop --process-id 12345 --grace-period-ms 3000

Use lifecycle when the terminal workflow must own process startup or shutdown instead of assuming the app is already running. The launch action accepts --session-start-warning and --no-session-start-warning for the pre-launch safety notice.

assert

Evaluate declarative UI assertions against one process target.

DriveNet.Cli.exe assert -n MyApp --clauses-file .\status-assertions.json --json
DriveNet.Cli.exe assert -n MyApp --clauses '[{"automationId":"lblStatus","condition":"textEquals","expected":"Saved"}]'

Use assert when a scripted or CI flow should fail immediately on unmet UI expectations instead of leaving verification to an external parser.

observe

Subscribe to live UIA events and stream them until timeout or Ctrl+C.

DriveNet.Cli.exe observe -n MyApp --event-types structureChanged,propertyChanged
DriveNet.Cli.exe observe -n MyApp --event-types focusChanged --timeout-ms 10000 --json

Use observe when polling is wasteful and you need to watch the app react to real-time UI changes.

test

Run a YAML manifest or single YAML suite through the built-in UI test runner.

DriveNet.Cli.exe test --suite tests/definitions/companion/querying.yaml
DriveNet.Cli.exe test --manifest tests/definitions/companion/manifest.yaml --result-json .\artifacts\companion-results.json

Use --result-json whenever an agent or script will inspect the run afterward.

For VS Code extension testing, spawn the Extension Development Host via F5 and use attach_only: true with process_name: Code and window_title_regex: '\[Extension Development Host\]' in the suite's app block. Do not use lifecycle launch for VS Code — Electron's singleton mutex prevents a second instance. Ensure no other Drive.NET session is attached to the same Code PID before running the test. See docs/yaml-test-runner.md — Testing VS Code / Electron Extensions for a full YAML pattern.

record

Record live interactions into batch JSON or YAML test suites.

DriveNet.Cli.exe record --action start --process-name MyApp
DriveNet.Cli.exe record --action stop --recording-id rec:abc123 --output recorded.json
DriveNet.Cli.exe record --action start --process-name MyApp --format yaml_suite --suite-name "Login Flow"

Use record when you want to capture a reproducible workflow first, then refine the generated batch or YAML output afterward. Replay the result with playback --input ....

demo

Run built-in visual verification flows directly from the CLI.

DriveNet.Cli.exe demo mouse-move --process-name DriveNet.TestApp.WinForms
DriveNet.Cli.exe demo mouse-move --process-id 12345 --duration-ms 3200 --mouse-button left
DriveNet.Cli.exe demo mouse-move --process-name MyApp --source-x-percent 10 --source-y-percent 20 --destination-x-percent 90 --destination-y-percent 80 --timings

demo mouse-move restores and foregrounds the target window, derives a safe in-window path from the live bounds, and then replays the humanised pointer motion so you can visually inspect it without hand-computing coordinates.

scaffold

Generate a starter YAML accessibility test suite targeting a named process.

DriveNet.Cli.exe scaffold --process-name MyApp
DriveNet.Cli.exe scaffold --process-name MyApp --min-score 80 --output tests/a11y-suite.yaml

Use scaffold when bootstrapping accessibility CI for a new app. The generated YAML defines a connect step, a report step with the chosen minimum-score threshold, and placeholder interact/assert steps you can customise.