temp/docs/reference/cli_system_commands.md

# 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 | Short git SHA of HEAD |
| `schema` | string | Data schema version (`v3`) |
| `platform` | string | OS and architecture |
| `dependencies` | object | Key dependency versions (langgraph, langchain-core, pydantic, typer) |

### 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.