Overview
gizzi doctor runs a set of local health checks across your Gizzi Code installation and working environment. Use it when the CLI behaves unexpectedly, before opening a bug report, or after installing or upgrading Gizzi Code.
The command inspects the runtime, required dependencies, configured providers, the local database, global configuration, and the current project directory. Each check prints either a passing status or a clear failure message describing what is wrong and how to fix it.
gizzi doctor is a read-only diagnostic command. It does not modify sessions, files, or settings unless you follow the remediation steps it prints.Command reference
gizzi doctor takes no subcommands and no flags.
Diagnostic categories
The command groups checks into the following sections.Runtime
Dependencies
Providers
When providers are configured, each provider ID is listed with the number of available models.
Database
Config
Project
The project section inspects the current working directory.Basic usage
Interpreting failures
When a check fails,gizzi doctor prints an ✗ line with a specific message:
- Bun or Node failure — Gizzi Code requires a working Bun runtime. Reinstall or upgrade Bun, then run the command again.
- Ripgrep missing — Install
ripgrepthrough your package manager (brew install ripgrep,apt install ripgrep, etc.). Without it, file search and globbing tools are unavailable. - Git missing — Install Git. Version control features such as diff context and branch awareness depend on it.
- No providers configured — Run
gizzi connect loginto add credentials for at least one provider. - Database or config directory missing — These are created automatically during normal use. If they remain missing, verify permissions in
~/.local/share/gizziand~/.config/gizzi-code.
Interactive diagnostics
Inside the interactive TUI (gizzi with no arguments), the /doctor screen provides the same core checks plus additional context: installation type, auto-update status, version locks, agent parse errors, plugin errors, MCP parsing warnings, keybinding warnings, and environment-variable validation. Use /doctor when you want a more detailed, interactive view of the same health data.
Common flags
gizzi doctor does not define any flags. Global flags such as --help and --version still apply.
Related docs
- Installation — Install or upgrade Gizzi Code
- Configuration — Manage profiles, models, and runtime options
- Authentication — Log in to providers with
gizzi connect login - CLI Overview — How Gizzi Code fits into the Allternit platform