feat: add doctor command for project health checks#21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rafa-thayto merged 9 commits into from
Mar 11, 2026
Merged

feat: add doctor command for project health checks #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
da41695
feat(color): add red color utility export
rafa-thayto Mar 10, 2026
cc4113c
feat(doctor): add doctor command for project health checks
rafa-thayto Mar 10, 2026
aad17a3
feat(cli): register doctor command
rafa-thayto Mar 10, 2026
7666de8
docs: add doctor command to CLI help output
rafa-thayto Mar 10, 2026
a2aa71f
refactor(doctor): remove git availability check
rafa-thayto Mar 10, 2026
4cac338
refactor(doctor): DRY check functions with defineCheck builder and im…
rafa-thayto Mar 11, 2026
29b6c0d
fix: align doctor command with centralized error handling patterns
rafa-thayto Mar 11, 2026
e939180
refactor(doctor): improve check names and messages for clarity
rafa-thayto Mar 11, 2026
1d72531
fix(doctor): restore Instance IDs prefix in check messages
rafa-thayto Mar 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -31,6 +31,7 @@ Commands:
api [options] [endpoint] [filter] Make authenticated requests to the Clerk API
ls [filter] List available API endpoints
(no args) Interactive request builder (TTY only)
doctor [options] Check your project's Clerk integration health
deploy [options] Deploy your Clerk application (hidden)

clerk init
Expand DownExpand Up@@ -83,6 +84,12 @@ clerk api [endpoint] [filter]
clerk api ls [filter] List available API endpoints
clerk api Interactive request builder (TTY only)

clerk doctor
--verbose Show detailed output for each check
--json Output results as JSON
--spotlight Only show warnings and failures
--fix Attempt to auto-fix issues

clerk deploy
--debug Show debug output
```
Expand Down
17 changes: 16 additions & 1 deletion src/cli.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,7 @@ import { configSchema } from "./commands/config/schema.js";
import { api } from "./commands/api/index.js";
import { link } from "./commands/link/index.js";
import { unlink } from "./commands/unlink/index.js";
import { doctor } from "./commands/doctor/index.js";
import { CliError, UserAbortError, ApiError, EXIT_CODE, throwUsageError } from "./lib/errors.js";
import { red } from "./lib/color.js";

Expand DownExpand Up@@ -42,7 +43,12 @@ program.command("init").description("Initialize Clerk in your project").action(i

const auth = program.command("auth").description("Manage authentication");

auth.command("login").description("Log in to your Clerk account").action(login);
auth
.command("login")
.description("Log in to your Clerk account")
.action(async () => {
await login();
});

auth.command("logout").description("Log out of your Clerk account").action(logout);

Expand DownExpand Up@@ -122,6 +128,15 @@ program
.option("--yes", "Skip confirmation for mutating requests")
.action(api);

program
.command("doctor")
.description("Check your project's Clerk integration health")
.option("--verbose", "Show detailed output for each check")
.option("--json", "Output results as JSON")
.option("--spotlight", "Only show warnings and failures")
.option("--fix", "Attempt to auto-fix issues")
.action(doctor);

program
.command("deploy", { hidden: true })
.description("Deploy your Clerk application")
Expand Down
93 changes: 93 additions & 0 deletions src/commands/doctor/README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
# Doctor Command

Runs a series of diagnostic checks on your Clerk CLI setup and reports
the status of each check. The command is read-only and never modifies
any state (unless `--fix` is used).

## Usage

```sh
clerk doctor # Run all checks
clerk doctor --verbose # Show detailed output
clerk doctor --json # Output results as JSON
clerk doctor --spotlight # Only show warnings and failures
clerk doctor --fix # Offer to auto-fix issues
```

## Options

| Flag | Description |
| ------------- | ----------------------------------------------------- |
| `--verbose` | Show detailed diagnostic info for each check |
| `--json` | Output results as machine-readable JSON |
| `--spotlight` | Only show warnings and failures (hide passing checks) |
| `--fix` | Offer to auto-fix issues with known remedies |

## Checks

| Check | Category | What it verifies |
| --------------------- | -------------- | ------------------------------------------------------------------ |
| Authentication token | Authentication | Credential store has a stored token |
| Token validity | Authentication | Token is still valid (calls `/oauth/userinfo`) |
| Project linkage | Project | Current directory is linked to a Clerk app |

@dmoernerdmoernerMar 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still find "Linked application" and "Project linkage" a little confusing. The definition of "Project linkage" doesn't use the term "project" but just uses "Clerk app".

@rafa-thaytorafa-thaytoMar 11, 2026

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let me think better on this

do you have any name suggestions?

| Linked application | Project | Linked application ID is accessible via the API |
| Instances | Project | Configured dev/prod instance IDs match the application's instances |
| Environment variables | Environment | .env.local or .env has Clerk keys |
| CLI configuration | Configuration | ~/.clerk/config.json exists and parses |

## Auto-Fix (`--fix`)

When `--fix` is passed in human mode, the command prompts to fix each
issue after all checks complete. After applying fixes, all checks are
re-run to verify the results.

`--fix` only works in human mode because the underlying fix actions are
interactive (`clerk auth login` opens a browser, `clerk link` shows a
picker). It is ignored in `--json` mode and agent mode.

Fixable issues:

| Issue | Fix action |
| ---------------------------------- | ----------------------------------- |
| Not logged in / expired token | Log in with `clerk auth login` |
| Not linked to an app / stale app | Link project with `clerk link` |
| Missing environment variables | Pull env vars with `clerk env pull` |
| Missing or corrupt CLI config file | Log in with `clerk auth login` |

Duplicate fix actions (e.g., multiple checks suggesting `clerk auth login`)
are deduplicated.

## Agent / CI Usage

AI agents and CI pipelines should use `--json` to get structured output:

```sh
clerk doctor --json # Diagnose, output JSON
clerk doctor --json --spotlight # JSON with only warnings/errors
```

Each result includes `name`, `status` (`pass` / `warn` / `fail`),
`message`, and optionally `detail` (extra diagnostic info), `remedy`
(a human-readable fix instruction), and `fix` (a label describing
the auto-fix action).

Agents cannot use `--fix` directly because the fix actions are interactive.
Instead, agents should read the `remedy` field from the JSON output and
orchestrate fixes themselves (e.g., ask the user to run `clerk auth login`,
or call `clerk link --app <id>` with a known app ID).

Exit code 1 signals one or more checks failed.

## Exit Codes

| Code | Meaning |
| ---- | ---------------------------------------- |
| 0 | All checks passed (warnings are allowed) |
| 1 | One or more checks failed |

## API Endpoints

| Method | Endpoint | Description |
| ------ | ----------------------------------- | ----------------------------------------------- |
| `GET` | `/oauth/userinfo` | Validates the stored auth token |
| `GET` | `/v1/platform/applications/{appId}` | Verifies the linked app and its instances exist |
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
feat: add doctor command for project health checks#21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

rafa-thayto
merged 9 commits into

from

Mar 11, 2026
 Merged


feat: add doctor command for project health checks
#21
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


9 commits


Select commit
Hold shift + click to select a range
da41695

feat(color): add red color utility export


rafa-thayto Mar 10, 2026
cc4113c

feat(doctor): add doctor command for project health checks


rafa-thayto Mar 10, 2026
aad17a3

feat(cli): register doctor command


rafa-thayto Mar 10, 2026
7666de8

docs: add doctor command to CLI help output


rafa-thayto Mar 10, 2026
a2aa71f

refactor(doctor): remove git availability check


rafa-thayto Mar 10, 2026
4cac338

refactor(doctor): DRY check functions with defineCheck builder and im…


rafa-thayto Mar 11, 2026
29b6c0d

fix: align doctor command with centralized error handling patterns


rafa-thayto Mar 11, 2026
e939180

refactor(doctor): improve check names and messages for clarity


rafa-thayto Mar 11, 2026
1d72531

fix(doctor): restore Instance IDs prefix in check messages


rafa-thayto Mar 11, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


7 changes: 7 additions & 0 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -31,6 +31,7 @@ Commands:
 api [options] [endpoint] [filter] Make authenticated requests to the Clerk API
 ls [filter] List available API endpoints
 (no args) Interactive request builder (TTY only)
 doctor [options] Check your project's Clerk integration health
 deploy [options] Deploy your Clerk application (hidden)

clerk init
Expand DownExpand Up@@ -83,6 +84,12 @@ clerk api [endpoint] [filter]
clerk api ls [filter] List available API endpoints
clerk api Interactive request builder (TTY only)

clerk doctor
 --verbose Show detailed output for each check
 --json Output results as JSON
 --spotlight Only show warnings and failures
 --fix Attempt to auto-fix issues

clerk deploy
 --debug Show debug output
```
Expand Down

17 changes: 16 additions & 1 deletion
src/cli.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,7 @@ import { configSchema } from "./commands/config/schema.js";
import { api } from "./commands/api/index.js";
import { link } from "./commands/link/index.js";
import { unlink } from "./commands/unlink/index.js";
import { doctor } from "./commands/doctor/index.js";
import { CliError, UserAbortError, ApiError, EXIT_CODE, throwUsageError } from "./lib/errors.js";
import { red } from "./lib/color.js";

Expand DownExpand Up@@ -42,7 +43,12 @@ program.command("init").description("Initialize Clerk in your project").action(i

const auth = program.command("auth").description("Manage authentication");

auth.command("login").description("Log in to your Clerk account").action(login);
auth
 .command("login")
 .description("Log in to your Clerk account")
 .action(async () => {
 await login();
 });

auth.command("logout").description("Log out of your Clerk account").action(logout);

Expand DownExpand Up@@ -122,6 +128,15 @@ program
 .option("--yes", "Skip confirmation for mutating requests")
 .action(api);

program
 .command("doctor")
 .description("Check your project's Clerk integration health")
 .option("--verbose", "Show detailed output for each check")
 .option("--json", "Output results as JSON")
 .option("--spotlight", "Only show warnings and failures")
 .option("--fix", "Attempt to auto-fix issues")
 .action(doctor);

program
 .command("deploy", { hidden: true })
 .description("Deploy your Clerk application")
Expand Down

93 changes: 93 additions & 0 deletions
src/commands/doctor/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
# Doctor Command

Runs a series of diagnostic checks on your Clerk CLI setup and reports
the status of each check. The command is read-only and never modifies
any state (unless `--fix` is used).

## Usage

```sh
clerk doctor # Run all checks
clerk doctor --verbose # Show detailed output
clerk doctor --json # Output results as JSON
clerk doctor --spotlight # Only show warnings and failures
clerk doctor --fix # Offer to auto-fix issues
```

## Options

| Flag | Description |
| ------------- | ----------------------------------------------------- |
| `--verbose` | Show detailed diagnostic info for each check |
| `--json` | Output results as machine-readable JSON |
| `--spotlight` | Only show warnings and failures (hide passing checks) |
| `--fix` | Offer to auto-fix issues with known remedies |

## Checks

| Check | Category | What it verifies |
| --------------------- | -------------- | ------------------------------------------------------------------ |
| Authentication token | Authentication | Credential store has a stored token |
| Token validity | Authentication | Token is still valid (calls `/oauth/userinfo`) |
| Project linkage | Project | Current directory is linked to a Clerk app |
@dmoernerdmoernerMar 11, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still find "Linked application" and "Project linkage" a little confusing. The definition of "Project linkage" doesn't use the term "project" but just uses "Clerk app".
@rafa-thaytorafa-thaytoMar 11, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let me think better on this
do you have any name suggestions?
| Linked application | Project | Linked application ID is accessible via the API |
| Instances | Project | Configured dev/prod instance IDs match the application's instances |
| Environment variables | Environment | .env.local or .env has Clerk keys |
| CLI configuration | Configuration | ~/.clerk/config.json exists and parses |

## Auto-Fix (`--fix`)

When `--fix` is passed in human mode, the command prompts to fix each
issue after all checks complete. After applying fixes, all checks are
re-run to verify the results.

`--fix` only works in human mode because the underlying fix actions are
interactive (`clerk auth login` opens a browser, `clerk link` shows a
picker). It is ignored in `--json` mode and agent mode.

Fixable issues:

| Issue | Fix action |
| ---------------------------------- | ----------------------------------- |
| Not logged in / expired token | Log in with `clerk auth login` |
| Not linked to an app / stale app | Link project with `clerk link` |
| Missing environment variables | Pull env vars with `clerk env pull` |
| Missing or corrupt CLI config file | Log in with `clerk auth login` |

Duplicate fix actions (e.g., multiple checks suggesting `clerk auth login`)
are deduplicated.

## Agent / CI Usage

AI agents and CI pipelines should use `--json` to get structured output:

```sh
clerk doctor --json # Diagnose, output JSON
clerk doctor --json --spotlight # JSON with only warnings/errors
```

Each result includes `name`, `status` (`pass` / `warn` / `fail`),
`message`, and optionally `detail` (extra diagnostic info), `remedy`
(a human-readable fix instruction), and `fix` (a label describing
the auto-fix action).

Agents cannot use `--fix` directly because the fix actions are interactive.
Instead, agents should read the `remedy` field from the JSON output and
orchestrate fixes themselves (e.g., ask the user to run `clerk auth login`,
or call `clerk link --app <id>` with a known app ID).

Exit code 1 signals one or more checks failed.

## Exit Codes

| Code | Meaning |
| ---- | ---------------------------------------- |
| 0 | All checks passed (warnings are allowed) |
| 1 | One or more checks failed |

## API Endpoints

| Method | Endpoint | Description |
| ------ | ----------------------------------- | ----------------------------------------------- |
| `GET` | `/oauth/userinfo` | Validates the stored auth token |
| `GET` | `/v1/platform/applications/{appId}` | Verifies the linked app and its instances exist |
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat: add doctor command for project health checks#21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

rafa-thayto
merged 9 commits into

from

Mar 11, 2026
 Merged


feat: add doctor command for project health checks
#21
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


9 commits


Select commit
Hold shift + click to select a range
da41695

feat(color): add red color utility export


rafa-thayto Mar 10, 2026
cc4113c

feat(doctor): add doctor command for project health checks


rafa-thayto Mar 10, 2026
aad17a3

feat(cli): register doctor command


rafa-thayto Mar 10, 2026
7666de8

docs: add doctor command to CLI help output


rafa-thayto Mar 10, 2026
a2aa71f

refactor(doctor): remove git availability check


rafa-thayto Mar 10, 2026
4cac338

refactor(doctor): DRY check functions with defineCheck builder and im…


rafa-thayto Mar 11, 2026
29b6c0d

fix: align doctor command with centralized error handling patterns


rafa-thayto Mar 11, 2026
e939180

refactor(doctor): improve check names and messages for clarity


rafa-thayto Mar 11, 2026
1d72531

fix(doctor): restore Instance IDs prefix in check messages


rafa-thayto Mar 11, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


7 changes: 7 additions & 0 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -31,6 +31,7 @@ Commands:
 api [options] [endpoint] [filter] Make authenticated requests to the Clerk API
 ls [filter] List available API endpoints
 (no args) Interactive request builder (TTY only)
 doctor [options] Check your project's Clerk integration health
 deploy [options] Deploy your Clerk application (hidden)

clerk init
Expand DownExpand Up@@ -83,6 +84,12 @@ clerk api [endpoint] [filter]
clerk api ls [filter] List available API endpoints
clerk api Interactive request builder (TTY only)

clerk doctor
 --verbose Show detailed output for each check
 --json Output results as JSON
 --spotlight Only show warnings and failures
 --fix Attempt to auto-fix issues

clerk deploy
 --debug Show debug output
```
Expand Down

17 changes: 16 additions & 1 deletion
src/cli.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,7 @@ import { configSchema } from "./commands/config/schema.js";
import { api } from "./commands/api/index.js";
import { link } from "./commands/link/index.js";
import { unlink } from "./commands/unlink/index.js";
import { doctor } from "./commands/doctor/index.js";
import { CliError, UserAbortError, ApiError, EXIT_CODE, throwUsageError } from "./lib/errors.js";
import { red } from "./lib/color.js";

Expand DownExpand Up@@ -42,7 +43,12 @@ program.command("init").description("Initialize Clerk in your project").action(i

const auth = program.command("auth").description("Manage authentication");

auth.command("login").description("Log in to your Clerk account").action(login);
auth
 .command("login")
 .description("Log in to your Clerk account")
 .action(async () => {
 await login();
 });

auth.command("logout").description("Log out of your Clerk account").action(logout);

Expand DownExpand Up@@ -122,6 +128,15 @@ program
 .option("--yes", "Skip confirmation for mutating requests")
 .action(api);

program
 .command("doctor")
 .description("Check your project's Clerk integration health")
 .option("--verbose", "Show detailed output for each check")
 .option("--json", "Output results as JSON")
 .option("--spotlight", "Only show warnings and failures")
 .option("--fix", "Attempt to auto-fix issues")
 .action(doctor);

program
 .command("deploy", { hidden: true })
 .description("Deploy your Clerk application")
Expand Down

93 changes: 93 additions & 0 deletions
src/commands/doctor/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
# Doctor Command

Runs a series of diagnostic checks on your Clerk CLI setup and reports
the status of each check. The command is read-only and never modifies
any state (unless `--fix` is used).

## Usage

```sh
clerk doctor # Run all checks
clerk doctor --verbose # Show detailed output
clerk doctor --json # Output results as JSON
clerk doctor --spotlight # Only show warnings and failures
clerk doctor --fix # Offer to auto-fix issues
```

## Options

| Flag | Description |
| ------------- | ----------------------------------------------------- |
| `--verbose` | Show detailed diagnostic info for each check |
| `--json` | Output results as machine-readable JSON |
| `--spotlight` | Only show warnings and failures (hide passing checks) |
| `--fix` | Offer to auto-fix issues with known remedies |

## Checks

| Check | Category | What it verifies |
| --------------------- | -------------- | ------------------------------------------------------------------ |
| Authentication token | Authentication | Credential store has a stored token |
| Token validity | Authentication | Token is still valid (calls `/oauth/userinfo`) |
| Project linkage | Project | Current directory is linked to a Clerk app |
@dmoernerdmoernerMar 11, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still find "Linked application" and "Project linkage" a little confusing. The definition of "Project linkage" doesn't use the term "project" but just uses "Clerk app".
@rafa-thaytorafa-thaytoMar 11, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let me think better on this
do you have any name suggestions?
| Linked application | Project | Linked application ID is accessible via the API |
| Instances | Project | Configured dev/prod instance IDs match the application's instances |
| Environment variables | Environment | .env.local or .env has Clerk keys |
| CLI configuration | Configuration | ~/.clerk/config.json exists and parses |

## Auto-Fix (`--fix`)

When `--fix` is passed in human mode, the command prompts to fix each
issue after all checks complete. After applying fixes, all checks are
re-run to verify the results.

`--fix` only works in human mode because the underlying fix actions are
interactive (`clerk auth login` opens a browser, `clerk link` shows a
picker). It is ignored in `--json` mode and agent mode.

Fixable issues:

| Issue | Fix action |
| ---------------------------------- | ----------------------------------- |
| Not logged in / expired token | Log in with `clerk auth login` |
| Not linked to an app / stale app | Link project with `clerk link` |
| Missing environment variables | Pull env vars with `clerk env pull` |
| Missing or corrupt CLI config file | Log in with `clerk auth login` |

Duplicate fix actions (e.g., multiple checks suggesting `clerk auth login`)
are deduplicated.

## Agent / CI Usage

AI agents and CI pipelines should use `--json` to get structured output:

```sh
clerk doctor --json # Diagnose, output JSON
clerk doctor --json --spotlight # JSON with only warnings/errors
```

Each result includes `name`, `status` (`pass` / `warn` / `fail`),
`message`, and optionally `detail` (extra diagnostic info), `remedy`
(a human-readable fix instruction), and `fix` (a label describing
the auto-fix action).

Agents cannot use `--fix` directly because the fix actions are interactive.
Instead, agents should read the `remedy` field from the JSON output and
orchestrate fixes themselves (e.g., ask the user to run `clerk auth login`,
or call `clerk link --app <id>` with a known app ID).

Exit code 1 signals one or more checks failed.

## Exit Codes

| Code | Meaning |
| ---- | ---------------------------------------- |
| 0 | All checks passed (warnings are allowed) |
| 1 | One or more checks failed |

## API Endpoints

| Method | Endpoint | Description |
| ------ | ----------------------------------- | ----------------------------------------------- |
| `GET` | `/oauth/userinfo` | Validates the stored auth token |
| `GET` | `/v1/platform/applications/{appId}` | Verifies the linked app and its instances exist |
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat: add doctor command for project health checks#21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

rafa-thayto
merged 9 commits into

from

Mar 11, 2026
 Merged


feat: add doctor command for project health checks
#21
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


9 commits


Select commit
Hold shift + click to select a range
da41695

feat(color): add red color utility export


rafa-thayto Mar 10, 2026
cc4113c

feat(doctor): add doctor command for project health checks


rafa-thayto Mar 10, 2026
aad17a3

feat(cli): register doctor command


rafa-thayto Mar 10, 2026
7666de8

docs: add doctor command to CLI help output


rafa-thayto Mar 10, 2026
a2aa71f

refactor(doctor): remove git availability check


rafa-thayto Mar 10, 2026
4cac338

refactor(doctor): DRY check functions with defineCheck builder and im…


rafa-thayto Mar 11, 2026
29b6c0d

fix: align doctor command with centralized error handling patterns


rafa-thayto Mar 11, 2026
e939180

refactor(doctor): improve check names and messages for clarity


rafa-thayto Mar 11, 2026
1d72531

fix(doctor): restore Instance IDs prefix in check messages


rafa-thayto Mar 11, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


7 changes: 7 additions & 0 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -31,6 +31,7 @@ Commands:
 api [options] [endpoint] [filter] Make authenticated requests to the Clerk API
 ls [filter] List available API endpoints
 (no args) Interactive request builder (TTY only)
 doctor [options] Check your project's Clerk integration health
 deploy [options] Deploy your Clerk application (hidden)

clerk init
Expand DownExpand Up@@ -83,6 +84,12 @@ clerk api [endpoint] [filter]
clerk api ls [filter] List available API endpoints
clerk api Interactive request builder (TTY only)

clerk doctor
 --verbose Show detailed output for each check
 --json Output results as JSON
 --spotlight Only show warnings and failures
 --fix Attempt to auto-fix issues

clerk deploy
 --debug Show debug output
```
Expand Down

17 changes: 16 additions & 1 deletion
src/cli.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,7 @@ import { configSchema } from "./commands/config/schema.js";
import { api } from "./commands/api/index.js";
import { link } from "./commands/link/index.js";
import { unlink } from "./commands/unlink/index.js";
import { doctor } from "./commands/doctor/index.js";
import { CliError, UserAbortError, ApiError, EXIT_CODE, throwUsageError } from "./lib/errors.js";
import { red } from "./lib/color.js";

Expand DownExpand Up@@ -42,7 +43,12 @@ program.command("init").description("Initialize Clerk in your project").action(i

const auth = program.command("auth").description("Manage authentication");

auth.command("login").description("Log in to your Clerk account").action(login);
auth
 .command("login")
 .description("Log in to your Clerk account")
 .action(async () => {
 await login();
 });

auth.command("logout").description("Log out of your Clerk account").action(logout);

Expand DownExpand Up@@ -122,6 +128,15 @@ program
 .option("--yes", "Skip confirmation for mutating requests")
 .action(api);

program
 .command("doctor")
 .description("Check your project's Clerk integration health")
 .option("--verbose", "Show detailed output for each check")
 .option("--json", "Output results as JSON")
 .option("--spotlight", "Only show warnings and failures")
 .option("--fix", "Attempt to auto-fix issues")
 .action(doctor);

program
 .command("deploy", { hidden: true })
 .description("Deploy your Clerk application")
Expand Down

93 changes: 93 additions & 0 deletions
src/commands/doctor/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
# Doctor Command

Runs a series of diagnostic checks on your Clerk CLI setup and reports
the status of each check. The command is read-only and never modifies
any state (unless `--fix` is used).

## Usage

```sh
clerk doctor # Run all checks
clerk doctor --verbose # Show detailed output
clerk doctor --json # Output results as JSON
clerk doctor --spotlight # Only show warnings and failures
clerk doctor --fix # Offer to auto-fix issues
```

## Options

| Flag | Description |
| ------------- | ----------------------------------------------------- |
| `--verbose` | Show detailed diagnostic info for each check |
| `--json` | Output results as machine-readable JSON |
| `--spotlight` | Only show warnings and failures (hide passing checks) |
| `--fix` | Offer to auto-fix issues with known remedies |

## Checks

| Check | Category | What it verifies |
| --------------------- | -------------- | ------------------------------------------------------------------ |
| Authentication token | Authentication | Credential store has a stored token |
| Token validity | Authentication | Token is still valid (calls `/oauth/userinfo`) |
| Project linkage | Project | Current directory is linked to a Clerk app |
@dmoernerdmoernerMar 11, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still find "Linked application" and "Project linkage" a little confusing. The definition of "Project linkage" doesn't use the term "project" but just uses "Clerk app".
@rafa-thaytorafa-thaytoMar 11, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let me think better on this
do you have any name suggestions?
| Linked application | Project | Linked application ID is accessible via the API |
| Instances | Project | Configured dev/prod instance IDs match the application's instances |
| Environment variables | Environment | .env.local or .env has Clerk keys |
| CLI configuration | Configuration | ~/.clerk/config.json exists and parses |

## Auto-Fix (`--fix`)

When `--fix` is passed in human mode, the command prompts to fix each
issue after all checks complete. After applying fixes, all checks are
re-run to verify the results.

`--fix` only works in human mode because the underlying fix actions are
interactive (`clerk auth login` opens a browser, `clerk link` shows a
picker). It is ignored in `--json` mode and agent mode.

Fixable issues:

| Issue | Fix action |
| ---------------------------------- | ----------------------------------- |
| Not logged in / expired token | Log in with `clerk auth login` |
| Not linked to an app / stale app | Link project with `clerk link` |
| Missing environment variables | Pull env vars with `clerk env pull` |
| Missing or corrupt CLI config file | Log in with `clerk auth login` |

Duplicate fix actions (e.g., multiple checks suggesting `clerk auth login`)
are deduplicated.

## Agent / CI Usage

AI agents and CI pipelines should use `--json` to get structured output:

```sh
clerk doctor --json # Diagnose, output JSON
clerk doctor --json --spotlight # JSON with only warnings/errors
```

Each result includes `name`, `status` (`pass` / `warn` / `fail`),
`message`, and optionally `detail` (extra diagnostic info), `remedy`
(a human-readable fix instruction), and `fix` (a label describing
the auto-fix action).

Agents cannot use `--fix` directly because the fix actions are interactive.
Instead, agents should read the `remedy` field from the JSON output and
orchestrate fixes themselves (e.g., ask the user to run `clerk auth login`,
or call `clerk link --app <id>` with a known app ID).

Exit code 1 signals one or more checks failed.

## Exit Codes

| Code | Meaning |
| ---- | ---------------------------------------- |
| 0 | All checks passed (warnings are allowed) |
| 1 | One or more checks failed |

## API Endpoints

| Method | Endpoint | Description |
| ------ | ----------------------------------- | ----------------------------------------------- |
| `GET` | `/oauth/userinfo` | Validates the stored auth token |
| `GET` | `/v1/platform/applications/{appId}` | Verifies the linked app and its instances exist |
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
feat: add doctor command for project health checks#21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

rafa-thayto
merged 9 commits into

from

Mar 11, 2026
 Merged


feat: add doctor command for project health checks
#21
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


9 commits


Select commit
Hold shift + click to select a range
da41695

feat(color): add red color utility export


rafa-thayto Mar 10, 2026
cc4113c

feat(doctor): add doctor command for project health checks


rafa-thayto Mar 10, 2026
aad17a3

feat(cli): register doctor command


rafa-thayto Mar 10, 2026
7666de8

docs: add doctor command to CLI help output


rafa-thayto Mar 10, 2026
a2aa71f

refactor(doctor): remove git availability check


rafa-thayto Mar 10, 2026
4cac338

refactor(doctor): DRY check functions with defineCheck builder and im…


rafa-thayto Mar 11, 2026
29b6c0d

fix: align doctor command with centralized error handling patterns


rafa-thayto Mar 11, 2026
e939180

refactor(doctor): improve check names and messages for clarity


rafa-thayto Mar 11, 2026
1d72531

fix(doctor): restore Instance IDs prefix in check messages


rafa-thayto Mar 11, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


7 changes: 7 additions & 0 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -31,6 +31,7 @@ Commands:
 api [options] [endpoint] [filter] Make authenticated requests to the Clerk API
 ls [filter] List available API endpoints
 (no args) Interactive request builder (TTY only)
 doctor [options] Check your project's Clerk integration health
 deploy [options] Deploy your Clerk application (hidden)

clerk init
Expand DownExpand Up@@ -83,6 +84,12 @@ clerk api [endpoint] [filter]
clerk api ls [filter] List available API endpoints
clerk api Interactive request builder (TTY only)

clerk doctor
 --verbose Show detailed output for each check
 --json Output results as JSON
 --spotlight Only show warnings and failures
 --fix Attempt to auto-fix issues

clerk deploy
 --debug Show debug output
```
Expand Down

17 changes: 16 additions & 1 deletion
src/cli.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,7 @@ import { configSchema } from "./commands/config/schema.js";
import { api } from "./commands/api/index.js";
import { link } from "./commands/link/index.js";
import { unlink } from "./commands/unlink/index.js";
import { doctor } from "./commands/doctor/index.js";
import { CliError, UserAbortError, ApiError, EXIT_CODE, throwUsageError } from "./lib/errors.js";
import { red } from "./lib/color.js";

Expand DownExpand Up@@ -42,7 +43,12 @@ program.command("init").description("Initialize Clerk in your project").action(i

const auth = program.command("auth").description("Manage authentication");

auth.command("login").description("Log in to your Clerk account").action(login);
auth
 .command("login")
 .description("Log in to your Clerk account")
 .action(async () => {
 await login();
 });

auth.command("logout").description("Log out of your Clerk account").action(logout);

Expand DownExpand Up@@ -122,6 +128,15 @@ program
 .option("--yes", "Skip confirmation for mutating requests")
 .action(api);

program
 .command("doctor")
 .description("Check your project's Clerk integration health")
 .option("--verbose", "Show detailed output for each check")
 .option("--json", "Output results as JSON")
 .option("--spotlight", "Only show warnings and failures")
 .option("--fix", "Attempt to auto-fix issues")
 .action(doctor);

program
 .command("deploy", { hidden: true })
 .description("Deploy your Clerk application")
Expand Down

93 changes: 93 additions & 0 deletions
src/commands/doctor/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
# Doctor Command

Runs a series of diagnostic checks on your Clerk CLI setup and reports
the status of each check. The command is read-only and never modifies
any state (unless `--fix` is used).

## Usage

```sh
clerk doctor # Run all checks
clerk doctor --verbose # Show detailed output
clerk doctor --json # Output results as JSON
clerk doctor --spotlight # Only show warnings and failures
clerk doctor --fix # Offer to auto-fix issues
```

## Options

| Flag | Description |
| ------------- | ----------------------------------------------------- |
| `--verbose` | Show detailed diagnostic info for each check |
| `--json` | Output results as machine-readable JSON |
| `--spotlight` | Only show warnings and failures (hide passing checks) |
| `--fix` | Offer to auto-fix issues with known remedies |

## Checks

| Check | Category | What it verifies |
| --------------------- | -------------- | ------------------------------------------------------------------ |
| Authentication token | Authentication | Credential store has a stored token |
| Token validity | Authentication | Token is still valid (calls `/oauth/userinfo`) |
| Project linkage | Project | Current directory is linked to a Clerk app |
@dmoernerdmoernerMar 11, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still find "Linked application" and "Project linkage" a little confusing. The definition of "Project linkage" doesn't use the term "project" but just uses "Clerk app".
@rafa-thaytorafa-thaytoMar 11, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let me think better on this
do you have any name suggestions?
| Linked application | Project | Linked application ID is accessible via the API |
| Instances | Project | Configured dev/prod instance IDs match the application's instances |
| Environment variables | Environment | .env.local or .env has Clerk keys |
| CLI configuration | Configuration | ~/.clerk/config.json exists and parses |

## Auto-Fix (`--fix`)

When `--fix` is passed in human mode, the command prompts to fix each
issue after all checks complete. After applying fixes, all checks are
re-run to verify the results.

`--fix` only works in human mode because the underlying fix actions are
interactive (`clerk auth login` opens a browser, `clerk link` shows a
picker). It is ignored in `--json` mode and agent mode.

Fixable issues:

| Issue | Fix action |
| ---------------------------------- | ----------------------------------- |
| Not logged in / expired token | Log in with `clerk auth login` |
| Not linked to an app / stale app | Link project with `clerk link` |
| Missing environment variables | Pull env vars with `clerk env pull` |
| Missing or corrupt CLI config file | Log in with `clerk auth login` |

Duplicate fix actions (e.g., multiple checks suggesting `clerk auth login`)
are deduplicated.

## Agent / CI Usage

AI agents and CI pipelines should use `--json` to get structured output:

```sh
clerk doctor --json # Diagnose, output JSON
clerk doctor --json --spotlight # JSON with only warnings/errors
```

Each result includes `name`, `status` (`pass` / `warn` / `fail`),
`message`, and optionally `detail` (extra diagnostic info), `remedy`
(a human-readable fix instruction), and `fix` (a label describing
the auto-fix action).

Agents cannot use `--fix` directly because the fix actions are interactive.
Instead, agents should read the `remedy` field from the JSON output and
orchestrate fixes themselves (e.g., ask the user to run `clerk auth login`,
or call `clerk link --app <id>` with a known app ID).

Exit code 1 signals one or more checks failed.

## Exit Codes

| Code | Meaning |
| ---- | ---------------------------------------- |
| 0 | All checks passed (warnings are allowed) |
| 1 | One or more checks failed |

## API Endpoints

| Method | Endpoint | Description |
| ------ | ----------------------------------- | ----------------------------------------------- |
| `GET` | `/oauth/userinfo` | Validates the stored auth token |
| `GET` | `/v1/platform/applications/{appId}` | Verifies the linked app and its instances exist |
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat: add doctor command for project health checks#21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

rafa-thayto
merged 9 commits into

from

Mar 11, 2026
 Merged


feat: add doctor command for project health checks
#21
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


9 commits


Select commit
Hold shift + click to select a range
da41695

feat(color): add red color utility export


rafa-thayto Mar 10, 2026
cc4113c

feat(doctor): add doctor command for project health checks


rafa-thayto Mar 10, 2026
aad17a3

feat(cli): register doctor command


rafa-thayto Mar 10, 2026
7666de8

docs: add doctor command to CLI help output


rafa-thayto Mar 10, 2026
a2aa71f

refactor(doctor): remove git availability check


rafa-thayto Mar 10, 2026
4cac338

refactor(doctor): DRY check functions with defineCheck builder and im…


rafa-thayto Mar 11, 2026
29b6c0d

fix: align doctor command with centralized error handling patterns


rafa-thayto Mar 11, 2026
e939180

refactor(doctor): improve check names and messages for clarity


rafa-thayto Mar 11, 2026
1d72531

fix(doctor): restore Instance IDs prefix in check messages


rafa-thayto Mar 11, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


7 changes: 7 additions & 0 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -31,6 +31,7 @@ Commands:
 api [options] [endpoint] [filter] Make authenticated requests to the Clerk API
 ls [filter] List available API endpoints
 (no args) Interactive request builder (TTY only)
 doctor [options] Check your project's Clerk integration health
 deploy [options] Deploy your Clerk application (hidden)

clerk init
Expand DownExpand Up@@ -83,6 +84,12 @@ clerk api [endpoint] [filter]
clerk api ls [filter] List available API endpoints
clerk api Interactive request builder (TTY only)

clerk doctor
 --verbose Show detailed output for each check
 --json Output results as JSON
 --spotlight Only show warnings and failures
 --fix Attempt to auto-fix issues

clerk deploy
 --debug Show debug output
```
Expand Down

17 changes: 16 additions & 1 deletion
src/cli.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,7 @@ import { configSchema } from "./commands/config/schema.js";
import { api } from "./commands/api/index.js";
import { link } from "./commands/link/index.js";
import { unlink } from "./commands/unlink/index.js";
import { doctor } from "./commands/doctor/index.js";
import { CliError, UserAbortError, ApiError, EXIT_CODE, throwUsageError } from "./lib/errors.js";
import { red } from "./lib/color.js";

Expand DownExpand Up@@ -42,7 +43,12 @@ program.command("init").description("Initialize Clerk in your project").action(i

const auth = program.command("auth").description("Manage authentication");

auth.command("login").description("Log in to your Clerk account").action(login);
auth
 .command("login")
 .description("Log in to your Clerk account")
 .action(async () => {
 await login();
 });

auth.command("logout").description("Log out of your Clerk account").action(logout);

Expand DownExpand Up@@ -122,6 +128,15 @@ program
 .option("--yes", "Skip confirmation for mutating requests")
 .action(api);

program
 .command("doctor")
 .description("Check your project's Clerk integration health")
 .option("--verbose", "Show detailed output for each check")
 .option("--json", "Output results as JSON")
 .option("--spotlight", "Only show warnings and failures")
 .option("--fix", "Attempt to auto-fix issues")
 .action(doctor);

program
 .command("deploy", { hidden: true })
 .description("Deploy your Clerk application")
Expand Down

93 changes: 93 additions & 0 deletions
src/commands/doctor/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
# Doctor Command

Runs a series of diagnostic checks on your Clerk CLI setup and reports
the status of each check. The command is read-only and never modifies
any state (unless `--fix` is used).

## Usage

```sh
clerk doctor # Run all checks
clerk doctor --verbose # Show detailed output
clerk doctor --json # Output results as JSON
clerk doctor --spotlight # Only show warnings and failures
clerk doctor --fix # Offer to auto-fix issues
```

## Options

| Flag | Description |
| ------------- | ----------------------------------------------------- |
| `--verbose` | Show detailed diagnostic info for each check |
| `--json` | Output results as machine-readable JSON |
| `--spotlight` | Only show warnings and failures (hide passing checks) |
| `--fix` | Offer to auto-fix issues with known remedies |

## Checks

| Check | Category | What it verifies |
| --------------------- | -------------- | ------------------------------------------------------------------ |
| Authentication token | Authentication | Credential store has a stored token |
| Token validity | Authentication | Token is still valid (calls `/oauth/userinfo`) |
| Project linkage | Project | Current directory is linked to a Clerk app |
@dmoernerdmoernerMar 11, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still find "Linked application" and "Project linkage" a little confusing. The definition of "Project linkage" doesn't use the term "project" but just uses "Clerk app".
@rafa-thaytorafa-thaytoMar 11, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let me think better on this
do you have any name suggestions?
| Linked application | Project | Linked application ID is accessible via the API |
| Instances | Project | Configured dev/prod instance IDs match the application's instances |
| Environment variables | Environment | .env.local or .env has Clerk keys |
| CLI configuration | Configuration | ~/.clerk/config.json exists and parses |

## Auto-Fix (`--fix`)

When `--fix` is passed in human mode, the command prompts to fix each
issue after all checks complete. After applying fixes, all checks are
re-run to verify the results.

`--fix` only works in human mode because the underlying fix actions are
interactive (`clerk auth login` opens a browser, `clerk link` shows a
picker). It is ignored in `--json` mode and agent mode.

Fixable issues:

| Issue | Fix action |
| ---------------------------------- | ----------------------------------- |
| Not logged in / expired token | Log in with `clerk auth login` |
| Not linked to an app / stale app | Link project with `clerk link` |
| Missing environment variables | Pull env vars with `clerk env pull` |
| Missing or corrupt CLI config file | Log in with `clerk auth login` |

Duplicate fix actions (e.g., multiple checks suggesting `clerk auth login`)
are deduplicated.

## Agent / CI Usage

AI agents and CI pipelines should use `--json` to get structured output:

```sh
clerk doctor --json # Diagnose, output JSON
clerk doctor --json --spotlight # JSON with only warnings/errors
```

Each result includes `name`, `status` (`pass` / `warn` / `fail`),
`message`, and optionally `detail` (extra diagnostic info), `remedy`
(a human-readable fix instruction), and `fix` (a label describing
the auto-fix action).

Agents cannot use `--fix` directly because the fix actions are interactive.
Instead, agents should read the `remedy` field from the JSON output and
orchestrate fixes themselves (e.g., ask the user to run `clerk auth login`,
or call `clerk link --app <id>` with a known app ID).

Exit code 1 signals one or more checks failed.

## Exit Codes

| Code | Meaning |
| ---- | ---------------------------------------- |
| 0 | All checks passed (warnings are allowed) |
| 1 | One or more checks failed |

## API Endpoints

| Method | Endpoint | Description |
| ------ | ----------------------------------- | ----------------------------------------------- |
| `GET` | `/oauth/userinfo` | Validates the stored auth token |
| `GET` | `/v1/platform/applications/{appId}` | Verifies the linked app and its instances exist |
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat: add doctor command for project health checks#21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

rafa-thayto
merged 9 commits into

from

Mar 11, 2026
 Merged


feat: add doctor command for project health checks
#21
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


9 commits


Select commit
Hold shift + click to select a range
da41695

feat(color): add red color utility export


rafa-thayto Mar 10, 2026
cc4113c

feat(doctor): add doctor command for project health checks


rafa-thayto Mar 10, 2026
aad17a3

feat(cli): register doctor command


rafa-thayto Mar 10, 2026
7666de8

docs: add doctor command to CLI help output


rafa-thayto Mar 10, 2026
a2aa71f

refactor(doctor): remove git availability check


rafa-thayto Mar 10, 2026
4cac338

refactor(doctor): DRY check functions with defineCheck builder and im…


rafa-thayto Mar 11, 2026
29b6c0d

fix: align doctor command with centralized error handling patterns


rafa-thayto Mar 11, 2026
e939180

refactor(doctor): improve check names and messages for clarity


rafa-thayto Mar 11, 2026
1d72531

fix(doctor): restore Instance IDs prefix in check messages


rafa-thayto Mar 11, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


7 changes: 7 additions & 0 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -31,6 +31,7 @@ Commands:
 api [options] [endpoint] [filter] Make authenticated requests to the Clerk API
 ls [filter] List available API endpoints
 (no args) Interactive request builder (TTY only)
 doctor [options] Check your project's Clerk integration health
 deploy [options] Deploy your Clerk application (hidden)

clerk init
Expand DownExpand Up@@ -83,6 +84,12 @@ clerk api [endpoint] [filter]
clerk api ls [filter] List available API endpoints
clerk api Interactive request builder (TTY only)

clerk doctor
 --verbose Show detailed output for each check
 --json Output results as JSON
 --spotlight Only show warnings and failures
 --fix Attempt to auto-fix issues

clerk deploy
 --debug Show debug output
```
Expand Down

17 changes: 16 additions & 1 deletion
src/cli.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,7 @@ import { configSchema } from "./commands/config/schema.js";
import { api } from "./commands/api/index.js";
import { link } from "./commands/link/index.js";
import { unlink } from "./commands/unlink/index.js";
import { doctor } from "./commands/doctor/index.js";
import { CliError, UserAbortError, ApiError, EXIT_CODE, throwUsageError } from "./lib/errors.js";
import { red } from "./lib/color.js";

Expand DownExpand Up@@ -42,7 +43,12 @@ program.command("init").description("Initialize Clerk in your project").action(i

const auth = program.command("auth").description("Manage authentication");

auth.command("login").description("Log in to your Clerk account").action(login);
auth
 .command("login")
 .description("Log in to your Clerk account")
 .action(async () => {
 await login();
 });

auth.command("logout").description("Log out of your Clerk account").action(logout);

Expand DownExpand Up@@ -122,6 +128,15 @@ program
 .option("--yes", "Skip confirmation for mutating requests")
 .action(api);

program
 .command("doctor")
 .description("Check your project's Clerk integration health")
 .option("--verbose", "Show detailed output for each check")
 .option("--json", "Output results as JSON")
 .option("--spotlight", "Only show warnings and failures")
 .option("--fix", "Attempt to auto-fix issues")
 .action(doctor);

program
 .command("deploy", { hidden: true })
 .description("Deploy your Clerk application")
Expand Down

93 changes: 93 additions & 0 deletions
src/commands/doctor/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
# Doctor Command

Runs a series of diagnostic checks on your Clerk CLI setup and reports
the status of each check. The command is read-only and never modifies
any state (unless `--fix` is used).

## Usage

```sh
clerk doctor # Run all checks
clerk doctor --verbose # Show detailed output
clerk doctor --json # Output results as JSON
clerk doctor --spotlight # Only show warnings and failures
clerk doctor --fix # Offer to auto-fix issues
```

## Options

| Flag | Description |
| ------------- | ----------------------------------------------------- |
| `--verbose` | Show detailed diagnostic info for each check |
| `--json` | Output results as machine-readable JSON |
| `--spotlight` | Only show warnings and failures (hide passing checks) |
| `--fix` | Offer to auto-fix issues with known remedies |

## Checks

| Check | Category | What it verifies |
| --------------------- | -------------- | ------------------------------------------------------------------ |
| Authentication token | Authentication | Credential store has a stored token |
| Token validity | Authentication | Token is still valid (calls `/oauth/userinfo`) |
| Project linkage | Project | Current directory is linked to a Clerk app |
@dmoernerdmoernerMar 11, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still find "Linked application" and "Project linkage" a little confusing. The definition of "Project linkage" doesn't use the term "project" but just uses "Clerk app".
@rafa-thaytorafa-thaytoMar 11, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let me think better on this
do you have any name suggestions?
| Linked application | Project | Linked application ID is accessible via the API |
| Instances | Project | Configured dev/prod instance IDs match the application's instances |
| Environment variables | Environment | .env.local or .env has Clerk keys |
| CLI configuration | Configuration | ~/.clerk/config.json exists and parses |

## Auto-Fix (`--fix`)

When `--fix` is passed in human mode, the command prompts to fix each
issue after all checks complete. After applying fixes, all checks are
re-run to verify the results.

`--fix` only works in human mode because the underlying fix actions are
interactive (`clerk auth login` opens a browser, `clerk link` shows a
picker). It is ignored in `--json` mode and agent mode.

Fixable issues:

| Issue | Fix action |
| ---------------------------------- | ----------------------------------- |
| Not logged in / expired token | Log in with `clerk auth login` |
| Not linked to an app / stale app | Link project with `clerk link` |
| Missing environment variables | Pull env vars with `clerk env pull` |
| Missing or corrupt CLI config file | Log in with `clerk auth login` |

Duplicate fix actions (e.g., multiple checks suggesting `clerk auth login`)
are deduplicated.

## Agent / CI Usage

AI agents and CI pipelines should use `--json` to get structured output:

```sh
clerk doctor --json # Diagnose, output JSON
clerk doctor --json --spotlight # JSON with only warnings/errors
```

Each result includes `name`, `status` (`pass` / `warn` / `fail`),
`message`, and optionally `detail` (extra diagnostic info), `remedy`
(a human-readable fix instruction), and `fix` (a label describing
the auto-fix action).

Agents cannot use `--fix` directly because the fix actions are interactive.
Instead, agents should read the `remedy` field from the JSON output and
orchestrate fixes themselves (e.g., ask the user to run `clerk auth login`,
or call `clerk link --app <id>` with a known app ID).

Exit code 1 signals one or more checks failed.

## Exit Codes

| Code | Meaning |
| ---- | ---------------------------------------- |
| 0 | All checks passed (warnings are allowed) |
| 1 | One or more checks failed |

## API Endpoints

| Method | Endpoint | Description |
| ------ | ----------------------------------- | ----------------------------------------------- |
| `GET` | `/oauth/userinfo` | Validates the stored auth token |
| `GET` | `/v1/platform/applications/{appId}` | Verifies the linked app and its instances exist |
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
feat: add doctor command for project health checks#21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

rafa-thayto
merged 9 commits into

from

Mar 11, 2026
 Merged


feat: add doctor command for project health checks
#21
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


9 commits


Select commit
Hold shift + click to select a range
da41695

feat(color): add red color utility export


rafa-thayto Mar 10, 2026
cc4113c

feat(doctor): add doctor command for project health checks


rafa-thayto Mar 10, 2026
aad17a3

feat(cli): register doctor command


rafa-thayto Mar 10, 2026
7666de8

docs: add doctor command to CLI help output


rafa-thayto Mar 10, 2026
a2aa71f

refactor(doctor): remove git availability check


rafa-thayto Mar 10, 2026
4cac338

refactor(doctor): DRY check functions with defineCheck builder and im…


rafa-thayto Mar 11, 2026
29b6c0d

fix: align doctor command with centralized error handling patterns


rafa-thayto Mar 11, 2026
e939180

refactor(doctor): improve check names and messages for clarity


rafa-thayto Mar 11, 2026
1d72531

fix(doctor): restore Instance IDs prefix in check messages


rafa-thayto Mar 11, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


7 changes: 7 additions & 0 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -31,6 +31,7 @@ Commands:
 api [options] [endpoint] [filter] Make authenticated requests to the Clerk API
 ls [filter] List available API endpoints
 (no args) Interactive request builder (TTY only)
 doctor [options] Check your project's Clerk integration health
 deploy [options] Deploy your Clerk application (hidden)

clerk init
Expand DownExpand Up@@ -83,6 +84,12 @@ clerk api [endpoint] [filter]
clerk api ls [filter] List available API endpoints
clerk api Interactive request builder (TTY only)

clerk doctor
 --verbose Show detailed output for each check
 --json Output results as JSON
 --spotlight Only show warnings and failures
 --fix Attempt to auto-fix issues

clerk deploy
 --debug Show debug output
```
Expand Down

17 changes: 16 additions & 1 deletion
src/cli.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,7 @@ import { configSchema } from "./commands/config/schema.js";
import { api } from "./commands/api/index.js";
import { link } from "./commands/link/index.js";
import { unlink } from "./commands/unlink/index.js";
import { doctor } from "./commands/doctor/index.js";
import { CliError, UserAbortError, ApiError, EXIT_CODE, throwUsageError } from "./lib/errors.js";
import { red } from "./lib/color.js";

Expand DownExpand Up@@ -42,7 +43,12 @@ program.command("init").description("Initialize Clerk in your project").action(i

const auth = program.command("auth").description("Manage authentication");

auth.command("login").description("Log in to your Clerk account").action(login);
auth
 .command("login")
 .description("Log in to your Clerk account")
 .action(async () => {
 await login();
 });

auth.command("logout").description("Log out of your Clerk account").action(logout);

Expand DownExpand Up@@ -122,6 +128,15 @@ program
 .option("--yes", "Skip confirmation for mutating requests")
 .action(api);

program
 .command("doctor")
 .description("Check your project's Clerk integration health")
 .option("--verbose", "Show detailed output for each check")
 .option("--json", "Output results as JSON")
 .option("--spotlight", "Only show warnings and failures")
 .option("--fix", "Attempt to auto-fix issues")
 .action(doctor);

program
 .command("deploy", { hidden: true })
 .description("Deploy your Clerk application")
Expand Down

93 changes: 93 additions & 0 deletions
src/commands/doctor/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
# Doctor Command

Runs a series of diagnostic checks on your Clerk CLI setup and reports
the status of each check. The command is read-only and never modifies
any state (unless `--fix` is used).

## Usage

```sh
clerk doctor # Run all checks
clerk doctor --verbose # Show detailed output
clerk doctor --json # Output results as JSON
clerk doctor --spotlight # Only show warnings and failures
clerk doctor --fix # Offer to auto-fix issues
```

## Options

| Flag | Description |
| ------------- | ----------------------------------------------------- |
| `--verbose` | Show detailed diagnostic info for each check |
| `--json` | Output results as machine-readable JSON |
| `--spotlight` | Only show warnings and failures (hide passing checks) |
| `--fix` | Offer to auto-fix issues with known remedies |

## Checks

| Check | Category | What it verifies |
| --------------------- | -------------- | ------------------------------------------------------------------ |
| Authentication token | Authentication | Credential store has a stored token |
| Token validity | Authentication | Token is still valid (calls `/oauth/userinfo`) |
| Project linkage | Project | Current directory is linked to a Clerk app |
@dmoernerdmoernerMar 11, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still find "Linked application" and "Project linkage" a little confusing. The definition of "Project linkage" doesn't use the term "project" but just uses "Clerk app".
@rafa-thaytorafa-thaytoMar 11, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let me think better on this
do you have any name suggestions?
| Linked application | Project | Linked application ID is accessible via the API |
| Instances | Project | Configured dev/prod instance IDs match the application's instances |
| Environment variables | Environment | .env.local or .env has Clerk keys |
| CLI configuration | Configuration | ~/.clerk/config.json exists and parses |

## Auto-Fix (`--fix`)

When `--fix` is passed in human mode, the command prompts to fix each
issue after all checks complete. After applying fixes, all checks are
re-run to verify the results.

`--fix` only works in human mode because the underlying fix actions are
interactive (`clerk auth login` opens a browser, `clerk link` shows a
picker). It is ignored in `--json` mode and agent mode.

Fixable issues:

| Issue | Fix action |
| ---------------------------------- | ----------------------------------- |
| Not logged in / expired token | Log in with `clerk auth login` |
| Not linked to an app / stale app | Link project with `clerk link` |
| Missing environment variables | Pull env vars with `clerk env pull` |
| Missing or corrupt CLI config file | Log in with `clerk auth login` |

Duplicate fix actions (e.g., multiple checks suggesting `clerk auth login`)
are deduplicated.

## Agent / CI Usage

AI agents and CI pipelines should use `--json` to get structured output:

```sh
clerk doctor --json # Diagnose, output JSON
clerk doctor --json --spotlight # JSON with only warnings/errors
```

Each result includes `name`, `status` (`pass` / `warn` / `fail`),
`message`, and optionally `detail` (extra diagnostic info), `remedy`
(a human-readable fix instruction), and `fix` (a label describing
the auto-fix action).

Agents cannot use `--fix` directly because the fix actions are interactive.
Instead, agents should read the `remedy` field from the JSON output and
orchestrate fixes themselves (e.g., ask the user to run `clerk auth login`,
or call `clerk link --app <id>` with a known app ID).

Exit code 1 signals one or more checks failed.

## Exit Codes

| Code | Meaning |
| ---- | ---------------------------------------- |
| 0 | All checks passed (warnings are allowed) |
| 1 | One or more checks failed |

## API Endpoints

| Method | Endpoint | Description |
| ------ | ----------------------------------- | ----------------------------------------------- |
| `GET` | `/oauth/userinfo` | Validates the stored auth token |
| `GET` | `/v1/platform/applications/{appId}` | Verifies the linked app and its instances exist |
Loading
Loading