Diagnostics & Troubleshooting
Run one read-only command to check the installed CLI, environment variables, protected configuration, credentials, API connectivity, secure-storage provider, and optional skill-installer dependency.
Command runbook
Diagnose the current setup
Doctor reads configuration and credentials only to validate them. It never prints an API key or changes local or remote state.
Run
higantic doctor
Expected
PASS CLI HiGantic CLI 1.8.2 is running. [OK] Credentials: A valid scoped key is available from profile 'default'. [OK] HiGantic API: Authentication and API connectivity are working. Result: Ready.
If it fails
Follow the first ERROR line and its hint. Use --offline when the network is intentionally unavailable.
Diagnostic modes
higantic doctor --offline higantic doctor --profile work higantic doctor --json
| Status | Meaning | Exit behavior |
|---|---|---|
| OK | The check passed | No failure |
| WARN | Optional or incomplete setup needs attention | Exit 0 |
| SKIP | A check was deliberately or safely skipped | Exit 0 |
| ERROR | The setup cannot perform the checked operation | Exit 2 |
Common recovery paths
| Message or code | Next action |
|---|---|
| profile_exists | Check status, revoke the exact profile, then sign in again—or choose another profile name |
| profile_not_selected | Run higantic auth profiles, then higantic auth use PROFILE |
| credential_not_found | Run doctor; remove only the exact broken profile with --profile PROFILE --local-only before signing in again |
| incomplete_environment | Set all three HIGANTIC variables or unset all three |
| secure_storage_unavailable | Install or unlock the operating-system credential provider, then rerun doctor |
| connection_error | Check the network and configured API origin, then rerun doctor |
| expired_token | Run higantic auth login to start a new ten-minute browser session |
Skill installation failures
The optional skill installer needs Node.js with npx. HiGantic strips credential and custom-origin environment variables before starting it. Failure output is reduced to a bounded, control-free final reason.
higantic skills install higantic skills install --json