tauri-agent-tools

CLI tool for agent-driven inspection and interaction with Tauri desktop applications. DOM, screenshot, and storage inspection read app state; eval can modify it. Monitors install temporary instrumentation. Interaction commands (click, type, scroll, etc.) are debug-only — they only work when the app runs with the dev bridge enabled.

Prerequisites

# Check if installed
which tauri-agent-tools

# Install globally if missing
npm install -g tauri-agent-tools

System dependencies by platform:

Bridge vs Standalone

Dependency checks follow the operation: window listing/info/title waits do not require ImageMagick; full-window PNG capture on macOS/Wayland uses native tools; crop/resize/diff and X11 capture require ImageMagick.

--title uses a regex on X11 and a substring on macOS/Sway/Hyprland. probe --json reports the selected PID, port, and window label; use --pid when multiple apps are running.

eval --json returns { "result": value }. It awaits promises and reports thrown expressions as errors. Commands accepting --json send fatal { "error": { "code": "…", "message": "…", "hint": "…" } } responses to stderr and exit nonzero; result records remain on stdout.

Choose exactly one condition for wait. Numeric intervals/timeouts must be positive integers; click --wait and capture --logs-duration also allow zero. check requires an assertion; --no-errors fails if observation is incomplete, including interruption by SIGINT/SIGTERM. Interrupted captures save available evidence with partial: true and warnings.

Console/IPC/mutation collectors have independent bounded buffers, report drops, and collect a final batch on stop. They restore their own instrumentation on completion, error, SIGINT, and SIGTERM while the webview is reachable. logs, rust-logs, and capture use independent v0.8 cursors; older bridges warn and fall back to destructive drain reads.

bundle stages privately and publishes only after text redaction and residual-secret checks pass. Redaction failures prevent the new archive and directory from being published. Its archive excludes unrelated existing files and rejects artifact symlinks. Missing sources produce partial: true; captures also save warnings. Images remain unredacted: review them before sharing.

Quote the complete replay command, e.g. --to-exec "node my-sidecar.js"; it is split on spaces, without shell syntax or support for arguments containing spaces.

Some commands require the Rust dev bridge running inside the Tauri app. Others work standalone.

Bridge required (needs running Tauri app with bridge): screenshot --selector, dom, eval, wait --selector, wait --eval, ipc-monitor, console-monitor, rust-logs, storage, page-state, mutations, snapshot, click, type, scroll, focus, navigate, select, invoke, capture, check, store-inspect

Bridge-enriched, but degrade gracefully (use a v0.7+ bridge for full output; otherwise emit a clear note instead of failing — pass --strict to fail loudly): capabilities audit, webview attach, health (richer with bridge v0.7+)

Standalone (no bridge needed): screenshot --title/--window-id (full window only), wait --title, list-windows, info, diff, logs, app-paths, config inspect, os-logs, sidecar tap, sidecar replay, forensics

Optional bridge (work standalone, richer with a bridge): probe, process-tree (use --deep for a bridge-free OS walk), logs (merges on-disk files alone, or also reads the bridge ring buffer with an independent cursor on v0.8+), bundle, diagnose

The bridge auto-discovers via token files in /tmp/tauri-dev-bridge-*.token. No manual port/token configuration needed.

Don't know where to start? diagnose

When something's wrong and you're not sure why, run:

tauri-agent-tools diagnose --config ./src-tauri -o ./diagnose-out

diagnose is a best-effort super-command. It always runs the bridge-free forensics half; if a dev bridge is reachable it also layers /process, /capabilities, /devtools, /health data. The master summary.md lists "Next steps" pointing at the right deeper command. See the tauri-debug-quickstart skill for a full symptom-to-command decision tree.

Debugging decision tree (precision form)

When you know what you're looking at, jump straight to:

Core Workflows

Inspect DOM then screenshot an element

# 1. Find the target app
tauri-agent-tools list-windows --tauri

# 2. Explore DOM structure
tauri-agent-tools dom --depth 3

# 3. Narrow down to a specific subtree
tauri-agent-tools dom ".sidebar" --depth 2 --styles

# 4. Screenshot the element
tauri-agent-tools screenshot --selector ".sidebar .nav-item.active" -o /tmp/nav.png

Monitor IPC calls

# Watch all IPC calls for 10 seconds
tauri-agent-tools ipc-monitor --duration 10000 --json

# Filter to specific commands
tauri-agent-tools ipc-monitor --filter "get_*" --duration 5000 --json

Diagnose app state

# Check page URL, title, viewport, scroll position
tauri-agent-tools page-state --json

# Inspect storage
tauri-agent-tools storage --type local --json

# Check console for errors
tauri-agent-tools console-monitor --level error --duration 5000 --json

Capture a full debug snapshot

# Screenshot + DOM + page state + storage in one call
tauri-agent-tools snapshot -o /tmp/debug --json

Compare screenshots

# Pixel-level comparison
tauri-agent-tools diff /tmp/before.png /tmp/after.png --json

# Fail CI if more than 1% of pixels differ
tauri-agent-tools diff /tmp/expected.png /tmp/actual.png --threshold 1

Monitor Rust logs and sidecar output

# Watch Rust tracing logs for 10 seconds
tauri-agent-tools rust-logs --duration 10000 --json

# Only warnings and errors (severity-based: warn shows warn+error)
tauri-agent-tools rust-logs --level warn --duration 5000 --json

# Filter to a specific Rust module
tauri-agent-tools rust-logs --target "myapp::db" --duration 5000 --json

# Only sidecar output (e.g. ffmpeg, python scripts)
tauri-agent-tools rust-logs --source sidecar --duration 10000 --json

# Specific sidecar
tauri-agent-tools rust-logs --source sidecar:ffmpeg --duration 5000 --json

Merge scattered logs into one timeline (logs)

A real app spreads logs across the bridge ring buffer, the webview console, an on-disk tauri-plugin-log file, and sidecar output. logs discovers what's available, normalizes every source, and emits one timestamp-ordered stream (NDJSON by default; --pretty for humans). Works with no bridge.

# Merge the on-disk log dir (auto-resolved from tauri.conf.json) + the bridge ring buffer
tauri-agent-tools logs --config ./src-tauri --pretty

# No source tree handy? Locate the OS log dir from a bundle id; skip the bridge
tauri-agent-tools logs --identifier com.example.app --no-bridge

# Point at explicit files / a custom dir; filter + infer correlation ids (run_id, requestId…)
tauri-agent-tools logs --log-dir ~/Library/Logs/com.example.app --level warn --correlate
tauri-agent-tools logs --log-file /path/a.log --log-file /path/b.log --filter "block_id=42"

# Follow live bridge logs until Ctrl-C (v0.8 bridge: non-draining cursor reads,
# safe to run alongside other log consumers). Against a pre-0.8 bridge it emits
# a one-time note and degrades to drain polling every --interval ms.
tauri-agent-tools logs --follow --level warn
tauri-agent-tools logs --follow --interval 1000 --pretty

Each entry is {ts, level, source, subsystem, message, origin} (+ correlation with --correlate). source is rust / sidecar:<name> (bridge) or file:<basename> (disk). Timezone-less timestamps are read as UTC so ordering is host-independent.

Bridge-extended diagnostics (process tree, capabilities, devtools, health)

These commands prefer richer endpoints on a v0.7+ bridge but degrade gracefully against older/vendored bridges: each calls GET /version first to feature-detect, and when an endpoint is missing it emits a clear note: (and falls back where it can) instead of failing. Pass --strict to make a missing endpoint a hard error instead.

# Tauri PID + registered sidecars (uses /process on a v0.7+ bridge).
# On older bridges it degrades to an OS walk when the app PID is resolvable.
tauri-agent-tools process-tree --json

# Walk the REAL OS descendant tree — sidecar children, MCP servers, ML workers —
# without the bridge at all (great for unregistered grandchildren):
tauri-agent-tools process-tree --deep --json
tauri-agent-tools process-tree --deep --pid 12345   # no bridge needed with an explicit PID

# Devtron-style live capability audit (uses /capabilities)
tauri-agent-tools capabilities audit --json
# findings[] flag wildcard "*", over-broad shell:/fs:/http: scopes,
# capabilities that reference window labels not actually registered, etc.

# Inspector URL or platform hint (uses /devtools)
tauri-agent-tools webview attach              # human-readable with hint
tauri-agent-tools webview attach --print-url  # URL alone (empty if none)
tauri-agent-tools webview attach --open       # launch in default browser

# "Is this app sick" check (uses /health). Exits non-zero on unhealthy.
tauri-agent-tools health --json

Sidecars only appear in the bridge's /process view (process-tree without --deep, and health) if integrators register them — by passing Some(&registry) to dev_bridge::spawn_sidecar_monitored or calling dev_bridge::register_sidecar. process-tree --deep needs none of that — it reads the live OS process table, so it surfaces unregistered children and grandchildren regardless.

Bridge-free diagnostics (post-mortem & sidecar workflows)

These six commands need no live bridge — useful for release builds, dead apps, and sidecar processes.

# Resolve the app's OS data/log/cache/config dirs from tauri.conf.json
tauri-agent-tools app-paths --config ./src-tauri --json
# All three platforms (handy for cross-OS forensics)
tauri-agent-tools app-paths --config ./src-tauri --platform all --exists

# Structured snapshot of the app config + capability/permission audit
tauri-agent-tools config inspect --config ./src-tauri --json
# warnings[] flags wildcard "*" perms, fs:allow-all, capabilities referencing
# plugins not declared in Cargo.toml, sidecars declared without tauri-plugin-shell.

# OS-level log tail, filtered to a Tauri bundle id (NDJSON one-per-line)
tauri-agent-tools os-logs --identifier com.example.app --duration 5000
tauri-agent-tools os-logs --level error --source main --duration 30000

# Run a sidecar under a tap to see its stdio + validate against a JSON Schema
tauri-agent-tools sidecar tap --schema ./schema.json --record /tmp/run.ndjson -- node my-sidecar.js
# Replay deterministically
tauri-agent-tools sidecar replay /tmp/run.ndjson --to-exec "node my-sidecar.js" --rate 100

# One-shot forensic bundle for post-crash analysis. Works on a DEAD app.
tauri-agent-tools forensics --config ./src-tauri -o ./forensics-out
# → ./forensics-out/{summary.md,summary.json,project.json,app-log-tail.txt,live-os-log.ndjson}
# summary.md includes detected panic markers + suggested next commands.

# One-shot SHAREABLE incident bundle: merges logs + deep process tree + app-paths +
# forensics (+ optional UI capture) into one redacted directory and a .tar.gz.
tauri-agent-tools bundle --config ./src-tauri -o ./triage
# → ./triage/{logs.ndjson,process-tree.json,app-paths.json,forensics/,summary.md} + ./triage.tar.gz
tauri-agent-tools bundle --config ./src-tauri --with-capture -o ./triage   # also screenshot + DOM (needs bridge)
# Secrets (token/api_key/password/JWTs/AWS keys/…) and PII (emails, IPs, phone
# numbers, home paths) are redacted from text artifacts on write; unredacted
# images are flagged as warnings in the redact phase.

Watch DOM mutations

# Observe child additions/removals for 10 seconds
tauri-agent-tools mutations "#todo-list" --duration 10000 --json

# Also track attribute changes
tauri-agent-tools mutations ".sidebar" --attributes --duration 5000

Find elements by text

# Search for elements containing text
tauri-agent-tools dom --text "Settings" --first --json

Interact with the app

# Click a button
tauri-agent-tools click ".submit-btn" --json

# Type into an input
tauri-agent-tools type "#search" "hello world" --json

# Clear and retype
tauri-agent-tools type "#email" "new@email.com" --clear --json

# App applies the value on a transition/async render: wait longer for it to stick
tauri-agent-tools type "#q" "term" --verify-timeout 2000 --json

# Scroll to bottom
tauri-agent-tools scroll --to-bottom --json

# Scroll element into view
tauri-agent-tools scroll --selector "#item-42" --into-view

# Focus an element
tauri-agent-tools focus "#username" --json

# Navigate to a route
tauri-agent-tools navigate "/settings" --json

# Select a dropdown value
tauri-agent-tools select "#country" "US" --json

# Toggle a checkbox
tauri-agent-tools select "input[type=checkbox]" --toggle --json

# Invoke a Tauri IPC command
tauri-agent-tools invoke get_release_context --json
tauri-agent-tools invoke save_item '{"id": 42}' --json

type and select <value> write through the element's native value setter (so React/Vue/Svelte controlled inputs see the change); select --toggle performs a native click(). Both then re-read the element. verification: "reverted" in the failure JSON (exit 1, with a hint; type prints it with --json, select always) means the app rolled the write back — a controlled input that rejected it — and is the app's answer, not a tooling error. verification: "transformed" means the app reformatted the value and counts as success (verified: false).

Probe, capture, and check (workflow commands)

# Discover targets and check bridge health
tauri-agent-tools probe --json

# Capture a full debug evidence bundle
tauri-agent-tools capture -o /tmp/debug --json
# Produces: manifest.json, screenshot.png, dom.json, page-state.json, storage.json, console-errors.json, rust-logs.json

# Run structured assertions
tauri-agent-tools check --selector ".app-ready" --no-errors --json
tauri-agent-tools check --eval "document.querySelectorAll('.block').length > 0" --json
tauri-agent-tools check --text "Workflow loaded" --json

Inspect reactive stores

# Auto-detect framework and list all stores
tauri-agent-tools store-inspect --json

# Inspect a specific store
tauri-agent-tools store-inspect --store executionStore --json

Target specific apps and windows

# Target a specific app by PID
tauri-agent-tools page-state --pid 12345 --json

# Target a specific window in a multi-window app
tauri-agent-tools eval "document.title" --window-label overlay --json

Command Reference

Targeting Flags

All bridge-dependent commands support these flags:

• --port <n> / --token <s> — explicit bridge config (skips auto-discovery)
• --pid <n> — target a specific app by PID
• --window-label <label> — target a specific webview window (default: main)
• --strict — for v0.7-endpoint commands, fail with an upgrade error instead of degrading when the bridge is too old

Important Notes

• Evaluation can modify app state. eval runs unrestricted JavaScript. Monitors, capture, and check --no-errors install temporary instrumentation and clean it up when they stop; force-killing the CLI cannot run cleanup.
• Interaction commands are debug-only. They only work with the dev bridge (debug builds).
• Use --json for structured, parseable output in automation.
• Always use --duration with ipc-monitor, console-monitor, rust-logs, and mutations.
• screenshot --selector requires both the bridge AND platform screenshot tools (imagemagick).
• Multi-app targeting: Use --pid to target a specific app. Use probe to discover all running bridges.