TypeScript/JavaScript API reference for @microsoft/winappcli.
Each CLI command is available as an async function that captures stdout/stderr and returns a typed result.
Helper utilities for MSIX identity, Electron debug identity, and build tools are also exported.
npm install @microsoft/winappcliimport { init, packageApp, certGenerate } from '@microsoft/winappcli';
// Initialize a new project with defaults
await init({ useDefaults: true });
// Generate a dev certificate
await certGenerate({ install: true });
// Package the built app
await packageApp({ inputFolder: './dist', cert: './devcert.pfx' });Every CLI command wrapper accepts an options object extending CommonOptions and returns Promise<WinappResult>.
Base options shared by most commands.
| Property | Type | Required | Description |
|---|---|---|---|
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
Result returned by every command wrapper.
| Property | Type | Required | Description |
|---|---|---|---|
exitCode |
number |
Yes | Process exit code (always 0 on success – non-zero throws). |
stdout |
string |
Yes | Captured standard output. |
stderr |
string |
Yes | Captured standard error. |
These functions wrap native winapp CLI commands. All accept CommonOptions (quiet, verbose, cwd).
Create a self-signed certificate for local testing only. Publisher must match the manifest (auto-inferred if --manifest provided or Package.appxmanifest is in working directory). Output: devcert.pfx (default password: 'password'). For production, obtain a certificate from a trusted CA. Use 'cert install' to trust on this machine.
function certGenerate(options?: CertGenerateOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
exportCer |
boolean | undefined |
No | Export a .cer file (public key only) alongside the .pfx |
ifExists |
IfExists | undefined |
No | Behavior when output file exists: 'error' (fail, default), 'skip' (keep existing), or 'overwrite' (replace) |
install |
boolean | undefined |
No | Install the certificate to the local machine store after generation |
json |
boolean | undefined |
No | Format output as JSON |
manifest |
string | undefined |
No | Path to Package.appxmanifest or appxmanifest.xml file to extract publisher information from |
output |
string | undefined |
No | Output path for the generated PFX file |
password |
string | undefined |
No | Password for the generated PFX file |
publisher |
string | undefined |
No | Publisher name for the generated certificate. If not specified, will be inferred from manifest. |
validDays |
number | undefined |
No | Number of days the certificate is valid |
Also accepts CommonOptions (quiet, verbose, cwd).
Display certificate details (subject, thumbprint, expiry). Useful for verifying a certificate matches your manifest before signing.
function certInfo(options: CertInfoOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
certPath |
string |
Yes | Path to the certificate file (PFX) |
json |
boolean | undefined |
No | Format output as JSON |
password |
string | undefined |
No | Password for the PFX file |
Also accepts CommonOptions (quiet, verbose, cwd).
Trust a certificate on this machine (requires admin). Run before installing MSIX packages signed with dev certificates. Example: winapp cert install ./devcert.pfx. Only needed once per certificate.
function certInstall(options: CertInstallOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
certPath |
string |
Yes | Path to the certificate file (PFX or CER) |
force |
boolean | undefined |
No | Force installation even if the certificate already exists |
password |
string | undefined |
No | Password for the PFX file |
Also accepts CommonOptions (quiet, verbose, cwd).
Enable package identity for debugging without creating full MSIX. Required for testing Windows APIs (push notifications, share target, etc.) during development. Example: winapp create-debug-identity ./myapp.exe. Requires Package.appxmanifest in current directory or passed via --manifest. Re-run after changing the manifest or Assets/.
function createDebugIdentity(options?: CreateDebugIdentityOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
entrypoint |
string | undefined |
No | Path to the .exe that will need to run with identity, or entrypoint script. |
keepIdentity |
boolean | undefined |
No | Keep the package identity from the manifest as-is, without appending '.debug' to the package name and application ID. |
manifest |
string | undefined |
No | Path to the Package.appxmanifest or appxmanifest.xml |
noInstall |
boolean | undefined |
No | Do not install the package after creation. |
Also accepts CommonOptions (quiet, verbose, cwd).
Generates a CodeIntegrityExternal.cat catalog file with hashes of executable files from specified directories. Used with the TrustedLaunch flag in MSIX sparse package manifests (AllowExternalContent) to allow execution of external files not included in the package.
function createExternalCatalog(options: CreateExternalCatalogOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
inputFolder |
string |
Yes | List of input folders with executable files to process (separated by semicolons) |
computeFlatHashes |
boolean | undefined |
No | Include flat hashes when generating the catalog |
ifExists |
IfExists | undefined |
No | Behavior when output file already exists |
output |
string | undefined |
No | Output catalog file path. If not specified, the default CodeIntegrityExternal.cat name is used. |
recursive |
boolean | undefined |
No | Include files from subdirectories |
usePageHashes |
boolean | undefined |
No | Include page hashes when generating the catalog |
Also accepts CommonOptions (quiet, verbose, cwd).
Print the path to the .winapp directory. Use --global for the shared cache location, or omit for the project-local .winapp folder. Useful for build scripts that need to reference installed packages.
function getWinappPath(options?: GetWinappPathOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
global |
boolean | undefined |
No | Get the global .winapp directory instead of local |
Also accepts CommonOptions (quiet, verbose, cwd).
Start here for initializing a Windows app with required setup. Sets up everything needed for Windows app development: creates Package.appxmanifest with default assets, creates winapp.yaml for version management, and downloads Windows SDK and Windows App SDK packages and generates projections. Interactive by default (use --use-defaults to skip prompts). Use 'restore' instead if you cloned a repo that already has winapp.yaml. Use 'manifest generate' if you only need a manifest, or 'cert generate' if you need a development certificate for code signing.
function init(options?: InitOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
baseDirectory |
string | undefined |
No | Base/root directory for the winapp workspace, for consumption or installation. |
configDir |
string | undefined |
No | Directory to read/store configuration (default: current directory) |
configOnly |
boolean | undefined |
No | Only handle configuration file operations (create if missing, validate if exists). Skip package installation and other workspace setup steps. |
ignoreConfig |
boolean | undefined |
No | Don't use configuration file for version management |
noGitignore |
boolean | undefined |
No | Don't update .gitignore file |
setupSdks |
SdkInstallMode | undefined |
No | SDK installation mode: 'stable' (default), 'preview', 'experimental', or 'none' (skip SDK installation) |
useDefaults |
boolean | undefined |
No | Do not prompt, and use default of all prompts |
Also accepts CommonOptions (quiet, verbose, cwd).
Add an execution alias (uap5:AppExecutionAlias) to a Package.appxmanifest. This allows launching the packaged app from the command line by typing the alias name. By default, the alias is inferred from the Executable attribute (e.g.
function manifestAddAlias(options?: ManifestAddAliasOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
appId |
string | undefined |
No | Application Id to add the alias to (default: first Application element) |
manifest |
string | undefined |
No | Path to Package.appxmanifest or appxmanifest.xml file (default: search current directory) |
name |
string | undefined |
No | Alias name (e.g. 'myapp.exe'). Default: inferred from the Executable attribute in the manifest. |
Also accepts CommonOptions (quiet, verbose, cwd).
Create Package.appxmanifest without full project setup. Use when you only need a manifest and image assets (no SDKs, no certificate). For full setup, use 'init' instead. Templates: 'packaged' (full MSIX), 'sparse' (desktop app needing Windows APIs).
function manifestGenerate(options?: ManifestGenerateOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
directory |
string | undefined |
No | Directory to generate manifest in |
description |
string | undefined |
No | Human-readable app description shown during installation and in Windows Settings |
executable |
string | undefined |
No | Path to the application's executable. Default: .exe |
ifExists |
IfExists | undefined |
No | Behavior when output file exists: 'error' (fail, default), 'skip' (keep existing), or 'overwrite' (replace) |
logoPath |
string | undefined |
No | Path to logo image file |
packageName |
string | undefined |
No | Package name (default: folder name) |
publisherName |
string | undefined |
No | Publisher CN (default: CN=) |
template |
ManifestTemplates | undefined |
No | Manifest template type: 'packaged' (full MSIX app, default) or 'sparse' (desktop app with package identity for Windows APIs) |
version |
string | undefined |
No | App version in Major.Minor.Build.Revision format (e.g., 1.0.0.0). |
Also accepts CommonOptions (quiet, verbose, cwd).
Generate new assets for images referenced in a Package.appxmanifest from a single source image. Source image should be at least 400x400 pixels.
function manifestUpdateAssets(options: ManifestUpdateAssetsOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
imagePath |
string |
Yes | Path to source image file (SVG, PNG, ICO, JPG, BMP, GIF) |
lightImage |
string | undefined |
No | Path to source image for light theme variants (SVG, PNG, ICO, JPG, BMP, GIF) |
manifest |
string | undefined |
No | Path to Package.appxmanifest or appxmanifest.xml file (default: search current directory) |
Also accepts CommonOptions (quiet, verbose, cwd).
Create MSIX installer from your built app. Run after building your app. A manifest (Package.appxmanifest or appxmanifest.xml) is required for packaging - it must be in current working directory, passed as --manifest or be in the input folder. Use --cert devcert.pfx to sign for testing. Example: winapp package ./dist --manifest Package.appxmanifest --cert ./devcert.pfx
function packageApp(options: PackageOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
inputFolder |
string |
Yes | Input folder with package layout |
cert |
string | undefined |
No | Path to signing certificate (will auto-sign if provided) |
certPassword |
string | undefined |
No | Certificate password (default: password) |
executable |
string | undefined |
No | Path to the executable relative to the input folder. |
generateCert |
boolean | undefined |
No | Generate a new development certificate |
installCert |
boolean | undefined |
No | Install certificate to machine |
manifest |
string | undefined |
No | Path to AppX manifest file (default: auto-detect from input folder or current directory) |
name |
string | undefined |
No | Package name (default: from manifest) |
output |
string | undefined |
No | Output msix file name for the generated package (defaults to .msix) |
publisher |
string | undefined |
No | Publisher name for certificate generation |
selfContained |
boolean | undefined |
No | Bundle Windows App SDK runtime for self-contained deployment |
skipPri |
boolean | undefined |
No | Skip PRI file generation |
Also accepts CommonOptions (quiet, verbose, cwd).
Use after cloning a repo or when .winapp/ folder is missing. Reinstalls SDK packages from existing winapp.yaml without changing versions. Requires winapp.yaml (created by 'init'). To check for newer SDK versions, use 'update' instead.
function restore(options?: RestoreOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
baseDirectory |
string | undefined |
No | Base/root directory for the winapp workspace |
configDir |
string | undefined |
No | Directory to read configuration from (default: current directory) |
Also accepts CommonOptions (quiet, verbose, cwd).
Creates packaged layout, registers the Application, and launches the packaged application.
function run(options: RunOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
inputFolder |
string |
Yes | Input folder containing the app to run |
args |
string | undefined |
No | Command-line arguments to pass to the application |
clean |
boolean | undefined |
No | Remove the existing package's application data (LocalState, settings, etc.) before re-deploying. By default, application data is preserved across re-deployments. |
debugOutput |
boolean | undefined |
No | Capture OutputDebugString messages and first-chance exceptions from the launched application. Only one debugger can attach to a process at a time, so other debuggers (Visual Studio, VS Code) cannot be used simultaneously. Use --no-launch instead if you need to attach a different debugger. Cannot be combined with --no-launch or --json. |
detach |
boolean | undefined |
No | Launch the application and return immediately without waiting for it to exit. Useful for CI/automation where you need to interact with the app after launch. Prints the PID to stdout (or in JSON with --json). |
json |
boolean | undefined |
No | Format output as JSON |
manifest |
string | undefined |
No | Path to the Package.appxmanifest (default: auto-detect from input folder or current directory) |
noLaunch |
boolean | undefined |
No | Only create the debug identity and register the package without launching the application |
outputAppxDirectory |
string | undefined |
No | Output directory for the loose layout package. If not specified, a directory named AppX inside the input-folder directory will be used. |
symbols |
boolean | undefined |
No | Download symbols from Microsoft Symbol Server for richer native crash analysis. Only used with --debug-output. First run downloads symbols and caches them locally; subsequent runs use the cache. |
unregisterOnExit |
boolean | undefined |
No | Unregister the development package after the application exits. Only removes packages registered in development mode. |
withAlias |
boolean | undefined |
No | Launch the app using its execution alias instead of AUMID activation. The app runs in the current terminal with inherited stdin/stdout/stderr. Requires a uap5:ExecutionAlias in the manifest. Use "winapp manifest add-alias" to add an execution alias to the manifest. |
Also accepts CommonOptions (quiet, verbose, cwd).
Code-sign an MSIX package or executable. Example: winapp sign ./app.msix ./devcert.pfx. Use --timestamp for production builds to remain valid after cert expires. The 'package' command can sign automatically with --cert.
function sign(options: SignOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
filePath |
string |
Yes | Path to the file/package to sign |
certPath |
string |
Yes | Path to the certificate file (PFX format) |
password |
string | undefined |
No | Certificate password |
timestamp |
string | undefined |
No | Timestamp server URL |
Also accepts CommonOptions (quiet, verbose, cwd).
Run a Microsoft Store Developer CLI command. This command will download the Microsoft Store Developer CLI if not already downloaded. Learn more about the Microsoft Store Developer CLI here: https://aka.ms/msstoredevcli
function store(options?: StoreOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
storeArgs |
string[] | undefined |
No | Arguments to pass through to the Microsoft Store Developer CLI. |
Also accepts CommonOptions (quiet, verbose, cwd).
Run Windows SDK tools directly (makeappx, signtool, makepri, etc.). Auto-downloads Build Tools if needed. For most tasks, prefer higher-level commands like 'package' or 'sign'. Example: winapp tool makeappx pack /d ./folder /p ./out.msix
function tool(options?: ToolOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
toolArgs |
string[] | undefined |
No | Arguments to pass to the SDK tool, e.g. ['makeappx', 'pack', '/d', './folder', '/p', './out.msix']. |
Also accepts CommonOptions (quiet, verbose, cwd).
Click an element by slug or text search using mouse simulation. Works on elements that don't support InvokePattern (e.g., column headers, list items). Use --double for double-click, --right for right-click.
function uiClick(options?: UiClickOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
double |
boolean | undefined |
No | Perform a double-click instead of a single click |
json |
boolean | undefined |
No | Format output as JSON |
right |
boolean | undefined |
No | Perform a right-click instead of a left click |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
Also accepts CommonOptions (quiet, verbose, cwd).
Move keyboard focus to the specified element using UIA SetFocus.
function uiFocus(options?: UiFocusOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
Also accepts CommonOptions (quiet, verbose, cwd).
Show the element that currently has keyboard focus in the target app.
function uiGetFocused(options?: UiGetFocusedOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
Also accepts CommonOptions (quiet, verbose, cwd).
Read UIA property values from an element. Specify --property for a single property or omit for all.
function uiGetProperty(options?: UiGetPropertyOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
property |
string | undefined |
No | Property name to read or filter on |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
Also accepts CommonOptions (quiet, verbose, cwd).
Read the current value from an element. Tries TextPattern (RichEditBox, Document), ValuePattern (TextBox, ComboBox, Slider), then Name (labels). Usage: winapp ui get-value -a
function uiGetValue(options?: UiGetValueOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
Also accepts CommonOptions (quiet, verbose, cwd).
View the UI element tree with semantic slugs, element types, names, and bounds.
function uiInspect(options?: UiInspectOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
ancestors |
boolean | undefined |
No | Walk up the tree from the specified element to the root |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
depth |
number | undefined |
No | Tree inspection depth |
hideDisabled |
boolean | undefined |
No | Hide disabled elements from output |
hideOffscreen |
boolean | undefined |
No | Hide offscreen elements from output |
interactive |
boolean | undefined |
No | Show only interactive/invokable elements (buttons, links, inputs, list items). Increases default depth to 8. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
Also accepts CommonOptions (quiet, verbose, cwd).
Activate an element by slug or text search. Tries InvokePattern, TogglePattern, SelectionItemPattern, and ExpandCollapsePattern in order.
function uiInvoke(options?: UiInvokeOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
Also accepts CommonOptions (quiet, verbose, cwd).
List all visible windows with their HWND, title, process, and size. Use -a to filter by app name. Use the HWND with -w to target a specific window.
function uiListWindows(options?: UiListWindowsOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
Also accepts CommonOptions (quiet, verbose, cwd).
Capture the target window or element as a PNG image. When multiple windows exist (e.g., dialogs), captures each to a separate file. With --json, returns file path and dimensions. Use --capture-screen for popup overlays.
function uiScreenshot(options?: UiScreenshotOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
captureScreen |
boolean | undefined |
No | Capture from screen (includes popups/overlays) instead of window rendering. Brings window to foreground first. |
json |
boolean | undefined |
No | Format output as JSON |
output |
string | undefined |
No | Save output to file path (e.g., screenshot) |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
Also accepts CommonOptions (quiet, verbose, cwd).
Scroll a container element using ScrollPattern. Use --direction to scroll incrementally, or --to to jump to top/bottom.
function uiScroll(options?: UiScrollOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
direction |
string | undefined |
No | Scroll direction: up, down, left, right |
json |
boolean | undefined |
No | Format output as JSON |
to |
string | undefined |
No | Scroll to position: top, bottom |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
Also accepts CommonOptions (quiet, verbose, cwd).
Scroll the specified element into the visible area using UIA ScrollItemPattern.
function uiScrollIntoView(options?: UiScrollIntoViewOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
Also accepts CommonOptions (quiet, verbose, cwd).
Search the element tree for elements matching a text query. Returns all matches with semantic slugs.
function uiSearch(options?: UiSearchOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
max |
number | undefined |
No | Maximum search results |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
Also accepts CommonOptions (quiet, verbose, cwd).
Set a value on an element using UIA ValuePattern. Works for TextBox, ComboBox, Slider, and other editable controls. Usage: winapp ui set-value -a
function uiSetValue(options?: UiSetValueOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
value |
string | undefined |
No | Value to set (text for TextBox/ComboBox, number for Slider) |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
Also accepts CommonOptions (quiet, verbose, cwd).
Connect to a target app and display connection info.
function uiStatus(options?: UiStatusOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
Also accepts CommonOptions (quiet, verbose, cwd).
Wait for an element to appear, disappear, or have a property reach a target value. Polls at 100ms intervals until condition met or timeout.
function uiWaitFor(options?: UiWaitForOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
contains |
boolean | undefined |
No | Use substring matching for --value instead of exact match |
gone |
boolean | undefined |
No | Wait for element to disappear instead of appear |
json |
boolean | undefined |
No | Format output as JSON |
property |
string | undefined |
No | Property name to read or filter on |
timeout |
number | undefined |
No | Timeout in milliseconds |
value |
string | undefined |
No | Wait for element value to equal this string. Uses smart fallback (TextPattern -> ValuePattern -> Name). Combine with --property to check a specific property instead. |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
Also accepts CommonOptions (quiet, verbose, cwd).
Unregisters a sideloaded development package. Only removes packages registered in development mode (e.g., via 'winapp run' or 'create-debug-identity').
function unregister(options?: UnregisterOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
force |
boolean | undefined |
No | Skip the install-location directory check and unregister even if the package was registered from a different project tree |
json |
boolean | undefined |
No | Format output as JSON |
manifest |
string | undefined |
No | Path to the Package.appxmanifest (default: auto-detect from current directory) |
Also accepts CommonOptions (quiet, verbose, cwd).
Check for and install newer SDK versions. Updates winapp.yaml with latest versions and reinstalls packages. Requires existing winapp.yaml (created by 'init'). Use --setup-sdks preview for preview SDKs. To reinstall current versions without updating, use 'restore' instead.
function update(options?: UpdateOptions): Promise<WinappResult>Options:
| Property | Type | Required | Description |
|---|---|---|---|
setupSdks |
SdkInstallMode | undefined |
No | SDK installation mode: 'stable' (default), 'preview', 'experimental', or 'none' (skip SDK installation) |
Also accepts CommonOptions (quiet, verbose, cwd).
Execute a command with BuildTools bin path added to PATH environment
function execWithBuildTools(command: string, options?: ExecSyncOptions): string | Buffer<ArrayBufferLike>Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
command |
string |
Yes | The command to execute |
options |
ExecSyncOptions |
No | Options to pass to execSync (optional) |
Returns: The output from execSync
Adds package identity information from an appxmanifest.xml file to an executable's embedded manifest
function addMsixIdentityToExe(exePath: string, appxManifestPath?: string | undefined, options?: MsixIdentityOptions): Promise<MsixIdentityResult>Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
exePath |
string |
Yes | Path to the executable file |
appxManifestPath |
string | undefined |
No | Path to the appxmanifest.xml file containing package identity data |
options |
MsixIdentityOptions |
No | Optional configuration |
Adds package identity to the Electron debug process
function addElectronDebugIdentity(options?: MsixIdentityOptions): Promise<ElectronDebugIdentityResult>Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
options |
MsixIdentityOptions |
No | Configuration options |
Clears/removes package identity from the Electron debug process by restoring from backup
function clearElectronDebugIdentity(options?: MsixIdentityOptions): Promise<ClearElectronDebugIdentityResult>Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
options |
MsixIdentityOptions |
No | Configuration options |
Get the path to the global .winapp directory
function getGlobalWinappPath(): stringReturns: The full path to the global .winapp directory
Get the path to the local .winapp directory
function getLocalWinappPath(): stringReturns: The full path to the local .winapp directory
These commands are available exclusively via npx winapp node <subcommand> and are not exported as programmatic functions.
Generate native addon files for an Electron project. Supports C++ (node-gyp) and C# (node-api-dotnet) templates.
npx winapp node create-addon [options]Options:
| Flag | Description |
|---|---|
--name <name> |
Addon name (default depends on template) |
--template <type> |
Addon template: cpp or cs (default: cpp) |
--verbose |
Enable verbose output |
Note: Must be run from the root of an Electron project (directory containing
package.json).
Examples:
npx winapp node create-addon
npx winapp node create-addon --name myAddon
npx winapp node create-addon --template cs --name MyCsAddonAdd package identity to the Electron debug process using sparse packaging. Creates a backup of electron.exe, generates a sparse MSIX manifest, adds identity to the executable, and registers the sparse package. Requires an appxmanifest.xml (create one with winapp init or winapp manifest generate).
npx winapp node add-electron-debug-identity [options]Options:
| Flag | Description |
|---|---|
--manifest <path> |
Path to custom appxmanifest.xml (default: appxmanifest.xml in current directory) |
--no-install |
Do not install the package after creation |
--keep-identity |
Keep the manifest identity as-is, without appending .debug suffix |
--verbose |
Enable verbose output |
Note: Must be run from the root of an Electron project (directory containing
node_modules/electron). To undo, usenpx winapp node clear-electron-debug-identity.
Examples:
npx winapp node add-electron-debug-identity
npx winapp node add-electron-debug-identity --manifest ./custom/appxmanifest.xmlRemove package identity from the Electron debug process. Restores electron.exe from the backup created by add-electron-debug-identity and removes the backup files.
npx winapp node clear-electron-debug-identity [options]Options:
| Flag | Description |
|---|---|
--verbose |
Enable verbose output |
Note: Must be run from the root of an Electron project (directory containing
node_modules/electron).
Examples:
npx winapp node clear-electron-debug-identityRe-exported from Node.js for convenience. See Node.js docs.
| Property | Type | Required | Description |
|---|---|---|---|
verbose |
boolean | undefined |
No | |
noInstall |
boolean | undefined |
No | |
keepIdentity |
boolean | undefined |
No | |
manifest |
string | undefined |
No |
| Property | Type | Required | Description |
|---|---|---|---|
success |
boolean |
Yes |
| Property | Type | Required | Description |
|---|---|---|---|
success |
boolean |
Yes | |
electronExePath |
string |
Yes | |
backupPath |
string |
Yes | |
manifestPath |
string |
Yes | |
assetsDir |
string |
Yes |
| Property | Type | Required | Description |
|---|---|---|---|
success |
boolean |
Yes | |
electronExePath |
string |
Yes | |
restoredFromBackup |
boolean |
Yes |
| Property | Type | Required | Description |
|---|---|---|---|
exitOnError |
boolean | undefined |
No |
| Property | Type | Required | Description |
|---|---|---|---|
exitCode |
number |
Yes |
| Property | Type | Required | Description |
|---|---|---|---|
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()) |
| Property | Type | Required | Description |
|---|---|---|---|
exitCode |
number |
Yes | |
stdout |
string |
Yes | |
stderr |
string |
Yes |
| Property | Type | Required | Description |
|---|---|---|---|
name |
string | undefined |
No | |
projectRoot |
string | undefined |
No | |
verbose |
boolean | undefined |
No |
| Property | Type | Required | Description |
|---|---|---|---|
success |
boolean |
Yes | |
addonName |
string |
Yes | |
addonPath |
string |
Yes | |
needsTerminalRestart |
boolean |
Yes | |
files |
string[] |
Yes |
| Property | Type | Required | Description |
|---|---|---|---|
name |
string | undefined |
No | |
projectRoot |
string | undefined |
No | |
verbose |
boolean | undefined |
No |
| Property | Type | Required | Description |
|---|---|---|---|
success |
boolean |
Yes | |
addonName |
string |
Yes | |
addonPath |
string |
Yes | |
needsTerminalRestart |
boolean |
Yes | |
files |
string[] |
Yes |
IfExists values.
type IfExists = "error" | "overwrite" | "skip"SdkInstallMode values.
type SdkInstallMode = "stable" | "preview" | "experimental" | "none"ManifestTemplates values.
type ManifestTemplates = "packaged" | "sparse"| Property | Type | Required | Description |
|---|---|---|---|
exportCer |
boolean | undefined |
No | Export a .cer file (public key only) alongside the .pfx |
ifExists |
IfExists | undefined |
No | Behavior when output file exists: 'error' (fail, default), 'skip' (keep existing), or 'overwrite' (replace) |
install |
boolean | undefined |
No | Install the certificate to the local machine store after generation |
json |
boolean | undefined |
No | Format output as JSON |
manifest |
string | undefined |
No | Path to Package.appxmanifest or appxmanifest.xml file to extract publisher information from |
output |
string | undefined |
No | Output path for the generated PFX file |
password |
string | undefined |
No | Password for the generated PFX file |
publisher |
string | undefined |
No | Publisher name for the generated certificate. If not specified, will be inferred from manifest. |
validDays |
number | undefined |
No | Number of days the certificate is valid |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
certPath |
string |
Yes | Path to the certificate file (PFX) |
json |
boolean | undefined |
No | Format output as JSON |
password |
string | undefined |
No | Password for the PFX file |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
certPath |
string |
Yes | Path to the certificate file (PFX or CER) |
force |
boolean | undefined |
No | Force installation even if the certificate already exists |
password |
string | undefined |
No | Password for the PFX file |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
entrypoint |
string | undefined |
No | Path to the .exe that will need to run with identity, or entrypoint script. |
keepIdentity |
boolean | undefined |
No | Keep the package identity from the manifest as-is, without appending '.debug' to the package name and application ID. |
manifest |
string | undefined |
No | Path to the Package.appxmanifest or appxmanifest.xml |
noInstall |
boolean | undefined |
No | Do not install the package after creation. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
inputFolder |
string |
Yes | List of input folders with executable files to process (separated by semicolons) |
computeFlatHashes |
boolean | undefined |
No | Include flat hashes when generating the catalog |
ifExists |
IfExists | undefined |
No | Behavior when output file already exists |
output |
string | undefined |
No | Output catalog file path. If not specified, the default CodeIntegrityExternal.cat name is used. |
recursive |
boolean | undefined |
No | Include files from subdirectories |
usePageHashes |
boolean | undefined |
No | Include page hashes when generating the catalog |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
global |
boolean | undefined |
No | Get the global .winapp directory instead of local |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
baseDirectory |
string | undefined |
No | Base/root directory for the winapp workspace, for consumption or installation. |
configDir |
string | undefined |
No | Directory to read/store configuration (default: current directory) |
configOnly |
boolean | undefined |
No | Only handle configuration file operations (create if missing, validate if exists). Skip package installation and other workspace setup steps. |
ignoreConfig |
boolean | undefined |
No | Don't use configuration file for version management |
noGitignore |
boolean | undefined |
No | Don't update .gitignore file |
setupSdks |
SdkInstallMode | undefined |
No | SDK installation mode: 'stable' (default), 'preview', 'experimental', or 'none' (skip SDK installation) |
useDefaults |
boolean | undefined |
No | Do not prompt, and use default of all prompts |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
appId |
string | undefined |
No | Application Id to add the alias to (default: first Application element) |
manifest |
string | undefined |
No | Path to Package.appxmanifest or appxmanifest.xml file (default: search current directory) |
name |
string | undefined |
No | Alias name (e.g. 'myapp.exe'). Default: inferred from the Executable attribute in the manifest. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
directory |
string | undefined |
No | Directory to generate manifest in |
description |
string | undefined |
No | Human-readable app description shown during installation and in Windows Settings |
executable |
string | undefined |
No | Path to the application's executable. Default: .exe |
ifExists |
IfExists | undefined |
No | Behavior when output file exists: 'error' (fail, default), 'skip' (keep existing), or 'overwrite' (replace) |
logoPath |
string | undefined |
No | Path to logo image file |
packageName |
string | undefined |
No | Package name (default: folder name) |
publisherName |
string | undefined |
No | Publisher CN (default: CN=) |
template |
ManifestTemplates | undefined |
No | Manifest template type: 'packaged' (full MSIX app, default) or 'sparse' (desktop app with package identity for Windows APIs) |
version |
string | undefined |
No | App version in Major.Minor.Build.Revision format (e.g., 1.0.0.0). |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
imagePath |
string |
Yes | Path to source image file (SVG, PNG, ICO, JPG, BMP, GIF) |
lightImage |
string | undefined |
No | Path to source image for light theme variants (SVG, PNG, ICO, JPG, BMP, GIF) |
manifest |
string | undefined |
No | Path to Package.appxmanifest or appxmanifest.xml file (default: search current directory) |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
inputFolder |
string |
Yes | Input folder with package layout |
cert |
string | undefined |
No | Path to signing certificate (will auto-sign if provided) |
certPassword |
string | undefined |
No | Certificate password (default: password) |
executable |
string | undefined |
No | Path to the executable relative to the input folder. |
generateCert |
boolean | undefined |
No | Generate a new development certificate |
installCert |
boolean | undefined |
No | Install certificate to machine |
manifest |
string | undefined |
No | Path to AppX manifest file (default: auto-detect from input folder or current directory) |
name |
string | undefined |
No | Package name (default: from manifest) |
output |
string | undefined |
No | Output msix file name for the generated package (defaults to .msix) |
publisher |
string | undefined |
No | Publisher name for certificate generation |
selfContained |
boolean | undefined |
No | Bundle Windows App SDK runtime for self-contained deployment |
skipPri |
boolean | undefined |
No | Skip PRI file generation |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
baseDirectory |
string | undefined |
No | Base/root directory for the winapp workspace |
configDir |
string | undefined |
No | Directory to read configuration from (default: current directory) |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
inputFolder |
string |
Yes | Input folder containing the app to run |
args |
string | undefined |
No | Command-line arguments to pass to the application |
clean |
boolean | undefined |
No | Remove the existing package's application data (LocalState, settings, etc.) before re-deploying. By default, application data is preserved across re-deployments. |
debugOutput |
boolean | undefined |
No | Capture OutputDebugString messages and first-chance exceptions from the launched application. Only one debugger can attach to a process at a time, so other debuggers (Visual Studio, VS Code) cannot be used simultaneously. Use --no-launch instead if you need to attach a different debugger. Cannot be combined with --no-launch or --json. |
detach |
boolean | undefined |
No | Launch the application and return immediately without waiting for it to exit. Useful for CI/automation where you need to interact with the app after launch. Prints the PID to stdout (or in JSON with --json). |
json |
boolean | undefined |
No | Format output as JSON |
manifest |
string | undefined |
No | Path to the Package.appxmanifest (default: auto-detect from input folder or current directory) |
noLaunch |
boolean | undefined |
No | Only create the debug identity and register the package without launching the application |
outputAppxDirectory |
string | undefined |
No | Output directory for the loose layout package. If not specified, a directory named AppX inside the input-folder directory will be used. |
symbols |
boolean | undefined |
No | Download symbols from Microsoft Symbol Server for richer native crash analysis. Only used with --debug-output. First run downloads symbols and caches them locally; subsequent runs use the cache. |
unregisterOnExit |
boolean | undefined |
No | Unregister the development package after the application exits. Only removes packages registered in development mode. |
withAlias |
boolean | undefined |
No | Launch the app using its execution alias instead of AUMID activation. The app runs in the current terminal with inherited stdin/stdout/stderr. Requires a uap5:ExecutionAlias in the manifest. Use "winapp manifest add-alias" to add an execution alias to the manifest. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
filePath |
string |
Yes | Path to the file/package to sign |
certPath |
string |
Yes | Path to the certificate file (PFX format) |
password |
string | undefined |
No | Certificate password |
timestamp |
string | undefined |
No | Timestamp server URL |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
storeArgs |
string[] | undefined |
No | Arguments to pass through to the Microsoft Store Developer CLI. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
toolArgs |
string[] | undefined |
No | Arguments to pass to the SDK tool, e.g. ['makeappx', 'pack', '/d', './folder', '/p', './out.msix']. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
double |
boolean | undefined |
No | Perform a double-click instead of a single click |
json |
boolean | undefined |
No | Format output as JSON |
right |
boolean | undefined |
No | Perform a right-click instead of a left click |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
property |
string | undefined |
No | Property name to read or filter on |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
ancestors |
boolean | undefined |
No | Walk up the tree from the specified element to the root |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
depth |
number | undefined |
No | Tree inspection depth |
hideDisabled |
boolean | undefined |
No | Hide disabled elements from output |
hideOffscreen |
boolean | undefined |
No | Hide offscreen elements from output |
interactive |
boolean | undefined |
No | Show only interactive/invokable elements (buttons, links, inputs, list items). Increases default depth to 8. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
captureScreen |
boolean | undefined |
No | Capture from screen (includes popups/overlays) instead of window rendering. Brings window to foreground first. |
json |
boolean | undefined |
No | Format output as JSON |
output |
string | undefined |
No | Save output to file path (e.g., screenshot) |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
direction |
string | undefined |
No | Scroll direction: up, down, left, right |
json |
boolean | undefined |
No | Format output as JSON |
to |
string | undefined |
No | Scroll to position: top, bottom |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
max |
number | undefined |
No | Maximum search results |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
value |
string | undefined |
No | Value to set (text for TextBox/ComboBox, number for Slider) |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
json |
boolean | undefined |
No | Format output as JSON |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
selector |
string | undefined |
No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
app |
string | undefined |
No | Target app (process name, window title, or PID). Lists windows if ambiguous. |
contains |
boolean | undefined |
No | Use substring matching for --value instead of exact match |
gone |
boolean | undefined |
No | Wait for element to disappear instead of appear |
json |
boolean | undefined |
No | Format output as JSON |
property |
string | undefined |
No | Property name to read or filter on |
timeout |
number | undefined |
No | Timeout in milliseconds |
value |
string | undefined |
No | Wait for element value to equal this string. Uses smart fallback (TextPattern -> ValuePattern -> Name). Combine with --property to check a specific property instead. |
window |
number | undefined |
No | Target window by HWND (stable handle from list output). Takes precedence over --app. |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
force |
boolean | undefined |
No | Skip the install-location directory check and unregister even if the package was registered from a different project tree |
json |
boolean | undefined |
No | Format output as JSON |
manifest |
string | undefined |
No | Path to the Package.appxmanifest (default: auto-detect from current directory) |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |
| Property | Type | Required | Description |
|---|---|---|---|
setupSdks |
SdkInstallMode | undefined |
No | SDK installation mode: 'stable' (default), 'preview', 'experimental', or 'none' (skip SDK installation) |
quiet |
boolean | undefined |
No | Suppress progress messages. |
verbose |
boolean | undefined |
No | Enable verbose output. |
cwd |
string | undefined |
No | Working directory for the CLI process (defaults to process.cwd()). |