Troubleshoot with doctor
Read the CLI's free checks for authentication, keys, models, and client configuration.
Use doctor when sign-in, an API key, or an already configured client is not working. For a first connection, start with the client quickstart. The normal report checks local configuration, authorization, and the free model catalog; it does not generate a response.
text
unlimgpt doctor --client codex
Replace codex with your client ID from the compatibility matrix. Without --client, the client-specific check is skipped. The report prints PASS, WARN, FAIL, or SKIP with each check code. For automation, run unlimgpt doctor --client codex --json.
Read each check
| Code | What it checks | What to do if it needs attention |
|---|---|---|
cli.runtime | The CLI version and operating system on which it started. | Compare your installed version with the installation guide. |
network.origin | The format of the configured HTTPS origin. This does not test network reachability. | Sign in again using a trusted HTTPS origin. For connection failures, see connection troubleshooting. |
cli.helper | Whether the active CLI profile's credential helper command exists and is executable. It does not read the client's actual configuration. | Reinstall the CLI and rerun configure so the client calls the installed executable. |
credential.store | Whether a local credential exists in the operating-system credential store. | WARN means no saved credential was found: sign in and configure the client. For FAIL, unlock or configure the system store; there is no plaintext fallback. |
auth.identity | Whether the CLI's own authorization is active. | Run unlimgpt login again. This authorization is separate from an application's API key. |
api.models | Whether the API key can read the free catalog and access the selected model ID. | Run unlimgpt models and choose an ID in its output. For Codex, quit Codex Desktop completely first; if the catalog lists gpt-5.6-sol, run unlimgpt configure codex --model gpt-5.6-sol. For access errors, check the key. |
client.compatibility | Whether expected client configuration files exist and the CLI supports that setup mode. Guided clients may have no file check. | WARN means an expected file was not found; FAIL means an unsupported mode or a failed check. Review the client guide and rerun configure. Without --client, this check is SKIP. |
inference.probe | One bounded generation request, only after explicit confirmation. | Without --probe, this check is SKIP. If an explicit probe fails, check connectivity and credits. |
PASS confirms only that check. WARN needs attention but does not fail the whole report; FAIL returns process exit code 7. SKIP means a check was not requested, not that the service is healthy. A passing network.origin does not rule out TLS or network failures; client.compatibility does not inspect file contents or test a real client connection; api.models does not verify paid generation.
Use JSON and the paid probe deliberately
text
unlimgpt doctor --client codex --json
The JSON has schema_version and data.checks[] entries with code, status, message, and optional remediation or evidence. Use data.ok and the process exit code for the check result. The outer ok means the CLI produced a JSON report and can be true when data.ok is false. Review evidence before sharing output with support: automatic secret redaction does not replace a review of local paths and other metadata. The CLI version, operating system, check codes, and statuses are usually enough. Never send an API key, token, prompt, or response.
Only after free checks, run one probe if needed. It can consume credits:
text
unlimgpt doctor --client codex --probe
In an interactive terminal, the CLI asks for confirmation. For automation, add --yes only if you accept a paid generation; without confirmation, the probe reports FAIL. Before retrying an uncertain outcome, check API Activity to avoid an unnecessary second request. To undo client setup, use its receipt and revert command only for a change still owned by this CLI.