Doctor

novageness doctor runs a deep diagnostic of your local Novageness install. It inspects every supported AI coding tool — Cursor, Claude Code, Codex, GitHub Copilot, and Augment Code — and validates that your stored API key is still accepted by the backend.

novageness doctor

What it checks

For each AI coding tool, doctor verifies three things:

Check	What it confirms
Config	The tool’s own config file contains the Novageness integration
Hook script	The installed hook / key-helper file exists on disk
Env wiring	The API key — and the gateway URL for gateway mode — is exported in your shell

It also validates your stored API key against the backend, so a revoked or expired key is caught here rather than at your next tool call. For Claude Code and Codex, doctor reports the active mode (subscription vs gateway).

Per-tool status

Each tool resolves to one of four statuses:

Status	Meaning
Healthy	Config, hook script, and env wiring all present (shown in green)
Tampered	Installed but broken — a missing hook, a config without the integration, or a managed config that points at a hook that isn’t on disk. Reinstall to fix
Not set up	No Novageness integration found for this tool
Managed by MDM	Configured org-wide by an admin (config and hook verified)

Doctor always tells you the next step:

Nothing set up yet → run novageness setup.
A user-level tool is tampered → run novageness doctor --fix (no sudo needed).
An MDM-managed install is broken → it’s org-wide, so run sudo novageness doctor --fix to reinstall the managed hooks.
API key invalid → run novageness login.

Exit codes

Code	Meaning
`0`	All tools healthy (or not installed / MDM-managed) and the API key is valid
non-zero	Any tool is Tampered or the API key is invalid

The non-zero exit lets you gate scripts or CI on a clean install.

Flags

Flag	Behavior
`--fix`	Reinstall the tampered tools the current scope can repair. Without `sudo` it fixes your user-level tools; with `sudo` (`sudo novageness doctor --fix`) it reinstalls the MDM-managed (org-wide) hooks. Whichever scope you run, doctor points you at the other for anything it couldn’t touch
`--json`	Machine-readable output (per-tool `status`, `checks`, `conflict`, plus `api_key`)

The JSON mirrors the human report. Each tool carries its status, the individual checks, and a boolean conflict — true when two modes of the same tool are installed at once (for example Claude Code in both subscription and gateway mode), which doctor reports as Tampered so --fix can clean it up. api_key carries the key-validation result (valid / invalid / not-logged-in / unverified).

Examples

# Full health check
novageness doctor

# Repair every tampered tool automatically
novageness doctor --fix

# Machine-readable output for scripts / CI
novageness doctor --json

Getting Started

CLI

Policies

Analytics

Hooks API

Integrations

MDM Integrations

Connections

Support & Troubleshooting

What it checks

Per-tool status

Exit codes

Flags

Examples

​What it checks

​Per-tool status

​Exit codes

​Flags

​Examples

What it checks

Per-tool status

Exit codes

Flags

Examples