Skip to content

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

Python

recover README from the last PR

yuhao4f92119ff9dc
diff --git a/README.md b/README.md
index 267ffb5ea..0e666453b 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,26 @@
<h1 align="center"><img src="assets/icon.png" alt="" width="64" style="vertical-align: middle;">&nbsp; CLI-Anything: Making ALL Software Agent-Native</h1>
+<p align="center">
+ <strong>Today's Software Serves HumansπŸ‘¨β€πŸ’». Tomorrow's Users will be AgentsπŸ€–.<br>
+CLI-Anything: Bridging the Gap Between AI Agents and the World's Software</strong><br>
+</p>
+
+<p align="center">
+ <a href="#-quick-start"><img src="https://img.shields.io/badge/Quick_Start-5_min-blue?style=for-the-badge" alt="Quick Start"></a>
+ <a href="#-demonstrations"><img src="https://img.shields.io/badge/Demos-8_Apps-green?style=for-the-badge" alt="Demos"></a>
+ <a href="#-test-results"><img src="https://img.shields.io/badge/Tests-1%2C298_Passing-brightgreen?style=for-the-badge" alt="Tests"></a>
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="License"></a>
+</p>
+<p align="center">
+ <img src="https://img.shields.io/badge/python-β‰₯3.10-blue?logo=python&logoColor=white" alt="Python">
+ <img src="https://img.shields.io/badge/click-β‰₯8.0-green" alt="Click">
+ <img src="https://img.shields.io/badge/pytest-100%25_pass-brightgreen" alt="Pytest">
+ <img src="https://img.shields.io/badge/coverage-unit_%2B_e2e-orange" alt="Coverage">
+ <img src="https://img.shields.io/badge/output-JSON_%2B_Human-blueviolet" alt="Output">
+ <a href="https://github.com/HKUDS/.github/blob/main/profile/README.md"><img src="https://img.shields.io/badge/Feishu-Group-E9DBFC?style=flat&logo=feishu&logoColor=white" alt="Feishu"></a>
+<a href="https://github.com/HKUDS/.github/blob/main/profile/README.md"><img src="https://img.shields.io/badge/WeChat-Group-C5EAB4?style=flat&logo=wechat&logoColor=white" alt="WeChat"></a>
+</p>
**One Command Line**: Make any software agent-ready for OpenClaw, nanobot, Cursor, Claude Code, etc.&nbsp;&nbsp;[**δΈ­ζ–‡ζ–‡ζ‘£**](README_CN.md)
@@ -8,6 +28,9 @@
<img src="assets/cli-typing.gif" alt="CLI-Anything typing demo" width="800">
</p>
+<p align="center">
+ <img src="assets/teaser.png" alt="CLI-Anything Teaser" width="800">
+</p>
---
@@ -62,7 +85,6 @@ That's it. The plugin is now available in your Claude Code session.
```
This runs the full pipeline:
-
1. πŸ” **Analyze** β€” Scans source code, maps GUI actions to APIs
2. πŸ“ **Design** β€” Architects command groups, state model, output formats
3. πŸ”¨ **Implement** β€” Builds Click CLI with REPL, JSON output, undo/redo
@@ -86,7 +108,8 @@ cli-anything-gimp --json layer add -n "Background" --type solid --color "#1a1a2e
cli-anything-gimp
```
-**Alternative: Manual Installation**
+<details>
+<summary><strong>Alternative: Manual Installation</strong></summary>
If you prefer not to use the marketplace:
@@ -101,7 +124,7 @@ cp -r CLI-Anything/cli-anything-plugin ~/.claude/plugins/cli-anything
/reload-plugins
```
-
+</details>
---
@@ -127,6 +150,7 @@ cp -r CLI-Anything/cli-anything-plugin ~/.claude/plugins/cli-anything
| **πŸ”¬ Scientific Computing** | Automate research workflows, simulations, and complex calculations | ImageJ, FreeCAD, QGIS, ParaView, Gephi, LibreCAD, Stellarium, KiCad, JASP, Jamovi |
| **🏒 Enterprise & Office** | Convert business applications and productivity tools into agent-accessible systems | NextCloud, GitLab, Grafana, Mattermost, LibreOffice, AppFlowy, NocoDB, Odoo (Community), Plane, ERPNext |
| **✨ AI Content Generation** | Generate professional deliverables (slides, docs, diagrams, websites, research reports) through AI-powered cloud APIs | [AnyGen](https://www.anygen.io), Gamma, Beautiful.ai, Tome |
+
---
## CLI-Anything's Key Features
@@ -142,7 +166,7 @@ AI agents are great at reasoning but terrible at using real professional softwar
| πŸ’Έ "UI automation breaks constantly" | No screenshots, no clicking, no RPA fragility. Pure command-line reliability with structured interfaces |
| πŸ“Š "Agents need structured data" | Built-in JSON output for seamless agent consumption + human-readable formats for debugging |
| πŸ”§ "Custom integrations are expensive" | One Claude plugin auto-generates CLIs for ANY codebase through proven 7-phase pipeline |
-| ⚑ "Prototype vs Production gap" | 1,361+ tests with real software validation. Battle-tested across 9 major applications |
+| ⚑ "Prototype vs Production gap" | 1,298+ tests with real software validation. Battle-tested across 8 major applications |
---
@@ -178,83 +202,138 @@ CLI-Anything can flat-out **replace GUI-based agent approaches** β€” no more scr
## ✨ βš™οΈ How CLI-Anything Works
-
-| |
-| --- |
-| |
-
+<table>
+<tr>
+<td width="50%">
### πŸ—οΈ Fully Automated 7-Phase Pipeline
-
From codebase analysis to PyPI publishing β€” the plugin handles architecture design, implementation, test planning, test writing, and documentation completely automatically.
-
+</td>
+<td width="50%">
### 🎯 Authentic Software Integration
-
Direct calls to real applications for actual rendering. LibreOffice generates PDFs, Blender renders 3D scenes, Audacity processes audio via sox. **Zero compromises**, **Zero toy implementations**.
-
+</td>
+</tr>
+<tr>
+<td width="50%">
### πŸ” Smart Session Management
-
Persistent project state with undo/redo capabilities, plus unified REPL interface (ReplSkin) that delivers consistent interactive experience across all CLIs.
-
+</td>
+<td width="50%">
### πŸ“¦ Zero-Config Installation
+Simple pip install -e . puts cli-anything-<software> directly on PATH. Agents discover tools via standard which commands. No setup, no wrappers.
-Simple pip install -e . puts cli-anything- directly on PATH. Agents discover tools via standard which commands. No setup, no wrappers.
-
-
+</td>
+</tr>
+<tr>
+<td width="50%">
### πŸ§ͺ Production-Grade Testing
-
Multi-layered validation: unit tests with synthetic data, end-to-end tests with real files and software, plus CLI subprocess verification of installed commands.
-
+</td>
+<td width="50%">
### 🐍 Clean Package Architecture
-
All CLIs organized under cli_anything.* namespace β€” conflict-free, pip-installable, with consistent naming: cli-anything-gimp, cli-anything-blender, etc.
-
+</td>
+</tr>
+</table>
---
## 🎬 Demonstrations
### 🎯 General-Purpose
-
CLI-Anything works on any software with a codebase β€” no domain restrictions or architectural limitations.
### 🏭 Professional-Grade Testing
-Tested across 9 diverse, complex open-source applications spanning creative and productivity domains previously inaccessible to AI agents.
+Tested across 8 diverse, complex open-source applications spanning creative and productivity domains previously inaccessible to AI agents.
### 🎨 Diverse Domain Coverage
-
From creative workflows (image editing, 3D modeling, vector graphics) to production tools (audio, office, live streaming, video editing).
### βœ… Full CLI Generation
-
Each application received complete, production-ready CLI interfaces β€” not demos, but comprehensive tool access preserving full capabilities.
+<table>
+<tr>
+<th align="center">Software</th>
+<th align="center">Domain</th>
+<th align="center">CLI Command</th>
+<th align="center">Backend</th>
+<th align="center">Tests</th>
+</tr>
+<tr>
+<td align="center"><strong>🎨 GIMP</strong></td>
+<td>Image Editing</td>
+<td><code>cli-anything-gimp</code></td>
+<td>Pillow + GEGL/Script-Fu</td>
+<td align="center">βœ… 107</td>
+</tr>
+<tr>
+<td align="center"><strong>🧊 Blender</strong></td>
+<td>3D Modeling & Rendering</td>
+<td><code>cli-anything-blender</code></td>
+<td>bpy (Python scripting)</td>
+<td align="center">βœ… 208</td>
+</tr>
+<tr>
+<td align="center"><strong>✏️ Inkscape</strong></td>
+<td>Vector Graphics</td>
+<td><code>cli-anything-inkscape</code></td>
+<td>Direct SVG/XML manipulation</td>
+<td align="center">βœ… 202</td>
+</tr>
+<tr>
+<td align="center"><strong>🎡 Audacity</strong></td>
+<td>Audio Production</td>
+<td><code>cli-anything-audacity</code></td>
+<td>Python wave + sox</td>
+<td align="center">βœ… 161</td>
+</tr>
+<tr>
+<td align="center"><strong>πŸ“„ LibreOffice</strong></td>
+<td>Office Suite (Writer, Calc, Impress)</td>
+<td><code>cli-anything-libreoffice</code></td>
+<td>ODF generation + headless LO</td>
+<td align="center">βœ… 158</td>
+</tr>
+<tr>
+<td align="center"><strong>πŸ“Ή OBS Studio</strong></td>
+<td>Live Streaming & Recording</td>
+<td><code>cli-anything-obs-studio</code></td>
+<td>JSON scene + obs-websocket</td>
+<td align="center">βœ… 153</td>
+</tr>
+<tr>
+<td align="center"><strong>🎞️ Kdenlive</strong></td>
+<td>Video Editing</td>
+<td><code>cli-anything-kdenlive</code></td>
+<td>MLT XML + melt renderer</td>
+<td align="center">βœ… 155</td>
+</tr>
+<tr>
+<td align="center"><strong>🎬 Shotcut</strong></td>
+<td>Video Editing</td>
+<td><code>cli-anything-shotcut</code></td>
+<td>Direct MLT XML + melt</td>
+<td align="center">βœ… 154</td>
+</tr>
+<tr>
+<td align="center" colspan="4"><strong>Total</strong></td>
+<td align="center"><strong>βœ… 1,298</strong></td>
+</tr>
+</table>
-| Software | Domain | CLI Command | Backend | Tests |
-| ------------------ | ------------------------------------ | -------------------------- | ---------------------------- | ----- |
-| **🎨 GIMP** | Image Editing | `cli-anything-gimp` | Pillow + GEGL/Script-Fu | βœ… 107 |
-| **🧊 Blender** | 3D Modeling & Rendering | `cli-anything-blender` | bpy (Python scripting) | βœ… 208 |
-| **✏️ Inkscape** | Vector Graphics | `cli-anything-inkscape` | Direct SVG/XML manipulation | βœ… 202 |
-| **🎡 Audacity** | Audio Production | `cli-anything-audacity` | Python wave + sox | βœ… 161 |
-| **πŸ“„ LibreOffice** | Office Suite (Writer, Calc, Impress) | `cli-anything-libreoffice` | ODF generation + headless LO | βœ… 158 |
-| **πŸ“Ή OBS Studio** | Live Streaming & Recording | `cli-anything-obs-studio` | JSON scene + obs-websocket | βœ… 153 |
-| **🎞️ Kdenlive** | Video Editing | `cli-anything-kdenlive` | MLT XML + melt renderer | βœ… 155 |
-| **🎬 Shotcut** | Video Editing | `cli-anything-shotcut` | Direct MLT XML + melt | βœ… 154 |
-| **✨ AnyGen** | AI Content Generation | `cli-anything-anygen` | AnyGen OpenAPI (cloud) | βœ… 63 |
-| **Total** | **βœ… 1,361** | | | |
-
-
-> **100% pass rate** across all 1,361 tests β€” 940 unit tests + 421 end-to-end tests.
+> **100% pass rate** across all 1,298 tests β€” 895 unit tests + 403 end-to-end tests.
---
@@ -262,14 +341,12 @@ Each application received complete, production-ready CLI interfaces β€” not demo
Each CLI harness undergoes rigorous multi-layered testing to ensure production reliability:
-
-| Layer | What it tests | Example |
-| ---------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------ |
-| **Unit tests** | Every core function in isolation with synthetic data | `test_core.py` β€” project creation, layer ops, filter params |
-| **E2E tests (native)** | Project file generation pipeline | Valid ODF ZIP structure, correct MLT XML, SVG well-formedness |
-| **E2E tests (true backend)** | Real software invocation + output verification | LibreOffice β†’ PDF with `%PDF-` magic bytes, Blender β†’ rendered PNG |
-| **CLI subprocess tests** | Installed command via `subprocess.run` | `cli-anything-gimp --json project new` β†’ valid JSON output |
-
+| Layer | What it tests | Example |
+|-------|---------------|---------|
+| **Unit tests** | Every core function in isolation with synthetic data | `test_core.py` β€” project creation, layer ops, filter params |
+| **E2E tests (native)** | Project file generation pipeline | Valid ODF ZIP structure, correct MLT XML, SVG well-formedness |
+| **E2E tests (true backend)** | Real software invocation + output verification | LibreOffice β†’ PDF with `%PDF-` magic bytes, Blender β†’ rendered PNG |
+| **CLI subprocess tests** | Installed command via `subprocess.run` | `cli-anything-gimp --json project new` β†’ valid JSON output |
```
================================ Test Summary ================================
@@ -281,23 +358,28 @@ libreoffice 158 passed βœ… (89 unit + 69 e2e)
obs-studio 153 passed βœ… (116 unit + 37 e2e)
kdenlive 155 passed βœ… (111 unit + 44 e2e)
shotcut 154 passed βœ… (110 unit + 44 e2e)
-anygen 63 passed βœ… (45 unit + 18 e2e)
──────────────────────────────────────────────────────────────────────────────
-TOTAL 1,361 passed βœ… 100% pass rate
+TOTAL 1,298 passed βœ… 100% pass rate
```
---
## πŸ—οΈ CLI-Anything's Architecture
-
+<p align="center">
+ <img src="assets/architecture.png" alt="CLI-Anything Architecture" width="750">
+</p>
### 🎯 Core Design Principles
1. **Authentic Software Integration** β€” The CLI generates valid project files (ODF, MLT XML, SVG) and delegates to real applications for rendering. **We build structured interfaces TO software, not replacements**.
+
2. **Flexible Interaction Models** β€” Every CLI operates in dual modes: stateful REPL for interactive agent sessions + subcommand interface for scripting/pipelines. **Run bare command β†’ enter REPL mode**.
+
3. **Consistent User Experience** β€” All generated CLIs share unified REPL interface (repl_skin.py) with branded banners, styled prompts, command history, progress indicators, and standardized formatting.
+
4. **Agent-Native Design** β€” Built-in --json flag on every command delivers structured data for machine consumption, while human-readable tables serve interactive use. **Agents discover capabilities via standard --help and which commands**.
+
5. **Zero Compromise Dependencies** β€” Real software is a hard requirement β€” no fallbacks, no graceful degradation. **Tests fail (not skip) when backends are missing, ensuring authentic functionality**.
---
@@ -332,8 +414,7 @@ cli-anything/
β”œβ”€β”€ πŸ“„ libreoffice/agent-harness/ # LibreOffice CLI (158 tests)
β”œβ”€β”€ πŸ“Ή obs-studio/agent-harness/ # OBS Studio CLI (153 tests)
β”œβ”€β”€ 🎞️ kdenlive/agent-harness/ # Kdenlive CLI (155 tests)
-β”œβ”€β”€ 🎬 shotcut/agent-harness/ # Shotcut CLI (154 tests)
-└── ✨ anygen/agent-harness/ # AnyGen CLI (63 tests)
+└── 🎬 shotcut/agent-harness/ # Shotcut CLI (154 tests)
```
Each `agent-harness/` contains an installable Python package under `cli_anything.<software>/` with Click CLI, core modules, utils (including `repl_skin.py` and backend wrapper), and comprehensive tests.
@@ -342,14 +423,12 @@ Each `agent-harness/` contains an installable Python package under `cli_anything
## 🎯 Plugin Commands
-
-| Command | Description |
-| ------------------------------------------------ | -------------------------------------------------------------- |
-| `/cli-anything <software-path-or-repo>` | Build complete CLI harness β€” all 7 phases |
-| `/cli-anything:refine <software-path> [focus]` | Refine an existing harness β€” expand coverage with gap analysis |
-| `/cli-anything:test <software-path-or-repo>` | Run tests and update TEST.md with results |
-| `/cli-anything:validate <software-path-or-repo>` | Validate against HARNESS.md standards |
-
+| Command | Description |
+|---------|-------------|
+| `/cli-anything <software-path-or-repo>` | Build complete CLI harness β€” all 7 phases |
+| `/cli-anything:refine <software-path> [focus]` | Refine an existing harness β€” expand coverage with gap analysis |
+| `/cli-anything:test <software-path-or-repo>` | Run tests and update TEST.md with results |
+| `/cli-anything:validate <software-path-or-repo>` | Validate against HARNESS.md standards |
### Examples
@@ -440,17 +519,15 @@ The playbook distills key insights from successfully building all 8 diverse, pro
### Critical Lessons
+| Lesson | Description |
+|--------|-------------|
+| **Use the real software** | The CLI MUST call the actual application for rendering. No Pillow replacements for GIMP, no custom renderers for Blender. Generate valid project files β†’ invoke the real backend. |
+| **The Rendering Gap** | GUI apps apply effects at render time. If your CLI manipulates project files but uses a naive export tool, effects get silently dropped. Solution: native renderer β†’ filter translation β†’ render script. |
+| **Filter Translation** | When mapping effects between formats (MLT β†’ ffmpeg), watch for duplicate filter merging, interleaved stream ordering, parameter space differences, and unmappable effects. |
+| **Timecode Precision** | Non-integer frame rates (29.97fps) cause cumulative rounding. Use `round()` not `int()`, integer arithmetic for display, and Β±1 frame tolerance in tests. |
+| **Output Verification** | Never trust that export worked because it exited 0. Verify: magic bytes, ZIP/OOXML structure, pixel analysis, audio RMS levels, duration checks. |
-| Lesson | Description |
-| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Use the real software** | The CLI MUST call the actual application for rendering. No Pillow replacements for GIMP, no custom renderers for Blender. Generate valid project files β†’ invoke the real backend. |
-| **The Rendering Gap** | GUI apps apply effects at render time. If your CLI manipulates project files but uses a naive export tool, effects get silently dropped. Solution: native renderer β†’ filter translation β†’ render script. |
-| **Filter Translation** | When mapping effects between formats (MLT β†’ ffmpeg), watch for duplicate filter merging, interleaved stream ordering, parameter space differences, and unmappable effects. |
-| **Timecode Precision** | Non-integer frame rates (29.97fps) cause cumulative rounding. Use `round()` not `int()`, integer arithmetic for display, and Β±1 frame tolerance in tests. |
-| **Output Verification** | Never trust that export worked because it exited 0. Verify: magic bytes, ZIP/OOXML structure, pixel analysis, audio RMS levels, duration checks. |
-
-
-> See the full methodology: `[cli-anything-plugin/HARNESS.md](cli-anything-plugin/HARNESS.md)`
+> See the full methodology: [`cli-anything-plugin/HARNESS.md`](cli-anything-plugin/HARNESS.md)
---
@@ -500,7 +577,7 @@ CLI_ANYTHING_FORCE_INSTALLED=1 python3 -m pytest cli_anything/<software>/tests/
We welcome contributions! CLI-Anything is designed to be extensible:
-- **New software targets** β€” Use the plugin to generate a CLI for any software with a codebase, then submit your harness via `[cli-anything-plugin/PUBLISHING.md](cli-anything-plugin/PUBLISHING.md)`.
+- **New software targets** β€” Use the plugin to generate a CLI for any software with a codebase, then submit your harness via [`cli-anything-plugin/PUBLISHING.md`](cli-anything-plugin/PUBLISHING.md).
- **Methodology improvements** β€” PRs to `HARNESS.md` that encode new lessons learned
- **Plugin enhancements** β€” New commands, phase improvements, better validation
- **Test coverage** β€” More E2E scenarios, edge cases, workflow tests
@@ -518,17 +595,14 @@ We welcome contributions! CLI-Anything is designed to be extensible:
## πŸ“– Documentation
-
-| Document | Description |
-| ------------------------------------------------------------------------ | ------------------------------------------------ |
-| `[cli-anything-plugin/HARNESS.md](cli-anything-plugin/HARNESS.md)` | The methodology SOP β€” single source of truth |
-| `[cli-anything-plugin/README.md](cli-anything-plugin/README.md)` | Plugin documentation β€” commands, options, phases |
-| `[cli-anything-plugin/QUICKSTART.md](cli-anything-plugin/QUICKSTART.md)` | 5-minute getting started guide |
-| `[cli-anything-plugin/PUBLISHING.md](cli-anything-plugin/PUBLISHING.md)` | Distribution and publishing guide |
-
+| Document | Description |
+|----------|-------------|
+| [`cli-anything-plugin/HARNESS.md`](cli-anything-plugin/HARNESS.md) | The methodology SOP β€” single source of truth |
+| [`cli-anything-plugin/README.md`](cli-anything-plugin/README.md) | Plugin documentation β€” commands, options, phases |
+| [`cli-anything-plugin/QUICKSTART.md`](cli-anything-plugin/QUICKSTART.md) | 5-minute getting started guide |
+| [`cli-anything-plugin/PUBLISHING.md`](cli-anything-plugin/PUBLISHING.md) | Distribution and publishing guide |
Each generated harness also includes:
-
- `<SOFTWARE>.md` β€” Architecture SOP specific to that application
- `tests/TEST.md` β€” Test plan and results documentation
@@ -538,7 +612,17 @@ Each generated harness also includes:
If CLI-Anything helps make your software Agent-native, give us a star! ⭐
-
+<!-- Uncomment when published:
+<div align="center">
+ <a href="https://star-history.com/#HKUDS/CLI-Anything&Date">
+ <picture>
+ <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=HKUDS/CLI-Anything&type=Date&theme=dark" />
+ <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=HKUDS/CLI-Anything&type=Date" />
+ <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=HKUDS/CLI-Anything&type=Date" />
+ </picture>
+ </a>
+</div>
+-->
---
@@ -548,18 +632,19 @@ MIT License β€” free to use, modify, and distribute.
---
-
+<div align="center">
**CLI-Anything** β€” *Make any software with a codebase Agent-native.*
-A methodology for the age of AI agents | 9 professional software demos | 1,361 passing tests
+<sub>A methodology for the age of AI agents | 8 professional software demos | 1,298 passing tests</sub>
-
+<br>
+<img src="assets/icon.png" alt="CLI-Anything Icon" width="80">
+</div>
-
-
-
-*Thanks for visiting ✨ CLI-Anything!*
-
+<p align="center">
+ <em> Thanks for visiting ✨ CLI-Anything!</em><br><br>
+ <img src="https://visitor-badge.laobi.icu/badge?page_id=HKUDS.CLI-Anything&style=for-the-badge&color=00d4ff" alt="Views">
+</p>