CLI Reference

Read commands discover the active Auditaur session automatically when --db is omitted. Pass --db <path> to select a specific SQLite database.

cargo run -p auditaur-cli -- doctor [--db <path>]
cargo run -p auditaur-cli -- doctor tauri [--path <app-or-src-tauri-path>] [--json]
cargo run -p auditaur-cli -- apps [--json]
cargo run -p auditaur-cli -- health [--json]
cargo run -p auditaur-cli -- apple observe --destination <xcode-destination-or-name> [--scheme <scheme>] [--workspace <path> | --project <path>] [--app-path <app>] [--bundle-id <id>] [--screenshot <path>] [--report <path>] [--diagnostics <file-or-dir>] [--log-predicate <predicate>] [--log-seconds <n>] [--skip-build] [--skip-launch] [--json]
cargo run -p auditaur-cli -- apple screenshot --destination <xcode-destination-or-name> --output <path> [--json]
cargo run -p auditaur-cli -- apple logs --destination <xcode-destination-or-name> [--output <path>] [--predicate <predicate>] [--seconds <n>] [--json]
cargo run -p auditaur-cli -- apple status --destination <xcode-destination-or-name> [--json]
cargo run -p auditaur-cli -- start [--config <path>] [--write-session <path>] [--json] [-- <command> [args...]]
cargo run -p auditaur-cli -- drill [<name>] [--config <path>] [--session-file <path>] [--json]
cargo run -p auditaur-cli -- inspect [--session-file <path>] [--limit <n>] [--json]
cargo run -p auditaur-cli -- stop [--session-file <path>] [--json]
cargo run -p auditaur-cli -- init skill [--path <repo-root>] [--agents-path] [--force] [--json]
cargo run -p auditaur-cli -- init extension [--path <repo-root>] [--force] [--json]
cargo run -p auditaur-cli -- init diagnostics [--path <repo-root>] [--dry-run] [--force] [--json]
cargo run -p auditaur-cli -- debug [--db <path>] [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--cdp-port <port>] [--require-frontend] [--require-drive-bridge] [--json] status
cargo run -p auditaur-cli -- debug [--db <path>] [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--cdp-port <port>] [--require-frontend] [--require-drive-bridge] [--json] watch [--interval-ms <ms>] [--timeout-seconds <n>] [--until-ready]
cargo run -p auditaur-cli -- debug [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--cdp-port <port>] [--require-frontend] [--require-drive-bridge] [--json] run [--interval-ms <ms>] [--timeout-seconds <n>] [--write-session <path>] -- <command> [args...]
cargo run -p auditaur-cli -- drill run --app <name> [--require-frontend] [--require-drive-bridge] [--timeout-seconds <n>] [--interval-ms <ms>] [--report <path>] [--selector <css>] [--expect-text <text>] [--script <path>] [--json] -- <command> [args...]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] inspect
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] wait --selector <css> [--target auditaur-bridge] [--timeout-ms <ms>] [--visible | --visible-only] [--test-id <id>] [--step-id <id>]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] exists --selector <css> [--target auditaur-bridge] [--visible | --visible-only] [--test-id <id>] [--step-id <id>]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] text --selector <css> [--target auditaur-bridge] [--visible | --visible-only] [--test-id <id>] [--step-id <id>]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] screenshot --output <path> [--snapshot-output <path>] [--selector <css>] [--target auditaur-bridge] [--test-id <id>] [--step-id <id>]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] snapshot [--output <path>] [--selector <css>] [--target auditaur-bridge] [--test-id <id>] [--step-id <id>]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] click --selector <css> [--target auditaur-bridge] [--visible | --visible-only] [--test-id <id>] [--step-id <id>]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] fill --selector <css> --value <text> [--target auditaur-bridge] [--visible | --visible-only] [--test-id <id>] [--step-id <id>]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] type --selector <css> --value <text> [--target auditaur-bridge] [--visible | --visible-only] [--test-id <id>] [--step-id <id>]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] press --key <key> [--selector <css>] [--target auditaur-bridge] [--test-id <id>] [--step-id <id>]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] hover --selector <css> [--target auditaur-bridge] [--visible | --visible-only] [--test-id <id>] [--step-id <id>]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] select --selector <css> --value <value> [--value <value>...] [--target auditaur-bridge] [--visible | --visible-only] [--test-id <id>] [--step-id <id>]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] check --selector <css> [--target auditaur-bridge] [--visible | --visible-only] [--test-id <id>] [--step-id <id>]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] uncheck --selector <css> [--target auditaur-bridge] [--visible | --visible-only] [--test-id <id>] [--step-id <id>]
cargo run -p auditaur-cli -- drive [--app <name>] [--session-id <id>] [--instance-id <id>] [--pid <pid>] [--latest] [--active] [--json] evaluate --expression <js> [--target auditaur-bridge] [--test-id <id>] [--step-id <id>]
cargo run -p auditaur-cli -- sessions [--db <path>] [--json] [--limit <n>]
cargo run -p auditaur-cli -- logs [--db <path> | --session-file <path>] [--json] [--session <id>] [--trace <id>] [--since <duration>] [--limit <n>]
cargo run -p auditaur-cli -- errors [--db <path> | --session-file <path>] [--json] [--session <id>] [--trace <id>] [--since <duration>] [--limit <n>]
cargo run -p auditaur-cli -- exceptions [--db <path> | --session-file <path>] [--json] [--markdown] [--output <path>] [--fingerprint <id>] [--session <id>] [--trace <id>] [--since <duration>] [--limit <n>]
cargo run -p auditaur-cli -- traces [--db <path> | --session-file <path>] [--json] [--session <id>] [--since <duration>] [--failed] [--limit <n>]
cargo run -p auditaur-cli -- trace <trace-id> [--db <path> | --session-file <path>] [--json] [--session <id>]
cargo run -p auditaur-cli -- agent-runs [--db <path> | --session-file <path>] [--app <name>] [--json] [--session <id>] [--since <duration>] [--limit <n>]
cargo run -p auditaur-cli -- agent-run <run-id> [--db <path> | --session-file <path>] [--app <name>] [--json] [--session <id>]
cargo run -p auditaur-cli -- ipc [--db <path> | --session-file <path>] [--json] [--session <id>] [--trace <id>] [--since <duration>] [--failed] [--limit <n>]
cargo run -p auditaur-cli -- events [--db <path> | --session-file <path>] [--json] [--session <id>] [--trace <id>] [--since <duration>] [--limit <n>]
cargo run -p auditaur-cli -- windows [--db <path> | --session-file <path>] [--json] [--session <id>] [--limit <n>]
cargo run -p auditaur-cli -- timeline [--db <path> | --session-file <path>] [--json] [--session <id>] [--trace <id>] [--anchor <kind:value>] [--window <duration>] [--since <duration>] [--limit <n>]
cargo run -p auditaur-cli -- related [--db <path> | --session-file <path>] [--json] [--session <id>] [--trace <id>] [--run-id <id>] [--window <label>] [--anchor <kind:value>] [--anchor-window <duration>] [--since <duration>] [--limit <n>]
cargo run -p auditaur-cli -- explain [--db <path> | --session-file <path>] [--json] [--session <id>] [--trace <id>] [--anchor <kind:value>] [--window <duration>] [--since <duration>] [--limit <n>]
cargo run -p auditaur-cli -- diagnose [--db <path> | --session-file <path>] [--json] [--session <id>] [--trace <id>] [--anchor <kind:value>] [--window <duration>] [--since <duration>] [--limit <n>]
cargo run -p auditaur-cli -- bundle [--db <path> | --session-file <path>] [--session <id>] [--trace <id>] [--since <duration>] [--redacted] [--output <path>] [--limit <n>]
cargo run -p auditaur-cli -- tail [--db <path> | --session-file <path>] [--session <id>] [--trace <id>] [--signal failures] [--replay] [--interval-ms <ms>] [--duration-seconds <n>] [--json]
cargo run -p auditaur-cli -- mcp

Human output is compact and bounds table cells. JSON output uses camelCase fields matching the Rust model.

apple is the native-app observe foundation for iOS Simulator-first workflows. apple observe resolves and boots a simulator destination using xcrun simctl, optionally runs xcodebuild build when --scheme is provided, optionally installs --app-path, optionally launches --bundle-id, captures --screenshot, collects recent simulator logs through simctl spawn <udid> log show --style json, counts Auditaur Apple diagnostics from --diagnostics <json-file-or-directory>, and writes an agent-readable JSON report. Use AuditaurAppleCore in the app, and for local Simulator observation use FileAuditaurExporter(directory:) to write batch JSON that --diagnostics can summarize. apple screenshot, apple logs, and apple status expose the same simulator selection in smaller commands.

start, default drill, inspect, and stop are the simplified agent contract. They read .auditaur/config.json by default and share .auditaur/session.json by default. A minimal config keeps app startup and drills together:

{
  "app": "my-tauri-app",
  "start": "npm run tauri dev",
  "readiness": {
    "frontend": true,
    "driveBridge": true,
    "timeoutSeconds": 180
  },
  "ports": {
    "web": {
      "env": "AUDITAUR_WEB_PORT"
    }
  },
  "defaultDrill": "smoke",
  "drills": {
    "smoke": {
      "selector": "#ready",
      "expectText": "Ready"
    }
  }
}

start delegates to debug run, waits for the newly spawned Auditaur session, and writes a session file. start --json emits one final startup object instead of streaming readiness progress, so agents can parse a single JSON document. If ports are configured, start reserves random local ports, exposes them through optional environment variables, expands {{port:name}} placeholders in the start command, and records the chosen ports in the session file and JSON output. drill runs the configured default or named drill; when the session file exists it uses the already-started app, and when it does not it falls back to an owned drill using the configured start command and cleanup behavior. inspect summarizes failures for the exact live session file. stop stops the process tree recorded by the session file. Read commands accept --session-file <path> as a postmortem-safe selector: they read the pinned database/session without requiring the recorded process to still be running.

init skill installs the Auditaur agent skill into .github/skills/auditaur-debug/SKILL.md for a consuming repository. Use --agents-path to install the same skill into .agents/skills/auditaur-debug/SKILL.md for agents that scan .agents/skills, --path <repo-root> to target another repo, and --force to overwrite an existing skill. The skill teaches Copilot/agents the recommended Auditaur debug readiness, attach-vs-wrapper startup choice, Tauri-native drive bridge, screenshot/snapshot, telemetry, and cleanup workflow. init extension installs the Auditaur manual-gate canvas extension into .github/extensions/auditaur-gate/extension.mjs so Copilot app sessions can render drill human gates as action cards and publish gate responses. init diagnostics installs optional .auditaur/diagnostics.json and .auditaur/diagnostics.md starter files with versioned generic failure-signal/checkpoint guidance; use --dry-run to preview and --force to overwrite. After the skill is available from the Auditaur repository on GitHub, users with GitHub CLI skill support can also install it with gh skill install sethjuarez/auditaur auditaur-debug. --since, --window, and --anchor-window accept durations such as 30s, 10m, 2h, or 1d. timeline merges logs, spans, span events, frontend errors, IPC calls, events, and window states into one chronological view. related returns the correlated structured rows behind trace, run, window, session, and recent-activity investigations. timeline, related, explain, and diagnose can focus on generic anchors such as trace:<id>, ipc:<command-or-latest>, error:latest, event:<name>, checkpoint:<name>, or time:<rfc3339-or-unix-nanos>; error:latest resolves to the latest generic failure signal, including frontend errors, failed IPC calls, failed spans, and error-level logs. Note that related --window keeps its existing window-label meaning, so anchor duration there is --anchor-window. diagnose composes existing findings and failure timeline signals without app-specific lenses. tail --signal failures is an opt-in filtered stream over frontend errors, failed IPC, failed spans, and error logs; default tail output is unchanged. Failure timelines may include raw application log lines, so apps must redact provider frames, prompts, transcripts, URLs with secrets, and user content before logging them; diagnostics config is guidance, not retroactive log sanitization. agent-runs groups agentive-style spans by run id and surfaces trace id, root command, model/tool call counts, provider/model, status, duration, logs, errors, and final summary when present. agent-run <run-id> drills into the grouped model calls, tool calls, agent events, logs, IPC calls, and errors for a run; --app <name> resolves a discovered app such as cutready without manually passing --db. explain summarizes obvious failures. exceptions groups captured frontend exceptions, Rust panic-hook records, and failed IPC calls by stable fingerprint. Use --fingerprint <id> to drill into one group, --markdown for a GitHub issue-ready draft, and --output <path> to write the JSON or Markdown report to disk; review and redact the local report before posting it publicly. bundle always redacts share-sensitive JSON fields and exports bounded JSON suitable for bug reports or handoffs; --redacted is accepted for explicitness.

apps reads discovery files from the local Auditaur data directory and marks entries stale when the heartbeat is older than 30 seconds. Stale entries for the same app identity are annotated with supersededBySessionId, secondsUntilNextStart, churnSessionCount, churnWindowSeconds, and churnHint when newer sessions appear after them. This helps distinguish a normal app exit from likely restart/session churn, such as a Tauri dev watcher rebuild after source edits, and highlights repeated restart bursts within a short window. health summarizes active/stale app health from heartbeat freshness, session churn hints, database readability/schema validation, and collector capability version skew; stale apps are surfaced but do not fail the overall report. debug exposes an agent-friendly readiness timeline. Prefer attach mode for human/local debugging: start the app normally, then run debug watch --until-ready. Use debug run -- <command> for agent-owned startup where Auditaur should start the normal app command under observation and leave it running after readiness. When --app is supplied, debug run snapshots matching discovery records before spawn, waits for a new post-spawn Auditaur session, and pins readiness to that exact session/database/pid instead of broad --active or --latest discovery. Pass --write-session <path> to write the final startup artifact with app, process, status, and ready-to-use selectors arrays for later debug, drive, and read commands. Use drill run instead when Auditaur should own cleanup and produce a pass/fail confidence report. The readiness timeline distinguishes app discovery, heartbeat freshness, database/schema readiness, session rows, window telemetry, backend/plugin telemetry, optional frontend telemetry, optional Tauri-native drive bridge readiness, and optional legacy browser-debug endpoint readiness. Pass --require-frontend when the session should not be considered ready until frontend logs/errors/IPC/events are observed, and pass --require-drive-bridge when selector drive actions must wait for initAuditaur({ driveBridge: true }) to register a fresh bridge. JSON output is suitable for agents and includes ready, stages, telemetry, cdp, and hints.

drill run is the first built-in confidence runner for app-owned validation workflows. It snapshots matching sessions before spawning the wrapped command, waits for a new post-spawn Auditaur session, pins subsequent readiness/drive/telemetry checks to that session and database, writes a redacted JSON report, and cleans up the spawned process tree. Use it when a smoke/confidence script should own lifecycle instead of composing debug run, drive, errors, ipc, and explain by hand. Before selector checks, drill run sends a selector-independent drive bridge ping to distinguish no bridge, stale heartbeat, active-but-unresponsive bridge, and selector failure. Older frontend bridge clients that respond with unsupported drive bridge action: ping are reported as pingUnsupportedButBridgeResponsive compatibility passes because the response still proves the bridge action loop is alive. Exit codes are stable: 0 passed, 1 check failed, 2 runner/config error, 3 app exited before readiness, 4 timeout, and 5 cleanup failure. Pass --selector and/or --expect-text for one simple visible text check.

Pass --script <path> to run app-authored setup hooks, human gates, and teardown hooks around the wrapped app command. Script files are JSON; command hooks are executed directly with Command::new(run).args(args), not through a shell, and cwd must resolve inside the current workspace/repo root. Setup hooks run before the app is spawned. Human gates run after Auditaur pins the new spawned app session and reaches debug readiness, but before selector/text/error/IPC/explain evidence collection; this keeps OAuth consent, OS permission prompts, installer elevation, camera/mic permissions, external browser handoffs, and hardware-key approvals in the same trustworthy session. Gates print tester instructions, optionally poll a visible selector for expected text, can attempt to copy a value such as an OAuth device code to the local OS clipboard, can expose script-defined choices (continue, retry, skip, fail, or abort), and can collect optional pasted text inputs for external context. Gates that need a manual response also publish a session-local human-gates request beside the pinned session database; an MCP client can list it with list_pending_human_gates and answer it with respond_human_gate, while terminal ENTER/choice input remains the fallback. Sensitive clipboard values and inputs are redacted in the drill report by default, but gate response files are local temporary JSON and can briefly contain raw input values until the drill consumes and cleans them up. Teardown hooks run after built-in drill phases and app process cleanup, including failure paths, and their stdout/stderr, exit code, duration, timeout flag, cwd, command, and args are captured in the redacted drill report. If a teardown hook fails, later teardown hooks marked "always": true still run so cleanup can continue.

{
  "setup": [
    {
      "name": "Seed data",
      "run": "npm",
      "args": ["run", "seed"],
      "timeoutMs": 30000,
      "cwd": "."
    }
  ],
  "gates": [
    {
      "name": "Approve GitHub sign-in",
      "instructions": "Complete the GitHub device-code approval in the app or browser, then return here.",
      "selector": "#status-card",
      "expectText": "Signed in",
      "timeoutMs": 300000,
      "manualContinue": true,
      "clipboard": {
        "label": "Device code",
        "value": "ABCD-1234",
        "sensitive": true,
        "copy": "attempt"
      },
      "choices": [
        { "id": "done", "label": "Done", "outcome": "continue" },
        { "id": "retry", "label": "Retry approval", "outcome": "retry" },
        { "id": "blocked", "label": "Blocked by SSO or consent", "outcome": "fail" },
        { "id": "abort", "label": "Abort drill", "outcome": "abort" }
      ],
      "inputs": [
        {
          "id": "external-error",
          "label": "External browser or provider error",
          "kind": "multilineText",
          "required": false,
          "sensitive": true
        }
      ]
    }
  ],
  "teardown": [
    {
      "name": "Clean data",
      "run": "npm",
      "args": ["run", "cleanup"],
      "timeoutMs": 30000,
      "cwd": ".",
      "always": true
    }
  ]
}

Malformed script/config exits 2. A setup hook failure exits 1, hook timeouts and human gate timeouts exit 4 unless an earlier stronger failure already occurred, and a teardown cleanup failure after an otherwise passing drill exits 5; if app/readiness/check phases already failed, that original exit code is preserved and the teardown failure is still included in the report.

drive is an optional app-driver layer, not part of the read-only observability core: it resolves an observed app session, prints PID/service/session/database attach info, records the platform drive backend, reports the in-app bridge status, and records the telemetry attributes driver actions must emit. In dogfood/dev environments with many historical sessions, use --session-id, --instance-id, --pid, --latest, or --active to disambiguate; ambiguity errors include top matching sessions and concrete selectors. Drive parent flags are global, so options such as --json and --app may appear before or after the subcommand. drive inspect reports the Tauri-native driver as selectorBackend=tauri_in_app_driver and exposes the session-proven bridge target as targetId=auditaur-bridge when the frontend explicitly enabled driveBridge. Legacy browser-debug flags are accepted only for compatibility and are ignored by drive actions.

Driver actions use a stable JSON envelope with action, selector, visibleOnly, serviceName, sessionId, targetId, windowLabel, targetBindingStatus, targetOwnershipStatus, ownershipProven, mutatesApp, payload, optional testId/stepId, and telemetryAttributes keys for future correlation (auditaur.test_id, auditaur.step_id, auditaur.driver.action, auditaur.driver.selector, auditaur.driver.visible_only, target id, target binding/ownership status, ownership proof flag, window label, trace id, and span id). exists, text, snapshot, and screenshot are diagnostic/read-style actions; screenshot --snapshot-output <path> is explicit opt-in failure artifact mode and writes a bounded JSON page snapshot/manifest alongside the PNG for failure handoffs. Bridge screenshots first try native WebView capture (screenshotBackend=tauri_native_webview_snapshot) for occlusion-free WebView pixels; selector screenshots crop that WebView image and include screenshotScope=selector plus selectorRect. If WebView capture fails, Auditaur falls back to native window capture (screenshotBackend=tauri_native_window_xcap) and then to the DOM text summary PNG (screenshotBackend=bridge_dom_summary_canvas) with error metadata. The snapshot clips page text and HTML fields to 65,536 characters each, may include sensitive DOM content or URLs, and should be reviewed before sharing. click, fill, type, press, hover, select, check, uncheck, and evaluate are mutating actions because they can dispatch DOM events or run arbitrary JavaScript. The in-app bridge target is session-directory proven and reports targetId=auditaur-bridge. The older --allow-probable-target and --allow-unproven-target flags are accepted as hidden compatibility aliases. Use --visible-only (or --visible) with selector actions when overlay/focus-mode DOM leaves hidden duplicate controls behind; visible filtering ignores hidden, inert, aria-hidden, and non-rendered matches. fill remains the fast DOM setter; it uses the native input/textarea value setter when available and dispatches input/change. Use type when framework-controlled text inputs need text insertion after focus, such as React textareas or autocomplete flows. press dispatches synthetic keydown/keyup events against the selector or active element. hover dispatches pointer/mouse events, select accepts one or more --value options, check and uncheck target checkbox/radio inputs, and evaluate returns a serializable JavaScript value. Bridge actions emit frontend action telemetry with auditaur.driver.backend=bridge; they are useful for smoke tests and CutReady-style validation, but they are still an in-WebView DOM driver rather than a browser engine replacement.

Enable initAuditaur({ driveBridge: true }) in development/test builds so drive commands can use the Tauri-native bridge; drive inspect reports bridge.status=active when the frontend bridge is available. The bridge is intentionally single-window for now: enable it in exactly one WebView per Auditaur session, usually with windowLabel: 'main'. If multiple windows enable it in the same session, target selection is unsupported and may be ambiguous. Staleness is heartbeat-only today; platform-specific PID existence checks are not implemented yet. doctor --db validates a specific SQLite database; doctor without --db validates discovery files and readable database paths. doctor tauri checks a Tauri app for the Auditaur crate, plugin registration, and required capability permission.