inspector-avalonia-cli

name	inspector-avalonia-cli
description	Use Inspector CLI for Avalonia inspection, debugging, live preview introspection, editing/mutation workflows, and troubleshooting across stub, host, and process modes.

Inspector Avalonia CLI Skill

Use this skill when users want to inspect, debug, preview, edit, or troubleshoot Avalonia UI state through Inspector.Cli.

High-value use cases

1. Inspection
   • Explore visual/logical tree topology
   • Read node metadata and properties
2. Debugging
   • Verify whether expected controls exist in tree snapshots
   • Compare property values and value sources
3. Live preview validation
   • Attach to a running Avalonia app process and confirm live snapshot availability
4. Editing / mutation
   • Set node properties
   • Run structure mutation commands (prefer dry-run first)
5. Troubleshooting
   • Diagnose process/session/mode issues via standardized diagnostics and exit codes

Command convention

Run from repository root:

dotnet run --project src/Inspector.Cli -- <command> ...

Use --json by default for automation.

Core workflow (always)

1. Connect and capture data.sessionId.
2. Run tree/property/mutation commands with --session-id.
3. Check success, exitCode, error, and diagnostics for each command.

Connection modes (detailed behavior)

Stub mode

dotnet run --project src/Inspector.Cli -- connect --mode stub --client-id agent --json

How it works:

• No target app is required
• Uses deterministic in-memory fixtures
• Best for command-flow testing and agent workflow validation

Host mode

dotnet run --project src/Inspector.Cli -- connect --mode host --address local://inspector --client-id agent --json

How it works:

• Targets an instrumented app host endpoint
• Suitable when app integrates Inspector host runtime directly
• Good for controlled inspection/editing sessions

Process mode (no host attach path)

dotnet run --project src/Inspector.Cli -- connect --mode process --pid <pid> --client-id agent --json
# or
dotnet run --project src/Inspector.Cli -- connect --mode process --name <process-name> --client-id agent --json

Rules:

• Exactly one of --pid or --name is required in process mode.
• If name resolution is ambiguous, retry with PID.
• Check data.processSnapshotAvailable:
  • true: live Avalonia snapshot is available (real nodes/properties)
  • false: process metadata fallback is being used (not full UI tree)

How it works:

• Resolves process target first
• Loads live snapshot from the process snapshot store when available
• Keeps using session-based commands after connect

Session commands

dotnet run --project src/Inspector.Cli -- tree get --session-id <session-id> --kind visual --json
dotnet run --project src/Inspector.Cli -- tree get --session-id <session-id> --kind logical --json
dotnet run --project src/Inspector.Cli -- node get-properties --session-id <session-id> --node-id <node-id> --json
dotnet run --project src/Inspector.Cli -- node set-property --session-id <session-id> --node-id <node-id> --property <name> --value <json-or-text> --json
dotnet run --project src/Inspector.Cli -- tree mutate --session-id <session-id> --target-node-id <node-id> --operation <set-property|insert|remove|move|reparent> --payload <json> --json
dotnet run --project src/Inspector.Cli -- tree batch-mutate --session-id <session-id> --operations <json-array|json-object> --json

Use --dry-run for cautious mutation workflows.

Workflow by scenario

A) Inspection workflow

1. Connect (stub / host / process)
2. tree get for visual + logical
3. node get-properties for selected nodes

B) Debugging workflow

1. Connect in same mode as failing scenario
2. tree get to validate control existence/hierarchy
3. node get-properties to confirm runtime values

C) Live preview / running app validation

1. Start target app
2. Connect with --mode process --pid <pid> or --name <name>
3. Confirm processSnapshotAvailable=true
4. Retrieve trees/properties and verify expected UI state

D) Editing workflow

1. Connect and gather baseline tree/properties
2. Use node set-property for value updates
3. Use tree mutate with --dry-run first, then apply
4. Use tree batch-mutate for fast multi-change updates (properties + structural changes in one call)
5. Re-read tree/properties to verify effects

Batch operation shape:

[
  {
    "targetNodeId": "visual-label",
    "operation": "set-property",
    "payload": { "property": "Text", "value": "Welcome" }
  },
  {
    "targetNodeId": "visual-root",
    "operation": "insert",
    "payload": { "typeName": "Avalonia.Controls.TextBox", "name": "EmailInput" }
  }
]

E) Troubleshooting workflow

1. Re-run connect in --json
2. Inspect error.code, error.message, diagnostics
3. Fix arguments or mode targeting and retry

Sample app live process snapshots

Start sample app:

dotnet run --project samples/Inspector.SampleApp

Then connect in process mode to the app PID and verify processSnapshotAvailable=true.

Exit codes and reliability

• 0 success
• 2 validation error
• 3 execution error
• 10 unexpected error

High-signal diagnostics

• cli.process.not_found
• cli.process.ambiguous
• cli.process.exited
• cli.session.not_found

When non-zero: surface error.code, error.message, and diagnostics directly, then retry with corrected arguments.