4.4 KiB
Diagnostics Check List
agents diagnostics runs the checks listed below. Each check returns one
of three statuses: ok, warn, or error. When the --check flag
is passed the command exits with code 1 if any check reports error.
Checks
Config file
Verifies that the configuration file (default config.toml or the path set
via CLEVERAGENTS_CONFIG_PATH) exists and is readable.
| Status | Condition | Remediation |
|---|---|---|
| ok | File exists and is readable, or file is absent (defaults are used) | None required |
| error | File exists but is not readable | Fix file permissions: chmod 644 <config_path> |
Data directory
Verifies that the data directory (from Settings.data_dir) exists and is
writable.
| Status | Condition | Remediation |
|---|---|---|
| ok | Directory exists and is writable | None required |
| warn | Directory does not exist | Create it: mkdir -p <data_dir> |
| error | Directory exists but is not writable | Fix permissions: chmod 755 <data_dir> or change ownership |
Database
Verifies that the SQLite database file (or its parent directory for first-run) is accessible and writable.
| Status | Condition | Remediation |
|---|---|---|
| ok | DB file is writable, or parent dir is writable (first run) | None required |
| ok | Non-SQLite database URL is configured | None required |
| error | DB file exists but is locked or not writable | Close other processes using the DB, or fix permissions |
| error | Parent directory is not writable | Fix parent directory permissions |
Provider API keys
Checks whether each supported LLM provider has its API key configured. One sub-check is emitted per provider.
| Provider | Environment variable | Status when missing |
|---|---|---|
| OpenAI | OPENAI_API_KEY |
warn |
| Anthropic | ANTHROPIC_API_KEY |
warn |
GOOGLE_API_KEY |
warn | |
| Google Gemini | GEMINI_API_KEY |
warn |
| Hugging Face | HF_TOKEN |
warn |
| OpenRouter | OPENROUTER_API_KEY |
warn |
| Status | Condition | Remediation |
|---|---|---|
| ok | API key is configured | None required |
| warn | API key is not set | Set the environment variable to enable the provider |
Missing provider keys are warnings, not errors, because the system can operate with any single provider configured.
Disk space
Checks available disk space on the volume containing the current working directory.
| Status | Condition | Remediation |
|---|---|---|
| ok | >= 1.0 GB free | None required |
| warn | 0.5 -- 1.0 GB free | Free disk space or move data directory to a larger volume |
| error | < 0.5 GB free | Immediately free disk space to avoid data corruption |
File permissions
Verifies read and write access to the data directory.
| Status | Condition | Remediation |
|---|---|---|
| ok | Data directory is readable and writable | None required |
| warn | Data directory does not exist | Create it (see Data directory check) |
| warn | Data directory is readable but not writable | Fix write permissions: chmod u+w <data_dir> |
| error | Data directory is not writable | Fix permissions or change ownership |
Git
Checks that the git binary is available on PATH.
| Status | Condition | Remediation |
|---|---|---|
| ok | git --version succeeds |
None required |
| error | git is not found or times out |
Install git for version control integration |
Summary counts
The summary object in JSON/YAML output includes:
| Field | Type | Description |
|---|---|---|
total |
int | Total number of individual checks run |
ok |
int | Checks that passed |
warnings |
int | Checks with non-critical issues |
errors |
int | Checks with critical issues |
duration_s |
float | Wall-clock seconds for the full diagnostic run |
Recommendations
When a check returns warn or error and has an actionable fix, the
recommendation is collected into the recommendations list in the output.
Recommendations are ordered by check execution order.
Using --check in CI
# Fail the pipeline if any critical check errors
agents diagnostics --check --format json
Exit code 0 means all checks passed (warnings are tolerated).
Exit code 1 means at least one check reported error.