forked from HAL9000/cleveragents-core
eugen.thaci
f66fb5a19a
Align Unicode box-drawing blocks and related tables in specification.md, ADR-044/045/046, and reference pages for consistent MkDocs rendering. ISSUES CLOSED: #1171
277 lines
8.5 KiB
Markdown
277 lines
8.5 KiB
Markdown
# Core System Commands
|
|
|
|
The CLI exposes three system-level commands for inspecting the running
|
|
environment: `version`, `info`, and `diagnostics`. All three support a
|
|
`--format` flag (`rich`, `plain`, `json`, `yaml`) so output can be consumed
|
|
by humans or parsed by scripts.
|
|
|
|
---
|
|
|
|
## `agents version`
|
|
|
|
Display version, build metadata, and dependency versions.
|
|
|
|
### Usage
|
|
|
|
```
|
|
agents version [--format rich|plain|json|yaml]
|
|
```
|
|
|
|
### Flags
|
|
|
|
| Flag | Default | Description |
|
|
|------|---------|-------------|
|
|
| `--format`, `-f` | `rich` | Output format |
|
|
|
|
### Fields
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `version` | string | Semantic version (`1.0.0`) |
|
|
| `channel` | string | Release channel (`stable`) |
|
|
| `python` | string | Python runtime version |
|
|
| `build_date` | string | ISO date of build (`YYYY-MM-DD`) |
|
|
| `commit` | string | Actual short git SHA of HEAD (from `CLEVERAGENTS_COMMIT` env var or `git rev-parse --short HEAD`; `"unknown"` if neither is available) |
|
|
| `schema` | string | Data schema version (`v3`) |
|
|
| `platform` | string | OS and architecture |
|
|
| `dependencies` | object | Key dependency versions (langgraph, langchain-core, pydantic, typer) |
|
|
|
|
### Commit SHA Resolution
|
|
|
|
The `commit` field is resolved in the following order:
|
|
|
|
1. `CLEVERAGENTS_COMMIT` environment variable — set at build time (e.g. in Docker or CI).
|
|
2. `git rev-parse --short HEAD` — used when running from source with git available.
|
|
3. `"unknown"` — fallback when neither source is available.
|
|
|
|
### Sample output — rich (default)
|
|
|
|
```
|
|
╭──────── CLI Version ─────────╮
|
|
│ CleverAgents CLI │
|
|
│ Version: 1.0.0 │
|
|
│ Channel: stable │
|
|
│ Python: 3.13.2 │
|
|
╰──────────────────────────────╯
|
|
╭──────── Build ───────────────╮
|
|
│ Build Date: 2026-02-17 │
|
|
│ Commit: 6de85ca │
|
|
│ Schema: v3 │
|
|
│ Platform: linux-x86_64 │
|
|
╰──────────────────────────────╯
|
|
╭──────── Dependencies ────────╮
|
|
│ langgraph: 0.3.34 │
|
|
│ langchain-core: 0.3.41 │
|
|
│ pydantic: 2.11.1 │
|
|
│ typer: 0.15.2 │
|
|
╰──────────────────────────────╯
|
|
OK Version reported
|
|
```
|
|
|
|
### Sample output — json
|
|
|
|
```json
|
|
{
|
|
"version": "1.0.0",
|
|
"channel": "stable",
|
|
"python": "3.13.2",
|
|
"build_date": "2026-02-17",
|
|
"commit": "6de85ca",
|
|
"schema": "v3",
|
|
"platform": "linux-x86_64",
|
|
"dependencies": {
|
|
"langgraph": "0.3.34",
|
|
"langchain-core": "0.3.41",
|
|
"pydantic": "2.11.1",
|
|
"typer": "0.15.2"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Sample output — plain
|
|
|
|
```
|
|
version: 1.0.0
|
|
channel: stable
|
|
python: 3.13.2
|
|
build_date: 2026-02-17
|
|
commit: 6de85ca
|
|
schema: v3
|
|
platform: linux-x86_64
|
|
dependencies:
|
|
langgraph: 0.3.34
|
|
langchain-core: 0.3.41
|
|
pydantic: 2.11.1
|
|
typer: 0.15.2
|
|
```
|
|
|
|
---
|
|
|
|
## `agents info`
|
|
|
|
Display environment details, runtime configuration, and storage sizes.
|
|
|
|
### Usage
|
|
|
|
```
|
|
agents info [--format rich|plain|json|yaml]
|
|
```
|
|
|
|
### Flags
|
|
|
|
| Flag | Default | Description |
|
|
|------|---------|-------------|
|
|
| `--format`, `-f` | `rich` | Output format |
|
|
|
|
### Fields
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `version` | string | CleverAgents version |
|
|
| `data_dir` | string | Absolute path to data directory |
|
|
| `config_path` | string | Absolute path to config file |
|
|
| `database` | string | Database URL |
|
|
| `server_mode` | string | Server mode (`disabled` in local-only) |
|
|
| `platform` | string | OS, release, and architecture |
|
|
| `automation` | string | Default automation level |
|
|
| `providers_configured` | int | Number of configured LLM providers |
|
|
| `providers` | list | Names of configured providers |
|
|
| `debug_mode` | bool | Whether debug mode is enabled |
|
|
| `storage` | object | Storage sizes (`db_size`, `logs`) |
|
|
|
|
### Sample output — rich (default)
|
|
|
|
```
|
|
╭──────── Environment ─────────╮
|
|
│ Data Dir: /home/user/... │
|
|
│ Config: config.toml │
|
|
│ Database: sqlite:///... │
|
|
│ Server Mode: disabled │
|
|
│ Platform: Linux 6.x (x86) │
|
|
╰──────────────────────────────╯
|
|
╭──────── Runtime ─────────────╮
|
|
│ Automation: suggest │
|
|
│ Providers: 2 configured │
|
|
│ Debug Mode: False │
|
|
╰──────────────────────────────╯
|
|
╭──────── Storage ─────────────╮
|
|
│ db_size: 0.1 MB │
|
|
│ logs: 0.0 MB │
|
|
╰──────────────────────────────╯
|
|
OK Environment details ready
|
|
```
|
|
|
|
### Sample output — json
|
|
|
|
```json
|
|
{
|
|
"version": "1.0.0",
|
|
"data_dir": "/home/user/.local/share/cleveragents",
|
|
"config_path": "/home/user/.config/cleveragents/config.toml",
|
|
"database": "sqlite:///data/db.sqlite",
|
|
"server_mode": "disabled",
|
|
"platform": "Linux 6.1.0 (x86_64)",
|
|
"automation": "suggest",
|
|
"providers_configured": 2,
|
|
"providers": ["openai", "anthropic"],
|
|
"debug_mode": false,
|
|
"storage": {
|
|
"db_size": "0.1 MB",
|
|
"logs": "0.0 MB"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## `agents diagnostics`
|
|
|
|
Run health checks and report system status.
|
|
|
|
### Usage
|
|
|
|
```
|
|
agents diagnostics [--format rich|plain|json|yaml] [--check]
|
|
```
|
|
|
|
### Flags
|
|
|
|
| Flag | Default | Description |
|
|
|------|---------|-------------|
|
|
| `--format`, `-f` | `rich` | Output format |
|
|
| `--check` | `false` | Exit with code 1 if any check has status `error` |
|
|
|
|
The `--check` flag is intended for CI and scripting: pipe diagnostics into
|
|
a gate that blocks deployment when critical checks fail.
|
|
|
|
### Output schema (json/yaml)
|
|
|
|
```json
|
|
{
|
|
"checks": [
|
|
{"name": "Config file", "status": "ok", "details": "..."},
|
|
{"name": "Database", "status": "ok", "details": "..."}
|
|
],
|
|
"summary": {
|
|
"total": 11,
|
|
"ok": 9,
|
|
"warnings": 2,
|
|
"errors": 0,
|
|
"duration_s": 0.03
|
|
},
|
|
"recommendations": ["Set OPENAI_API_KEY to enable OpenAI models"],
|
|
"has_errors": false,
|
|
"has_warnings": true
|
|
}
|
|
```
|
|
|
|
### Check statuses
|
|
|
|
| Status | Meaning |
|
|
|--------|---------|
|
|
| `ok` | Check passed |
|
|
| `warn` | Non-critical issue detected |
|
|
| `error` | Critical issue — must be resolved |
|
|
|
|
### Sample output — rich (default)
|
|
|
|
```
|
|
Checks
|
|
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
|
|
┃ Check ┃ Status┃ Details ┃
|
|
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
|
|
│ Config file │ OK │ not present (defaults)│
|
|
│ Data directory │ OK │ writable │
|
|
│ Database │ OK │ writable │
|
|
│ Openai key │ OK │ configured │
|
|
│ Anthropic key │ WARN │ missing │
|
|
│ Google key │ WARN │ missing │
|
|
│ Openrouter key │ WARN │ missing │
|
|
│ Disk space │ OK │ 42.1 GB free │
|
|
│ File permissions │ OK │ data dir r/w │
|
|
│ Git │ OK │ git 2.43.0 │
|
|
└──────────────────┴───────┴───────────────────────┘
|
|
╭──────── Summary ────────────╮
|
|
│ Checks: 10 total │
|
|
│ Warnings: 3 │
|
|
│ Errors: 0 │
|
|
│ Duration: 0.03s │
|
|
╰─────────────────────────────╯
|
|
╭──────── Recommendations ────╮
|
|
│ - Set ANTHROPIC_API_KEY ... │
|
|
│ - Set GOOGLE_API_KEY ... │
|
|
│ - Set OPENROUTER_API_KEY ...│
|
|
╰─────────────────────────────╯
|
|
OK All checks passed
|
|
```
|
|
|
|
### Exit codes
|
|
|
|
| Code | Meaning |
|
|
|------|---------|
|
|
| `0` | All checks passed (or warnings only) |
|
|
| `1` | At least one `error` check (only with `--check`) |
|
|
|
|
See [Diagnostics Checks](diagnostics_checks.md) for the full check list
|
|
and remediation steps.
|