docs(showcase): showcase CLI version/info/diagnostics commands
Created comprehensive showcase documentation for CLI version, info, and diagnostics commands Documented fast-path vs regular command behavior Included verified outputs and machine-readable JSON/YAML examples Registered the showcase entry in docs/showcase/examples.json Added BDD tests for the showcase documentation Closes #7592
This commit is contained in:
Forgejo
@@ -0,0 +1,435 @@
|
||||
# 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*
|
||||
@@ -1,5 +1,26 @@
|
||||
{
|
||||
"examples": [
|
||||
{
|
||||
"title": "Understanding CleverAgents CLI Version, Info, and Diagnostics Commands",
|
||||
"category": "cli-tools",
|
||||
"path": "cli-tools/cli-version-info-diagnostics.md",
|
||||
"feature": "Version info diagnostics fast-path regular initialization",
|
||||
"commands": [
|
||||
"agents version",
|
||||
"agents info",
|
||||
"agents diagnostics",
|
||||
"agents --format json version",
|
||||
"agents --format json info",
|
||||
"agents --format json diagnostics",
|
||||
"agents --format yaml version",
|
||||
"agents --format yaml info",
|
||||
"agents --format yaml diagnostics"
|
||||
],
|
||||
"complexity": "beginner",
|
||||
"educational_value": "high",
|
||||
"generated_by": "uat-tester",
|
||||
"generated_at": "2026-04-19"
|
||||
},
|
||||
{
|
||||
"title": "Mastering Output Format Flags in CleverAgents CLI",
|
||||
"category": "cli-tools",
|
||||
|
||||
@@ -0,0 +1,98 @@
|
||||
Feature: CLI Version, Info, and Diagnostics Commands Showcase
|
||||
As a CleverAgents user
|
||||
I want to understand the version, info, and diagnostics commands
|
||||
So that I can verify my installation and troubleshoot issues
|
||||
|
||||
Background:
|
||||
Given the CleverAgents CLI is installed and available
|
||||
|
||||
Scenario: Display version information using fast-path execution
|
||||
When I run the command "agents version"
|
||||
Then the output should contain "CleverAgents"
|
||||
And the output should contain a version number
|
||||
And the command should complete quickly (within 200ms)
|
||||
|
||||
Scenario: Display version information in JSON format
|
||||
When I run the command "agents --format json version"
|
||||
Then the output should be valid JSON
|
||||
And the JSON should have a "status" field with value "success"
|
||||
And the JSON should have a "data" field containing version information
|
||||
And the JSON data should contain "version" field
|
||||
And the JSON data should contain "python_version" field
|
||||
|
||||
Scenario: Display version information in YAML format
|
||||
When I run the command "agents --format yaml version"
|
||||
Then the output should be valid YAML
|
||||
And the YAML should have a "status" field with value "success"
|
||||
And the YAML should have a "data" field containing version information
|
||||
|
||||
Scenario: Display comprehensive system information
|
||||
When I run the command "agents info"
|
||||
Then the output should contain "CleverAgents System Information"
|
||||
And the output should contain "Version Information"
|
||||
And the output should contain "Installation Details"
|
||||
And the output should contain "System Configuration"
|
||||
And the output should contain "Feature Flags"
|
||||
|
||||
Scenario: Display system information in JSON format
|
||||
When I run the command "agents --format json info"
|
||||
Then the output should be valid JSON
|
||||
And the JSON should have a "status" field with value "success"
|
||||
And the JSON data should contain "version" field
|
||||
And the JSON data should contain "installation" field
|
||||
And the JSON data should contain "configuration" field
|
||||
And the JSON data should contain "features" field
|
||||
|
||||
Scenario: Run system diagnostics
|
||||
When I run the command "agents diagnostics"
|
||||
Then the output should contain "CleverAgents System Diagnostics Report"
|
||||
And the output should contain "Installation Check"
|
||||
And the output should contain "Configuration Check"
|
||||
And the output should contain "Database Check"
|
||||
And the output should contain "Summary"
|
||||
And the output should contain "Status"
|
||||
|
||||
Scenario: Run diagnostics in JSON format
|
||||
When I run the command "agents --format json diagnostics"
|
||||
Then the output should be valid JSON
|
||||
And the JSON should have a "status" field with value "success"
|
||||
And the JSON data should contain "timestamp" field
|
||||
And the JSON data should contain "system" field
|
||||
And the JSON data should contain "checks" field
|
||||
And the JSON data should contain "summary" field
|
||||
|
||||
Scenario: Verify fast-path vs regular command behavior
|
||||
When I run the command "agents version"
|
||||
Then the command should complete quickly (within 200ms)
|
||||
When I run the command "agents info"
|
||||
Then the command should take longer than version command
|
||||
When I run the command "agents diagnostics"
|
||||
Then the command should take longer than version command
|
||||
|
||||
Scenario: Verify output format consistency
|
||||
When I run the command "agents --format json version"
|
||||
And I run the command "agents --format json info"
|
||||
And I run the command "agents --format json diagnostics"
|
||||
Then all JSON outputs should have a "status" field
|
||||
And all JSON outputs should have a "data" field
|
||||
|
||||
Scenario: Verify showcase documentation exists
|
||||
Given the showcase documentation file exists at "docs/showcase/cli-tools/cli-version-info-diagnostics.md"
|
||||
When I read the documentation file
|
||||
Then it should contain "Understanding CleverAgents CLI Version, Info, and Diagnostics Commands"
|
||||
And it should contain "version" command explanation
|
||||
And it should contain "info" command explanation
|
||||
And it should contain "diagnostics" command explanation
|
||||
And it should contain "Fast-Path vs Regular Command Behavior" section
|
||||
And it should contain JSON output examples
|
||||
And it should contain YAML output examples
|
||||
|
||||
Scenario: Verify showcase is registered in examples.json
|
||||
Given the showcase examples registry exists at "docs/showcase/examples.json"
|
||||
When I read the examples registry
|
||||
Then it should contain an entry for "Understanding CleverAgents CLI Version, Info, and Diagnostics Commands"
|
||||
And the entry should have category "cli-tools"
|
||||
And the entry should have path "cli-tools/cli-version-info-diagnostics.md"
|
||||
And the entry should list version, info, and diagnostics commands
|
||||
And the entry should have complexity "beginner"
|
||||
And the entry should have educational_value "high"
|
||||
Reference in New Issue
Block a user