> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ultra.security/llms.txt
> Use this file to discover all available pages before exploring further.

# ultra doctor

> Run system diagnostics and upload reports to Hub

Run diagnostic checks to verify Ultra is properly configured. Optionally upload a sanitized diagnostics report to Ultra Hub for fleet debugging.

## Usage

```bash theme={null}
ultra doctor [flags]
```

## Flags

| Flag        | Short | Default | Description                                                       |
| ----------- | ----- | ------- | ----------------------------------------------------------------- |
| `--verbose` | `-v`  | `false` | Show detailed output                                              |
| `--debug`   |       | `false` | Show detailed detection diagnostics                               |
| `--report`  |       | `false` | Upload a sanitized diagnostics report to Ultra Hub                |
| `--dry-run` |       | `false` | With `--report`, print the payload to stdout instead of uploading |

## Examples

```bash theme={null}
# Run diagnostics
ultra doctor

# Show detailed output
ultra doctor --verbose

# Upload a diagnostics report to Hub
ultra doctor --report

# Preview the report payload without uploading
ultra doctor --report --dry-run
```

## Checks performed

### System

* **Go Runtime** — Go version and platform
* **Operating System** — OS compatibility (macOS, Linux, Windows)

### MCP clients

* **Claude Desktop** — Installation and MCP config detection
* **Cursor** — Installation and MCP config detection
* **VS Code** — Installation and MCP config detection
* **Cline** — Installation and MCP config detection
* **Claude Code** — Installation and MCP config detection
* **Windsurf** — Installation and MCP config detection
* **Goose** — Installation and MCP config detection
* **Codex** — Installation and MCP config detection
* **Grok Build** — Installation and MCP config detection
* **OpenCode** — Installation and MCP config detection
* **Gemini CLI** — Installation and MCP config detection
* **Antigravity** — Installation and MCP config detection
* **Roo Code** — Installation and MCP config detection
* **Amazon Q Developer** — Installation and MCP config detection
* **LM Studio** — Installation and MCP config detection
* **Zed** — Installation and MCP config detection
* **Ona** — Workspace and MCP config detection
* **Hermes** — Installation and MCP config detection

### Configuration

* **Config Directory** — Ultra config directory exists (`~/.config/ultra/`)
* **Config File** — Ultra configuration file exists

### Dependencies

* **Node.js** — Required for npm-based MCP servers
* **Docker** — Optional for containerized MCP servers

## Output

Each check shows a status icon:

* **Pass** — Check succeeded
* **Warning** — Optional component missing or not configured
* **Error** — Required component missing or broken

The summary shows total checks, passes, warnings, and errors with recommendations for any issues found.

## Diagnostics reporting

When you pass `--report`, Ultra collects a sanitized snapshot of your gateway's configuration, detected MCP clients, and recent log artifacts, then uploads the bundle to Ultra Hub. This helps your organization's admins and Ultra support diagnose installation or connectivity issues across a fleet of machines.

### What is collected

| Section                 | Contents                                                                                       |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| **Config snapshot**     | Your `ultra.yaml` with tokens, secrets, and environment variables masked as `[REDACTED]`       |
| **Detected clients**    | Which MCP clients are installed, whether Ultra is configured in each, and any detection errors |
| **Hub state**           | Whether the gateway is linked, the workspace ID, sync interval, and offline mode setting       |
| **Log artifacts**       | The last 16 KB of `sync.log`, `crash.log`, post-install log, and setup agent log (if present)  |
| **Managed preferences** | Whether MDM-managed keys (`AutoSetup`, `DeployKey`, etc.) are present on macOS                 |
| **System info**         | Ultra version, OS, and architecture                                                            |

### Privacy and redaction

The diagnostics payload is automatically redacted before it leaves your machine:

* API keys, tokens, and secrets are replaced with `[REDACTED]`
* Your home directory path is replaced with `~`
* Hostnames are replaced with `[REDACTED_HOSTNAME]`
* Credential patterns (Bearer tokens, JWTs, AWS keys, GitHub tokens, PEM private keys, database URLs) are detected and scrubbed

Use `--report --dry-run` to inspect the exact payload before uploading.

### Requirements

* The gateway must be authenticated with Ultra Hub (`ultra login`)
* The report is uploaded to `POST /api/v1/diagnostics` and stored in S3 for Ultra employees only
* A `gateway.diagnostics_reported` security event appears in your organization's [Admin Log](/hub/admin-log) when `--report` is used manually

<Note>
  Automatic background diagnostic uploads (during install auto-link, for example) do not create Admin Log entries.
</Note>