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
auditaur init diagnostics

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. init diagnostics writes optional versioned .auditaur\diagnostics.json and .auditaur\diagnostics.md files with generic failure-signal and checkpoint guidance; use --dry-run before writing or --force to overwrite. 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 diagnose --session-file .auditaur\session.json --json
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.

Focus evidence around one generic anchor

auditaur timeline --session-file .auditaur\session.json --anchor error:latest --window 10s --json
auditaur related --session-file .auditaur\session.json --anchor ipc:<command> --anchor-window 10s --json
auditaur explain --session-file .auditaur\session.json --anchor trace:<traceId>

Anchors keep the product generic: use trace:<id>, ipc:<command-or-latest>, error:latest, event:<name>, checkpoint:<name>, or time:<rfc3339-or-unix-nanos> instead of adding app-specific lenses. error:latest resolves to the latest generic failure signal, such as a frontend error, failed IPC call, failed span, or error-level log.

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 --json watch --until-ready

Use attach mode when the developer owns the app process. Default readiness means the Auditaur session, telemetry database, window records, and backend/plugin telemetry are ready. Add --require-frontend only when frontend telemetry is required; Tauri WebViews may not emit frontend telemetry until a user interaction or app code path runs. Add --require-drive-bridge when selector actions must be available before the run is considered ready.

Observe a dev app with no Auditaur config

auditaur observe --app my-tauri-app -- npm run tauri dev

Use observe when an agent or script owns startup but the app repo does not have .auditaur\config.json. It starts the normal dev command as argv, so package-manager and tool shims such as npm, pnpm, yarn, and cargo tauri do not need manual PowerShell/bash wrapping unless you want shell syntax. observe ignores matching sessions that existed before spawn, waits for the newly started Auditaur session, writes .auditaur\session.json by default, and prints pinned follow-up commands for status, tail/logs, drive inspection when available, and stop. Prefer --session-file .auditaur\session.json for read commands over --active, --latest, or copied --db/--session selectors in later automation.

When multiple apps or agents may start dev servers concurrently, reserve named ports and pass them through placeholders or environment variables:

auditaur observe --app my-tauri-app --port web -- npm run dev -- --port {{port:web}}
auditaur observe --app my-tauri-app --port-env web=VITE_PORT -- npm run tauri dev
auditaur observe --app my-tauri-app --port web=5177 -- npm run dev -- --port {{port:web}}

--port web chooses an available random local port and records it in .auditaur\session.json under ports.web. --port-env web=VITE_PORT also exports the chosen value to the child command. Use --port web=5177 only when a specific port is required and should fail fast if it is already taken. The app’s Vite/Tauri setup must consume the placeholder or environment variable; Auditaur cannot change a hard-coded dev server port by itself.

For stricter frontend readiness:

auditaur observe --app my-tauri-app --require-frontend -- npm run tauri dev

--require-frontend may wait until a WebView action emits frontend logs, errors, IPC, events, or spans.

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.

Live-tail only failure signals

auditaur tail --session-file .auditaur\session.json --signal failures --replay

--signal failures is opt-in and filters the normal timeline stream to frontend errors, failed IPC calls, failed spans, and error logs.

Failure timelines may include raw application log lines. Auditaur redacts known structured telemetry fields and bundles, but diagnostics config cannot retroactively sanitize provider frames, prompts, transcripts, URLs with secrets, or user content that an app already logged. Redact sensitive values before logging them.

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.