# 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 '. Actors only: provider/model flags were removed. Use actors instead. Built-ins are /; custom actors use local/. 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
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 '. Actors only: provider/model flags were removed. Use actors instead. Built-ins are /; custom actors use local/. 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`). - 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