AppInspector CLI

Install the Sherpa app inspector as a dotnet tool, start a local web server, then embed it in any desktop WebView or browser.

Install CLI arguments

What is AppInspector?

sherpa-inspector is the AppInspector host extracted from MAUI Sherpa. It starts a local ASP.NET Core server, connects to an existing DevFlow or AppInspector-compatible agent, and prints a machine-readable URL that a caller can load in an embedded WebView.

NuGet-distributed

Install from NuGet.org as a global or app-local dotnet tool.

Agent-spec friendly

Works with DevFlow v1 agents and falls back to legacy DevFlow agents when possible.

Automation-ready

Emits an INSPECTOR_READY JSON line so host apps and AI agents know exactly where to navigate.

Install and package

The recommended distribution is the Sherpa.AppInspector.Cli dotnet tool NuGet package.

Install the dotnet tool

Install from NuGet.org. The package ID is Sherpa.AppInspector.Cli and the installed command is sherpa-inspector.

Terminal 
dotnet tool install --global Sherpa.AppInspector.Cli

Tagged CI builds publish the package to NuGet.org and attach the .nupkg to the GitHub release.

Install app-local for an embedding host

Use a tool-path install when a host application wants to control exactly where the executable lives.

Terminal 
dotnet tool install --tool-path ./tools/appinspector Sherpa.AppInspector.Cli

At runtime, start the installed sherpa-inspector command as a child process, read stdout until the INSPECTOR_READY line appears, parse the JSON, then navigate your WebView to url.

Quick start

The target app must already be running an AppInspector-compatible agent. For MAUI apps, that means adding and starting the DevFlow agent.

Terminal 
# Minimal invocation: connect to an agent already listening on 9251
sherpa-inspector --agent-port 9251

# Full metadata-rich invocation for an embedding host
sherpa-inspector serve \
  --agent-host 127.0.0.1 \
  --agent-port 9251 \
  --agent-id simple-sample \
  --app-name SimpleInspectorSample \
  --project /path/to/project \
  --tab tree

Tip

If you discover the target app through the DevFlow broker or a host-specific broker, pass through the known agent port and any useful metadata. The only required value is the agent port.

Arguments

These are the supported command-line options for sherpa-inspector.

Option Required Default Purpose
--agent-port, --port Yes N/A Target app agent port.
--agent-host No 127.0.0.1 Target app agent host.
--agent-id No agent Friendly route/session identifier for the inspector URL.
--project No empty Project path or name echoed in the ready payload and URL.
--session-id No empty Host session metadata for embedding apps.
--app-name No agent status name Display name shown while the inspector connects.
--tab No tree Initial tab: tree, network, profiling, webview, logs, or platform.
--listen-host No 127.0.0.1 Host interface for the local inspector web server.
--listen-port No 0 Local server port. 0 chooses an ephemeral port.
--https No false Serve HTTPS when a suitable certificate is available.
--idle-timeout No 60 Seconds without WebView heartbeat before auto-exit.
--no-auto-exit No false Keep the server alive until Ctrl+C, SIGTERM, process termination, or shutdown URL.

Embedding flow

Hosts should treat stdout as the integration contract.

stdout 
INSPECTOR_READY {
  "status": "ready",
  "url": "http://127.0.0.1:54321/inspector/devflow/agent/tree?host=127.0.0.1&port=9251&token=...",
  "endpoints": ["http://127.0.0.1:54321"],
  "pid": 12345,
  "agent": {
    "host": "127.0.0.1",
    "port": 9251,
    "agentId": "agent"
  },
  "stop": {
    "shutdownUrl": "http://127.0.0.1:54321/internal/shutdown?token=...",
    "autoExitIdleSeconds": 60
  }
}
  1. Start sherpa-inspector as a child process.
  2. Read stdout until a line starts with INSPECTOR_READY .
  3. Parse the JSON payload after the prefix.
  4. Navigate your WebView to url.
  5. Stop the process with Ctrl+C, SIGTERM, the emitted pid, or stop.shutdownUrl.

Troubleshooting

The page renders, but clicks do nothing

This usually means Blazor did not hydrate. Check that /_framework/blazor.web.js returns JavaScript and that POST /_blazor/negotiate?negotiateVersion=1 returns a 200 JSON response.

Terminal 
# Replace 54321 with the emitted inspector port
curl -I http://127.0.0.1:54321/_framework/blazor.web.js
curl -X POST -I http://127.0.0.1:54321/_blazor/negotiate?negotiateVersion=1

Keep it local

AppInspector can read app state and trigger UI actions. Keep the default loopback binding unless you are intentionally building a trusted local workflow.