CLI Recipes

These recipes assume exactly one active readable Auditaur session. If commands report ambiguity, copy databasePath from auditaur apps --json and add --db "<databasePath>".

Simplest agent loop

With .auditaur\config.json checked into the app repo, agents can use one session file and four commands:

auditaur start
auditaur drill
auditaur inspect
auditaur stop

Use auditaur drill <name> when the config defines multiple drills. start writes .auditaur\session.json; drill, inspect, and stop read it so agents do not need custom wrappers for readiness polling, session IDs, database paths, or process cleanup.

Scaffold agent helpers in a consuming repo

auditaur init skill
auditaur init extension

init skill installs the Auditaur debugging workflow for agents. init extension installs the Copilot canvas extension that can render drill human gates as action cards. Use --path <repo-root> to target another repository.

Inspect the latest active app

auditaur apps --json
auditaur health --json
auditaur sessions --json

Use this before deeper debugging. apps tells you what Auditaur discovered; health summarizes database readability, schema validity, heartbeat state, churn, and capability skew.

Triage a fresh failure

auditaur errors --json
auditaur exceptions --json
auditaur traces --failed --json
auditaur ipc --failed --json
auditaur events --json

Start with grouped exceptions and failed IPC. Move to traces when you need causality.

Explain one failing trace

auditaur trace <traceId> --json
auditaur timeline --trace <traceId> --json
auditaur explain --trace <traceId>

Use trace for structured detail, timeline for chronological context, and explain for obvious failure findings.

Watch readiness while a developer starts the app

npm run tauri dev
auditaur debug --app my-tauri-app --active --require-frontend --json watch --until-ready

Use attach mode when the developer owns the app process. Add --require-drive-bridge when selector actions must be available before the run is considered ready.

Start the app under observation

auditaur debug --app my-tauri-app --require-frontend --require-drive-bridge --json run --timeout-seconds 180 --write-session .auditaur\session.json -- npm run tauri dev

Use wrapper mode when an agent or script owns startup but should leave the app running after readiness for inspection. With --app, debug run ignores matching sessions that existed before spawn, waits for the newly started Auditaur session, and writes .auditaur\session.json with exact sessionId, instanceId, pid, databasePath, and selector arguments for follow-up commands. Prefer those exact selectors over --active or --latest in later automation.

Run a pass/fail confidence drill

auditaur drill run --app my-tauri-app --require-drive-bridge --selector "#ready" --expect-text "Ready" -- npm run tauri dev

Use drill mode when Auditaur should start the app, wait for a fresh session, check readiness, optionally drive one selector/text assertion, write a report, and clean up the app process tree.

Pause for a human approval inside a drill

auditaur drill run --app my-tauri-app --require-drive-bridge --script .auditaur\drills\github-login.json -- npm run tauri dev

Use a human gate when the flow requires OAuth consent, OS permissions, elevation, browser handoff, or hardware-key approval. The gate runs after Auditaur pins the spawned app session and before final evidence collection, so the report stays tied to one session. A tester can answer in the terminal, through list_pending_human_gates/respond_human_gate over MCP, or through the auditaur-human-gate canvas installed by auditaur init extension.

Verify the Tauri-native drive bridge

auditaur debug --app my-tauri-app --active --require-drive-bridge --json watch --until-ready
auditaur drive --app my-tauri-app --active --json inspect
auditaur drive --app my-tauri-app --active --json exists --selector "#ready" --visible-only
auditaur drive --app my-tauri-app --active --json screenshot --selector "#ready" --output ready.png

Use read-style actions before mutating the UI. Selector screenshots first try native WebView capture and crop the selected element when possible.

Produce a GitHub issue draft

auditaur exceptions --json
auditaur exceptions --fingerprint <id> --markdown --output issue.md

Review and redact the generated Markdown before posting it outside the machine.

Produce a bounded handoff bundle

auditaur bundle --redacted --output auditaur-bundle.json

Bundles are intended for bug reports and agent handoffs. They are bounded and redacted, but you should still review local telemetry before sharing.

Query through MCP

auditaur mcp

Use MCP when an agent can call tools directly. Use the CLI for quick local checks, scripts, and shell-friendly JSON.