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

{
  "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

{
  "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)

{
  "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 for the full check list and remediation steps.