cleveragents-core/docs/showcase/cli-tools/cli-version-info-diagnostics.md

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.

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

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

$ agents --format json version

Expected Output:

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

$ agents --format json info

Expected Output:

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

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

$ agents --format json diagnostics

Expected Output:

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

$ agents --format yaml version

Expected Output:

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

Click to see the full CleverAgents session log

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

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 — Learn more about output formatting options
• CleverAgents CLI Basics — Get started with the CLI
• Server Connection and A2A Protocol Integration — 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