From c92f7e2dc3c5a217f03f1e7f84829abb777adee4 Mon Sep 17 00:00:00 2001 From: Sagnik Ghosh Date: Tue, 18 Aug 2026 01:20:30 +0530 Subject: [PATCH] Document the `autter doctor` setup validation command The CLI gained `autter doctor` (autter-cli #51): end-to-end setup validation with a fix line per failed check, exit code 1 on failure, and a `--json` report. Update the docs to make it the first diagnostic step: - Troubleshooting: lead with `autter doctor` and describe what it checks; keep `autter debug` as the full support report to share - Command reference: add the doctor row, clarify the debug row - Install: verify the installation with doctor instead of debug - Performance FAQs and agent pages (Cursor, GitHub Copilot, Windsurf): point setup verification at doctor Generated-By: PostHog Desktop Task-Id: c84ac9ce-31cc-4e70-8451-62857be00f1c --- cli/command-reference.mdx | 3 ++- cli/copilot.mdx | 2 +- cli/cursor.mdx | 2 +- cli/install.mdx | 4 ++-- cli/performance-faqs.mdx | 4 ++-- cli/troubleshooting.mdx | 24 +++++++++++++++++++++--- cli/windsurf.mdx | 4 ++-- 7 files changed, 31 insertions(+), 12 deletions(-) diff --git a/cli/command-reference.mdx b/cli/command-reference.mdx index a1b17b5..c0dbce5 100644 --- a/cli/command-reference.mdx +++ b/cli/command-reference.mdx @@ -42,7 +42,8 @@ Run `autter help` for the command list installed on your machine. | `autter config set ` | Set a value | | `autter config --add ` | Add an array item or object entry | | `autter config unset ` | Remove a value and restore its default | -| `autter debug` | Print support diagnostics | +| `autter doctor [--json]` | Validate the setup end-to-end; exits non-zero when a check fails | +| `autter debug` | Print the full support diagnostics report | | `autter bg status` | Check the background service | | `autter bg restart` | Restart the background service | | `autter bg tail -f` | Follow background-service logs | diff --git a/cli/copilot.mdx b/cli/copilot.mdx index e17c6e9..acd169b 100644 --- a/cli/copilot.mdx +++ b/cli/copilot.mdx @@ -37,7 +37,7 @@ Autter works with GitHub Copilot by recording the edits Copilot makes and attach ## After installation ```bash -autter debug +autter doctor autter stats HEAD autter blame src/services/review.ts ``` diff --git a/cli/cursor.mdx b/cli/cursor.mdx index cd981ac..24c0923 100644 --- a/cli/cursor.mdx +++ b/cli/cursor.mdx @@ -37,7 +37,7 @@ Autter works with Cursor by recording checkpoints around the edits Cursor makes ## Verify the result ```bash -autter debug +autter doctor autter status autter stats HEAD ``` diff --git a/cli/install.mdx b/cli/install.mdx index 95f04be..3a1c322 100644 --- a/cli/install.mdx +++ b/cli/install.mdx @@ -93,12 +93,12 @@ The installer asks whether you want local-only or connected mode. ```bash autter --version -autter debug +autter doctor autter whoami ``` - `autter --version` prints the installed version. -- `autter debug` checks the installation and integrations. +- `autter doctor` validates the installation end-to-end, including a test checkpoint, and prints a fix for every failed check. - `autter whoami` shows whether the CLI is connected. ## Verify an agent integration diff --git a/cli/performance-faqs.mdx b/cli/performance-faqs.mdx index d11368f..1dd9ef0 100644 --- a/cli/performance-faqs.mdx +++ b/cli/performance-faqs.mdx @@ -15,7 +15,7 @@ If something feels slow, check the specific command first: - `autter status` inspects the current working tree - `autter stats` walks commit history for the range you give it - `autter blame` reads attribution for one file -- `autter debug` checks the installation and integrations +- `autter doctor` runs end-to-end setup checks, so a few seconds is expected ## What runs locally @@ -55,7 +55,7 @@ Use narrower ranges and specific files when you can. That gives you the same ans If Autter feels unusually slow, run: ```bash -autter debug +autter doctor autter bg status ``` diff --git a/cli/troubleshooting.mdx b/cli/troubleshooting.mdx index 5a3ad98..3050413 100644 --- a/cli/troubleshooting.mdx +++ b/cli/troubleshooting.mdx @@ -4,10 +4,28 @@ description: "Diagnose missing attribution, background-service issues, login fai icon: "wrench" --- -Start with Autter's built-in diagnostics: +Start with Autter's built-in setup validation: + +```bash +autter doctor +``` + +## Validate the setup with `autter doctor` + +`autter doctor` checks the installation end-to-end and prints a fix line for every failed check. It verifies: + +- The Git version and the Autter configuration file +- The repository filters that decide whether the current repository is tracked +- The background service and its Git event capture +- A real checkpoint round-trip, from checkpoint through commit to line-level attribution +- Integration status for the coding agents detected on the machine +- Login state, plus platform reachability in connected mode + +The command exits `0` when no check fails and `1` otherwise, so you can use it in scripts. Add `--json` for a machine-readable report. + +If every check passes but something still looks wrong, gather more context: ```bash -autter debug autter bg status autter whoami autter config @@ -101,7 +119,7 @@ autter config set telemetry_oss off ## Get support diagnostics -Run `autter debug` and review the output before sharing it. Remove repository paths, identities, tokens, and other sensitive values. +Run `autter doctor` first and apply the fixes it prints. When you need a full report to share, run `autter debug` and review the output before sharing it. Remove repository paths, identities, tokens, and other sensitive values. Report reproducible open source CLI problems. diff --git a/cli/windsurf.mdx b/cli/windsurf.mdx index 6aa29ae..e8c46b7 100644 --- a/cli/windsurf.mdx +++ b/cli/windsurf.mdx @@ -11,7 +11,7 @@ Autter works with Windsurf by capturing the agent's edits as checkpoints and wri - Automatic authorship tracking for Windsurf edits - `autter blame` for file-level review - `autter stats` for commit and range summaries -- `autter debug` when you need setup diagnostics +- `autter doctor` when you need setup validation ## Set up Windsurf @@ -37,7 +37,7 @@ Autter works with Windsurf by capturing the agent's edits as checkpoints and wri ## Verify the flow ```bash -autter debug +autter doctor autter stats HEAD autter blame src/service.ts ```