# 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
