126 lines
4.4 KiB
Markdown
126 lines
4.4 KiB
Markdown
# 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 | `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
|
|
|
|
```bash
|
|
# 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`.
|