Diagnostics (doctor)

mogick doctor inspects the current Mogick CLI environment and generates a structured diagnostic report. It prints Markdown by default, supports JSON through --json or --format json, and can write directly to a file with --export <path>. The default checks include terminal compatibility but do not make network requests or run interactive font checks.

The report covers the operating system and shell, configuration integrity, models and providers, the memory database, MCP server connections, and loaded Skills. Enable --check-network explicitly to test connectivity, chat completions, streaming, usage metadata, and related service capabilities. Each report is a reproducible troubleshooting snapshot that you can attach to a support request.

Usage

mogick doctor                          # Run diagnostics and print a Markdown report
mogick doctor --json                   # Run diagnostics and print JSON
mogick doctor --format json            # Select JSON with the --format option
mogick doctor --export ./report.md      # Write the raw report to a file
mogick doctor --check-network          # Also probe network service availability
mogick doctor --check-terminal-font    # Interactively inspect the font and terminal grid
mogick doctor --all                    # Run the network and terminal checks together

Options

Option	Description
--json	Output JSON; equivalent to --format json
--format md|json	Specify output format: md (Markdown, default) or json
--export <path>	Write the report to the specified file
--check-network	Probe the reachability of network services (such as API endpoints)
--check-terminal-font	Interactively check Unicode borders, Chinese width and status symbols
--all	Perform both network probing and interactive terminal/font checking
--verbose	Increase output verbosity and show more diagnostic details
--logs-path <file>	Write diagnostic logs to the specified file

Output format

The JSON output has the following top-level structure:

Field	Description
schema_version	Report format version
generated_at	Generated timestamp
request	Diagnostic request parameters, such as verbose and check_network
summary	Summary status (status, warning_count, error_count)
sections	Diagnostic modules containing id, title, status, items, and details

Status values are ok, warn, error, or exception.

Checks

A complete report covers these modules:

Section ID	Checks
runtime	Operating system, architecture, Go version, CLI version, working directory, and executable path
config	Global and project-level config.json paths and whether they exist
models	Local model and provider configuration, including model list, provider types, and counts
memory	sessions.sqlite path, existence, file size
mcp	Each MCP server's name, type, transport, and enabled state
skills	Skills directory and file status
auth	Authentication-token status and expiration
terminal	stdin/stdout, TERM, terminal size, UTF-8 locale and Windows VT capabilities

Having no MCP servers configured is a valid empty state and does not produce a warning. The summary and Needs attention list derive their warning counts from the same checks.

Network check

--check-network makes real network requests and adds a network section to the report. When troubleshooting model connectivity, focus on these fields:

Field or check item	Meaning
base_url	The actual API base used to request model services
server_url	The provider's original service URL; with llm-store, it may differ from base_url
provider	The active provider type
timeout_seconds	Total timeout for the network checks
server_reachable	Basic HTTP reachability check on base_url
chat_completion	Whether a non-streaming Chat Completions request succeeds
chat_usage	Whether a non-streaming response includes usage metadata
chat_tool_call	Whether the model can return a tool call
stream_response	Whether a streaming response completes and returns text
stream_usage	Whether a streaming response includes usage metadata
embeddings	Whether an embedding request succeeds when an embedding model is configured
rerank	Whether a reranking request succeeds when a reranking model is configured
llm_store_modelinfo	Whether the remote model catalog can be retrieved in an llm-store setup

Common usage fields include prompt_tokens, completion_tokens, total_tokens, and cached_tokens. If chat_completion succeeds but chat_usage or stream_usage reports a warning, the service is usually available but does not return complete token-usage metadata.

Example

Run the default checks and print a Markdown report:

mogick doctor

Print JSON for automated parsing:

mogick doctor --json

Export a report for CI artifacts or team sharing:

mogick doctor --export ./mogick-doctor-report.md

Include verbose output and network checks:

mogick doctor --verbose --check-network

Filter errors from JSON output in an automation script:

mogick doctor --json | jq '.sections[] | select(.status == "error")'