cleveragents-core/docs/showcase/cli-tools/cleveragents-cli-basics.md

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:

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

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

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

$ python -m cleveragents --format json version

Actual Output:

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

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

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

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

$ python -m cleveragents diagnostics --check
# Exits with code 1 if any check has ERROR status

For machine-readable output:

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

# ✅ 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

#!/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

Click to see the full verified command session

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

---

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).
• Both --help and --version use a fast-path eager exit that avoids loading subcommand modules, resulting in instant response times. The version, info, and diagnostics commands are lightweight introspection tools but do not benefit from the fast-path optimization.

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
• Showcase Index

---

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