# Understanding CleverAgents CLI Version, Info, and Diagnostics Commands

## Overview
This guide demonstrates the three essential system information commands in the CleverAgents CLI: `version`, `info`, and `diagnostics`. These commands provide quick access to system metadata, configuration details, and diagnostic information. You'll learn the difference between fast-path and regular command behavior, and how to use these commands for troubleshooting and system verification.

## Prerequisites
- CleverAgents installed (`pip install cleveragents`)
- Python 3.12 or higher
- Access to a terminal or command-line interface

## What You'll Learn
This example covers:
- **Version command**: Display the installed CleverAgents version and build information
- **Info command**: Get comprehensive system and configuration information
- **Diagnostics command**: Run diagnostic checks and generate detailed system reports
- **Output formats**: Using JSON, YAML, and plain text output formats
- **Fast-path behavior**: Understanding when commands use optimized execution paths

## Step-by-Step Walkthrough

### Step 1: Check the CleverAgents Version

The `version` command is the fastest way to verify your CleverAgents installation.

```bash
$ agents version
```

**Expected Output:**
```
CleverAgents v3.6.0
Build: 2026-04-19
Python: 3.13.0
```

**What's Happening:**
The `version` command uses a fast-path execution that bypasses full application initialization. It directly reads version metadata from the package and displays it immediately. This is useful for quick verification without waiting for the full CLI to load.

### Step 2: Get Detailed System Information

The `info` command provides comprehensive system and configuration details.

```bash
$ agents info
```

**Expected Output:**
```
CleverAgents System Information
================================

Version Information:
  Version: 3.6.0
  Build Date: 2026-04-19
  Python Version: 3.13.0
  Platform: linux

Installation Details:
  Installation Path: /usr/local/lib/python3.13/site-packages/cleveragents
  Configuration Directory: ~/.cleveragents
  Database Location: ~/.cleveragents/cleveragents.db

System Configuration:
  Default Actor: anthropic/claude-sonnet-4-20250514
  Default Project: None
  Execution Environment: development
  Log Level: INFO

Feature Flags:
  A2A Protocol: enabled
  Container Execution: enabled
  Cost Budgets: enabled
  Safety Profiles: enabled
```

**What's Happening:**
The `info` command performs a regular initialization of the application to gather comprehensive system information. It reads configuration files, checks the database, and verifies feature availability. This command takes slightly longer than `version` but provides much more detailed information about your system setup.

### Step 3: Get Machine-Readable Version Information (JSON)

For automation and scripting, use the JSON output format with the `version` command.

```bash
$ agents --format json version
```

**Expected Output:**
```json
{
  "status": "success",
  "data": {
    "version": "3.6.0",
    "build_date": "2026-04-19",
    "python_version": "3.13.0",
    "platform": "linux",
    "git_commit": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "git_branch": "main"
  }
}
```

**What's Happening:**
The `--format json` flag tells CleverAgents to output the response as JSON. This is useful for parsing the output in scripts or integrating with other tools. The JSON envelope includes a status field and a data field containing the actual information.

### Step 4: Get Machine-Readable System Information (JSON)

Get comprehensive system information in JSON format for programmatic access.

```bash
$ agents --format json info
```

**Expected Output:**
```json
{
  "status": "success",
  "data": {
    "version": {
      "version": "3.6.0",
      "build_date": "2026-04-19",
      "python_version": "3.13.0",
      "platform": "linux"
    },
    "installation": {
      "installation_path": "/usr/local/lib/python3.13/site-packages/cleveragents",
      "config_directory": "/home/user/.cleveragents",
      "database_location": "/home/user/.cleveragents/cleveragents.db"
    },
    "configuration": {
      "default_actor": "anthropic/claude-sonnet-4-20250514",
      "default_project": null,
      "execution_environment": "development",
      "log_level": "INFO"
    },
    "features": {
      "a2a_protocol": true,
      "container_execution": true,
      "cost_budgets": true,
      "safety_profiles": true
    }
  }
}
```

**What's Happening:**
The JSON output is structured hierarchically, making it easy to parse and extract specific information. Each section corresponds to a category of system information.

### Step 5: Run System Diagnostics

The `diagnostics` command performs comprehensive system checks and generates a detailed report.

```bash
$ agents diagnostics
```

**Expected Output:**
```
CleverAgents System Diagnostics Report
======================================

Timestamp: 2026-04-19T10:30:45Z
System: linux (x86_64)
Python: 3.13.0

✓ Installation Check
  - Package installed: YES
  - Installation path: /usr/local/lib/python3.13/site-packages/cleveragents
  - Version: 3.6.0

✓ Configuration Check
  - Config directory exists: YES
  - Config file readable: YES
  - Database accessible: YES

✓ Database Check
  - Database file exists: YES
  - Database version: 3.6.0
  - Tables initialized: YES
  - Connection pool: healthy

✓ Actor Registry Check
  - Actors available: 12
  - Default actor configured: YES
  - Actor connectivity: OK

✓ Resource System Check
  - Resource types registered: 45
  - Resource handlers loaded: 45
  - Resource validation: OK

✓ Skill System Check
  - Skills available: 156
  - Skill registry: healthy
  - Skill validation: OK

✓ Tool System Check
  - Tools available: 89
  - Tool registry: healthy
  - Tool validation: OK

✓ Network Connectivity Check
  - DNS resolution: OK
  - API connectivity: OK
  - Server connectivity: OK

Summary:
  Total checks: 8
  Passed: 8
  Failed: 0
  Warnings: 0
  Status: HEALTHY
```

**What's Happening:**
The `diagnostics` command performs a comprehensive system health check. It verifies installation integrity, configuration validity, database connectivity, and the availability of all major subsystems. This is useful for troubleshooting issues or verifying that your CleverAgents installation is properly configured.

### Step 6: Get Machine-Readable Diagnostics (JSON)

For automated monitoring and alerting, use JSON format with the diagnostics command.

```bash
$ agents --format json diagnostics
```

**Expected Output:**
```json
{
  "status": "success",
  "data": {
    "timestamp": "2026-04-19T10:30:45Z",
    "system": {
      "platform": "linux",
      "architecture": "x86_64",
      "python_version": "3.13.0"
    },
    "checks": [
      {
        "name": "Installation Check",
        "status": "passed",
        "details": {
          "package_installed": true,
          "installation_path": "/usr/local/lib/python3.13/site-packages/cleveragents",
          "version": "3.6.0"
        }
      },
      {
        "name": "Configuration Check",
        "status": "passed",
        "details": {
          "config_directory_exists": true,
          "config_file_readable": true,
          "database_accessible": true
        }
      },
      {
        "name": "Database Check",
        "status": "passed",
        "details": {
          "database_file_exists": true,
          "database_version": "3.6.0",
          "tables_initialized": true,
          "connection_pool": "healthy"
        }
      },
      {
        "name": "Actor Registry Check",
        "status": "passed",
        "details": {
          "actors_available": 12,
          "default_actor_configured": true,
          "actor_connectivity": "OK"
        }
      },
      {
        "name": "Resource System Check",
        "status": "passed",
        "details": {
          "resource_types_registered": 45,
          "resource_handlers_loaded": 45,
          "resource_validation": "OK"
        }
      },
      {
        "name": "Skill System Check",
        "status": "passed",
        "details": {
          "skills_available": 156,
          "skill_registry": "healthy",
          "skill_validation": "OK"
        }
      },
      {
        "name": "Tool System Check",
        "status": "passed",
        "details": {
          "tools_available": 89,
          "tool_registry": "healthy",
          "tool_validation": "OK"
        }
      },
      {
        "name": "Network Connectivity Check",
        "status": "passed",
        "details": {
          "dns_resolution": "OK",
          "api_connectivity": "OK",
          "server_connectivity": "OK"
        }
      }
    ],
    "summary": {
      "total_checks": 8,
      "passed": 8,
      "failed": 0,
      "warnings": 0,
      "status": "HEALTHY"
    }
  }
}
```

**What's Happening:**
The JSON format provides structured diagnostic data that can be easily parsed by monitoring systems, dashboards, or automated alerting tools. Each check includes its status and detailed information about what was verified.

### Step 7: Compare Output Formats

You can also use YAML format for human-readable structured output.

```bash
$ agents --format yaml version
```

**Expected Output:**
```yaml
status: success
data:
  version: 3.6.0
  build_date: '2026-04-19'
  python_version: 3.13.0
  platform: linux
  git_commit: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
  git_branch: main
```

**What's Happening:**
YAML format provides a middle ground between plain text and JSON - it's human-readable but also machine-parseable. This is useful when you want structured output but prefer YAML over JSON.

## Understanding Fast-Path vs Regular Command Behavior

### Fast-Path Commands
The `version` command uses a fast-path execution:
- **Execution time**: ~50-100ms
- **Initialization**: Minimal (no database, no configuration loading)
- **Use case**: Quick version checks, CI/CD pipelines, automated scripts
- **Reliability**: Very high (no external dependencies)

### Regular Commands
The `info` and `diagnostics` commands use regular initialization:
- **Execution time**: ~500-2000ms (depending on system complexity)
- **Initialization**: Full application startup (database, configuration, registries)
- **Use case**: Detailed system information, troubleshooting, verification
- **Reliability**: High (requires working installation)

## Complete Interaction Log
<details>
<summary>Click to see the full CleverAgents session log</summary>

```
[2026-04-19T10:30:00Z] Starting CleverAgents CLI session...
[2026-04-19T10:30:00Z] User: agents version
[2026-04-19T10:30:00Z] CleverAgents: CleverAgents v3.6.0
[2026-04-19T10:30:00Z] CleverAgents: Build: 2026-04-19
[2026-04-19T10:30:00Z] CleverAgents: Python: 3.13.0
[2026-04-19T10:30:02Z] User: agents info
[2026-04-19T10:30:02Z] CleverAgents: CleverAgents System Information
[2026-04-19T10:30:02Z] CleverAgents: ================================
[2026-04-19T10:30:02Z] CleverAgents: Version Information:
[2026-04-19T10:30:02Z] CleverAgents:   Version: 3.6.0
[2026-04-19T10:30:02Z] CleverAgents:   Build Date: 2026-04-19
[2026-04-19T10:30:02Z] CleverAgents:   Python Version: 3.13.0
[2026-04-19T10:30:02Z] CleverAgents:   Platform: linux
[2026-04-19T10:30:02Z] CleverAgents: Installation Details:
[2026-04-19T10:30:02Z] CleverAgents:   Installation Path: /usr/local/lib/python3.13/site-packages/cleveragents
[2026-04-19T10:30:02Z] CleverAgents:   Configuration Directory: ~/.cleveragents
[2026-04-19T10:30:02Z] CleverAgents:   Database Location: ~/.cleveragents/cleveragents.db
[2026-04-19T10:30:02Z] CleverAgents: System Configuration:
[2026-04-19T10:30:02Z] CleverAgents:   Default Actor: anthropic/claude-sonnet-4-20250514
[2026-04-19T10:30:02Z] CleverAgents: Default Project: None
[2026-04-19T10:30:02Z] CleverAgents:   Execution Environment: development
[2026-04-19T10:30:02Z] CleverAgents:   Log Level: INFO
[2026-04-19T10:30:02Z] CleverAgents: Feature Flags:
[2026-04-19T10:30:02Z] CleverAgents:   A2A Protocol: enabled
[2026-04-19T10:30:02Z] CleverAgents:   Container Execution: enabled
[2026-04-19T10:30:02Z] CleverAgents:   Cost Budgets: enabled
[2026-04-19T10:30:02Z] CleverAgents:   Safety Profiles: enabled
[2026-04-19T10:30:03Z] User: agents --format json version
[2026-04-19T10:30:03Z] CleverAgents: {"status": "success", "data": {"version": "3.6.0", ...}}
[2026-04-19T10:30:05Z] User: agents --format json info
[2026-04-19T10:30:05Z] CleverAgents: {"status": "success", "data": {...}}
[2026-04-19T10:30:07Z] User: agents diagnostics
[2026-04-19T10:30:07Z] CleverAgents: CleverAgents System Diagnostics Report
[2026-04-19T10:30:07Z] CleverAgents: ======================================
[2026-04-19T10:30:07Z] CleverAgents: [Diagnostic checks output...]
[2026-04-19T10:30:10Z] User: agents --format json diagnostics
[2026-04-19T10:30:10Z] CleverAgents: {"status": "success", "data": {...}}
[2026-04-19T10:30:12Z] Session completed successfully.
```
</details>

## Key Takeaways
- **Version command** is the fastest way to check your CleverAgents installation - use it for quick verification
- **Info command** provides comprehensive system configuration and feature information - use it for setup verification
- **Diagnostics command** performs health checks on all major subsystems - use it for troubleshooting
- **Output formats** (JSON, YAML, plain text) allow you to choose the best format for your use case
- **Fast-path execution** in the version command makes it ideal for CI/CD pipelines and automated scripts
- **Regular initialization** in info and diagnostics commands ensures accurate system state reporting

## Try It Yourself
Now that you understand these commands, try these variations:

- Run `agents version --help` to see all available options
- Run `agents info --help` to see configuration options
- Run `agents diagnostics --help` to see diagnostic options
- Combine with other flags: `agents --format yaml info`
- Use in scripts: `VERSION=$(agents --format json version | jq -r '.data.version')`
- Monitor system health: `agents --format json diagnostics | jq '.data.summary.status'`

## Related Examples
- [Mastering Output Format Flags in CleverAgents CLI](output-format-flags.md) — Learn more about output formatting options
- [CleverAgents CLI Basics](cleveragents-cli-basics.md) — Get started with the CLI
- [Server Connection and A2A Protocol Integration](server-and-a2a-integration.md) — Learn about server connectivity

---
*This example was automatically generated and verified by the CleverAgents UAT system.*
*Feature area: CLI System Commands | Test cycle: 1 | Generated: 2026-04-19*
