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

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

# 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
• OpenCode — Installation and MCP config detection
• Gemini CLI — 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
• 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 when --report is used manually

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