## File: README.md
CLI-Anything: Making ALL Software Agent-Native
**๐ [CLI-Hub](https://hkuds.github.io/CLI-Anything/)**: `pip install cli-anything-hub` then `cli-hub install ` โ browse, install, and manage all community-built CLIs. Want to add your own? [Open a PR](https://github.com/HKUDS/CLI-Anything/blob/main/CONTRIBUTING.md) โ the hub updates instantly.
**๐ฌ [See Demos](#-real-world-demos)**: Watch AI agents use generated CLIs plus preview, live preview, and trajectory loops to produce real artifacts โ CAD builds, 3D scenes, diagrams, gameplay, subtitles, and more.
**๐ [Become a Contributor, or Request a CLI]**: [Join us](https://github.com/HKUDS/CLI-Anything/issues/new?template=contributor-signup.yml)! Sign up to build a new CLI harness โ once reviewed and merged, you'll gain access as one of our community contributors! Wish CLI-Anything supported a specific software or service? Submit a [wishlist request](https://github.com/HKUDS/CLI-Anything/issues/new?template=cli-wishlist.yml)!
**One Command Line**: Make any software agent-ready for Pi, OpenClaw, nanobot, Cursor, Claude Code, etc. [**ไธญๆๆๆกฃ**](README_CN.md) | [**ๆฅๆฌ่ชใใญใฅใกใณใ**](README_JA.md) | [**Deutsch**](README_DE.md)
---
## ๐ฐ News
> Thanks to all invaluable efforts from the community! More updates continuously on the way everyday..
- **2026-05-30** ๐งญ **Hermes skill** proposed (#320), adding a CLI-Anything orchestration skill with installer scripts and HARNESS fallback guidance. ๐บ๏ธ **ArcGIS Pro** was proposed for the public registry (#318) as a Windows/ArcPy CLI for cartography, geoprocessing, feature editing, and live-Pro MCP workflows.
- **2026-05-27** ๐ง **CLI-Hub** registry date updates now handle `python -m pip` install commands (#312), improving package-date detection for registry automation.
- **2026-05-23** ๐ **Obsidian Agent CLI** was proposed for the public registry (#307), bringing a PyPI-installed Obsidian automation CLI with persistent agent memory workflows and a pinned skill link.
- **2026-05-21** ๐ **Sketch CLI** token-file handling was hardened against path traversal and symlink escapes (#304).
- **2026-05-20** ๐ **Joplin CLI** was proposed (#300) with notebooks, notes, to-dos, tags, attachments, search/sync, import/export, server/E2EE helpers, full docs, packaged skill docs, and a 134-test validation baseline.
- **2026-05-20** ๐๏ธ **Rekordbox CLI** merged (#252) with guarded SQLCipher write paths, backup-required forced writes, smoke coverage, and root skill sync. ๐ **Calibre CLI** merged (#223) with library/search/metadata/conversion/export workflows, 41 unit tests, real-Calibre E2E evidence, and root skill validation. ๐ง **3MF CLI** merged (#209) with mesh inspection, hole resizing, repair, comparison, and preserved triangle attributes. ๐๏ธ **MiniMax CLI** merged (#189) with chat/TTS workflows, JSON-safe model/voice listing, REPL quote handling, and smoke/E2E coverage. ๐ฎ **UEAtelier** joined the registry (#297) as an Unreal Editor MCP self-extension workbench with a Python CLI proxy.
- **2026-05-19** ๐ ๏ธ Existing harnesses got a quality/security pass โ **Zoom** downloads recordings from direct URLs (#294), **Obsidian** search now uses the Local REST API vendor content types (#289), **LibreOffice** headless conversion is more robust on macOS (#290), and XML/SVG/ODF/MLT/MusicXML/CSL parsing now routes untrusted input through `defusedxml` (#296).
- **2026-05-18** ๐ README presentation refreshed with the Trendshift badge and centered project header polish (#285, #286), keeping the landing section focused on discovery and project momentum.
- **2026-05-17** ๐ **CLI-Hub** registry handling was hardened (#281) โ registry entries are now copied before `_source` tagging, preventing cached or mocked registry data from being mutated in place.
- **2026-05-16** ๐ง **n8n** received the REPL banner crash fix that later merged into main (#280), restoring the no-subcommand interactive startup path with regression coverage.
Earlier news (Apr 10โ18)
- **2026-04-18** ๐งฉ **All SKILL.md files are now being unified under the top-level `skills/` directory** โ every CLI skill can be installed from one canonical source with `npx skills add HKUDS/CLI-Anything --skill -g -y`. We also added root-skill validation CI, synced contribution / PR docs and REPL skill-path hints to the new layout, and refreshed the **CLI-Hub** install-first frontend around the new `npx skills` flow.
- **2026-04-17** ๐ **CLI-Hub** received another install UX pass โ public registry metadata and skill coverage were tightened, visit counting was corrected, and the web hub was further refined. ๐งช **Shotcut** render output duration was fixed (#92). ๐ **SKILL** contribution paths were corrected for the new docs flow (#224), and the skill generator now safely handles empty intros (#203).
- **2026-04-16** ๐บ๏ธ **QGIS CLI** merged (#207) โ a full GIS / map authoring harness landed. ๐งฌ **UniMol Tools CLI** merged (#219) for molecular modeling workflows. ๐ **CLI-Hub** also added more public CLIs, including **py4csr**, refreshed its generated meta-skill, corrected SKILL contribution docs, and fixed `apt-get` package extraction in skill generation (#204).
- **2026-04-16** ๐ **Unreal Insights CLI** expanded โ added background capture session control (`capture start/status/snapshot/stop`), engine-root-matched `UnrealInsights.exe` resolution/build flows, and refreshed docs/tests for the new orchestration workflow.
- **2026-04-15** ๐ **CLI-Hub** updated to **v0.2.0** โ the PyPI package now supports public CLIs from multiple install sources (`pip`, `npm`, `brew`, bundled/system tools), backed by a new `public_registry.json`. The Hub frontend was redesigned with separate **CLI-Anything CLIs** and **Public CLIs** decks, and live end-to-end checks now cover real install, update, and uninstall flows across both pip and npm packages.
- **2026-04-14** ๐งญ **Safari CLI** merged (#212) and added to the Hub registry โ browser automation via `safari-mcp`. ๐ฌ **Kdenlive** also received compatibility fixes for Gen 5 project output and invalid project generation.
- **2026-04-13** ๐ **Obsidian CLI** merged (#211) โ knowledge management harness via the Local REST API, with 48 unit tests and 7 E2E tests. โ๏ธ **Eth2-Quickstart CLI** merged (#195) โ Ethereum staking node management harness. ๐ **Zotero CLI** updated to v0.4.1 (#201) โ now shipped from its standalone repo, and CLI-Hub gained support for remote `skill_md` URLs.
- **2026-04-11** ๐ **n8n CLI** merged (#188) โ workflow automation harness for self-hosted automation flows. ๐ง **Exa CLI** fix (#205) added the `x-exa-integration` header for usage tracking. ๐ฆ **CLI-Hub** also gained its PyPI auto-publish workflow and package refresh pipeline.
- **2026-04-10** ๐ฆ **CLI-Hub package manager** launched โ `pip install cli-anything-hub` to browse, search, install, update, and uninstall CLI-Anything harnesses from one command. The web Hub also shipped its first install-focused frontend refresh and "Empower yourself" toolkit card.
Earlier news (Apr 1โ9)
- **2026-04-09** ๐งน Cleanup and docs pass (#200) โ fixed Openscreen test subtotals, added Openscreen to the Chinese README and project structure, and clarified `/cli-anything` command syntax in the docs.
- **2026-04-08** ๐ฌ **Openscreen CLI** merged (#183) โ screen recording editor harness with 101 tests. โ๏ธ **CloudAnalyzer CLI** merged (#181) โ cloud cost analysis harness with 27 commands. ๐ **SeaClip / PM2 / ChromaDB** harnesses merged (#129).
- **2026-04-07** ๐ **Dify Workflow CLI** merged (#191) โ workflow automation wrapper. ๐ง **Inkscape** auto-save fix (#193, fixes #182). ๐ก๏ธ **DomShell security hardening** (#156) โ URL validation and DOM sanitization for the browser CLI. ๐ฅง **Pi Coding Agent extension** merged (#178).
- **2026-04-06** ๐ **Exa CLI** merged (#172) โ AI-powered web search and answers harness. ๐ฎ **Godot CLI** merged (#140) โ game engine harness with a full demo-game E2E pipeline. โ๏ธ **CloudAnalyzer** review fixes and frontend improvements also landed.
- **2026-04-03** ๐งช **WireMock CLI** merged (#170) โ HTTP mock server harness for API testing. ๐ฅง **Pi Coding Agent** extension support also landed, and CLI demo recordings were added to the docs.
- **2026-04-01** โ๏ธ **Slay the Spire II CLI** merged (#148) โ deck-building roguelike harness. ๐ฅ **VideoCaptioner CLI** merged (#166) โ AI-powered video captioning harness. ๐ฐ๏ธ **IntelWatch** was added to the registry for B2B OSINT workflows.
Earlier news (Mar 23โ30)
- **2026-03-30** ๐๏ธ **CLI-Anything v0.2.0** โ HARNESS.md progressive disclosure redesign. Detailed guides extracted into `guides/` for on-demand loading. Phases 1โ7 now contiguous. Key Principles and Rules merged into a single authoritative section.
- **2026-03-29** ๐ Blender skill docs updated โ enforce absolute render paths and correct prerequisites.
- **2026-03-28** ๐ **CLIBrowser** added to CLI-Hub registry for agent-accessible browser automation.
- **2026-03-27** ๐ Zotero SKILL.md enhanced with agent-facing constraints; REPL config and executable resolution fixes.
- **2026-03-26** ๐ **Zotero CLI** harness landed for Zotero desktop (library management, collections, citations). Draw.io custom ID bugfix (#132) and registry.json syntax fix.
- **2026-03-25** ๐ฎ **RenderDoc CLI** merged for GPU frame capture analysis. FreeCAD updated for v1.1. Blender EEVEE engine name corrected. Zoom token permissions hardened.
- **2026-03-24** ๐ญ **FreeCAD CLI** added with 258 commands across 17 groups. **iTerm2** and **Teltonika RMS** harnesses added to registry.
- **2026-03-23** ๐ค Launched **CLI-Hub meta-skill** โ agents can now discover and install CLIs autonomously. **Krita CLI** harness merged for digital painting.
Earlier news (Mar 11โ22)
- **2026-03-22** ๐ต **MuseScore CLI** merged with transpose, export, and instrument management.
- **2026-03-21** ๐ง Infrastructure improvements โ refined test harnesses and documentation across multiple CLIs. Enhanced Windows compatibility for several backends.
- **2026-03-20** ๐ **Novita AI** CLI added for OpenAI-compatible API access. Registry metadata improvements for better hub discovery.
- **2026-03-19** ๐ฆ Package structure refinements across harnesses. Improved SKILL.md generation with better command documentation.
- **2026-03-18** ๐งช Test coverage expansion โ additional E2E scenarios and edge case validation across multiple CLIs.
- **2026-03-17** ๐ Launched the **[CLI-Hub](https://hkuds.github.io/CLI-Anything/)** โ a central registry where you can browse, search, and install any CLI with a single `pip` command.
- **2026-03-16** ๐ค Added **SKILL.md generation** (Phase 6.5) โ every generated CLI now ships with an AI-discoverable skill definition.
- **2026-03-15** ๐พ Support for **OpenClaw** from the community! Merged Windows `cygpath` guard for cross-platform support.
- **2026-03-14** ๐ Fixed a GIMP Script-Fu path injection vulnerability and added **Japanese README** translation.
- **2026-03-13** ๐ **Qodercli** plugin officially merged as a community contribution with dedicated setup scripts.
- **2026-03-12** ๐ฆ **Codex skill** integration landed, bringing CLI-Anything to yet another AI coding platform.
- **2026-03-11** ๐ **Zoom** video conferencing harness added as the 11th supported application.
---
## ๐ค Why CLI?
CLI is the universal interface for both humans and AI agents:
โข **Structured & Composable** - Text commands match LLM format and chain for complex workflows
โข **Lightweight & Universal** - Minimal overhead, works across all systems without dependencies
โข **Self-Describing** - --help flags provide automatic documentation agents can discover
โข **Proven Success** - Claude Code runs thousands of real workflows through CLI daily
โข **Agent-First Design** - Structured JSON output eliminates parsing complexity
โข **Deterministic & Reliable** - Consistent results enable predictable agent behavior
## ๐ Quick Start
CLI-Anything has two equally useful starting points:
| Goal | Start Here |
|------|------------|
| **Use the existing CLI ecosystem now** | Install `cli-anything-hub`, browse the registry, and install ready-made CLIs. |
| **Build a new agent-native CLI** | Install the CLI-Anything plugin/skill for your agent, then run the 7-phase harness generator. |
**Phase 1: Empower yourself โ your CLI toolkit**
Install the CLI-Hub package manager first. It lets you browse, search, inspect, install, update, uninstall, and launch CLI-Anything harnesses plus public third-party CLIs from one command.
**PIP**
```bash
pip install cli-anything-hub
```
| Command | What it does |
|---------|--------------|
| `cli-hub list` | Browse the registry |
| `cli-hub search ` | Search by keyword |
| `cli-hub info ` | Inspect one CLI |
| `cli-hub install ` | Install from CLI-Hub |
| `cli-hub update ` | Update an install |
| `cli-hub uninstall ` | Remove an install |
| `cli-hub launch [args...]` | Run an installed CLI |
```bash
# Browse what is available
cli-hub list
cli-hub search image
# Install and try a CLI immediately
cli-hub install gimp
cli-hub info gimp
cli-hub launch gimp
```
> Some CLIs wrap real desktop or backend software. If a selected CLI needs GIMP, Blender, LibreOffice, or another upstream tool, install that upstream application too.
**Phase 1.5: Empower your agents โ install in one command**
Give SKILL-compatible agents the CLI-Hub meta-skill so they can discover and install the right CLI for a task.
**Also available on:** [ClawHub](https://clawhub.ai/yuh-yang/cli-anything-hub), [SkillHub](https://www.skillhub.club/web/skills/itsyuhao-cli-anything-hub), [SkillHub.cn](https://skillhub.cn/skills/cli-hub-meta-skill)
**NPX SKILLS**
```bash
npx skills add HKUDS/CLI-Anything --skill cli-hub-meta-skill -g -y
```
**Works with:** OpenClaw, Nanobot, Claude Code, Codex, Reasonix, Antigravity, and other SKILL-compatible agents.
Then prompt:
```text
Find appropriate CLI software in CLI-Hub and complete the task: ...
```
**Phase 3: Build a new CLI when the registry does not have one yet**
Use the CLI-Anything generator when you need a new harness for software, a codebase, or an internal tool that is not already available through CLI-Hub.
**Prerequisites**
- **Python 3.10+**
- Target software or source repo available locally or online
- A supported AI coding agent: [Claude Code](#-claude-code) | [Pi](#-pi-coding-agent) | [OpenClaw](#-openclaw) | [OpenCode](#-opencode) | [Codex](#-codex) | [Hermes](#-hermes) | [Reasonix](#-reasonix) | [Qodercli](#-qodercli) | [GitHub Copilot CLI](#-github-copilot-cli) | [More Platforms](#-more-platforms-coming-soon)
### Pick Your Agent Platform
โก Claude Code
**Step 1: Add the Marketplace**
CLI-Anything is distributed as a Claude Code plugin marketplace hosted on GitHub.
```bash
# Add the CLI-Anything marketplace
/plugin marketplace add HKUDS/CLI-Anything
```
**Step 2: Install the Plugin**
```bash
# Install the cli-anything plugin from the marketplace
/plugin install cli-anything
```
That's it. The plugin is now available in your Claude Code session.
> **Note for Win Users:** Claude Code runs shell commands via `bash`. On Windows, install Git for Windows (includes `bash` and
`cygpath`) or use WSL; otherwise commands may fail with `cygpath: command not found`.
**Step 3: Build a CLI in One Command**
```bash
# /cli-anything
# Generate a complete CLI for GIMP (all 7 phases)
/cli-anything ./gimp
```
Command compatibility across Claude Code versions:
- Use `/cli-anything` as the primary entrypoint.
- On older builds where `/cli-anything` isn't recognized **after confirming the plugin is installed and loaded**, try the legacy entry form `/cli-anything:cli-anything`.
- Auxiliary commands keep the `:subcommand` form (e.g. `/cli-anything:refine`).
If you see `Unknown skill: cli-anything`, focus on plugin install/load first (both entry forms reference the same skill, so swapping forms won't help):
1. Reload plugin commands: `/reload-plugins`
2. Verify the plugin is loaded: `/help cli-anything` (CLI-Anything help/commands should appear)
3. Reinstall from marketplace if needed:
- `/plugin marketplace add HKUDS/CLI-Anything`
- `/plugin install cli-anything`
4. After confirming the plugin is available, retry the entry command:
- Preferred: `/cli-anything ./gimp`
- Older builds only: `/cli-anything:cli-anything ./gimp`
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
4. ๐ **Plan Tests** โ Creates TEST.md with unit + E2E test plans
5. ๐งช **Write Tests** โ Implements comprehensive test suite
6. ๐ **Document** โ Updates TEST.md with results
7. ๐ฆ **Publish** โ Creates `setup.py`, installs to PATH
**Step 4 (Optional): Refine and Improve the CLI**
After the initial build, you can iteratively refine the CLI to expand coverage and add missing capabilities:
```bash
# Broad refinement โ agent analyzes gaps across all capabilities
/cli-anything:refine ./gimp
# Focused refinement โ target a specific functionality area
/cli-anything:refine ./gimp "I want more CLIs on image batch processing and filters"
```
The refine command performs gap analysis between the software's full capabilities and current CLI coverage, then implements new commands, tests, and documentation for the identified gaps. You can run it multiple times to steadily expand coverage โ each run is incremental and non-destructive.
**Alternative: Manual Installation**
If you prefer not to use the marketplace:
```bash
# Clone the repo
git clone https://github.com/HKUDS/CLI-Anything.git
# Copy plugin to Claude Code plugins directory
cp -r CLI-Anything/cli-anything-plugin ~/.claude/plugins/cli-anything
# Reload plugins
/reload-plugins
```
โก Pi Coding Agent
**Step 1: Install the Extension**
The extension lives at `.pi-extension/cli-anything/` in this repository. Install it globally so `/cli-anything` commands are available in **all** Pi projects:
```bash
# Clone the repo
git clone https://github.com/HKUDS/CLI-Anything.git
cd CLI-Anything
# Install globally into Pi's extensions directory
bash .pi-extension/cli-anything/install.sh
```
To uninstall:
```bash
bash .pi-extension/cli-anything/install.sh --uninstall
```
> **How it works:** `install.sh` copies the extension files (including HARNESS.md, commands, guides, scripts, and templates from `cli-anything-plugin/`) into `~/.pi/agent/extensions/cli-anything/`, which Pi auto-discovers on startup. Run `/reload` in Pi or restart Pi to activate.
**Step 2: Build a CLI in One Command**
Once the extension is loaded, the following commands are available:
```bash
# Generate a complete CLI for GIMP (all 7 phases)
/cli-anything ./gimp
# Build from a GitHub repo
/cli-anything https://github.com/blender/blender
```
**Step 3 (Optional): Refine and Improve the CLI**
```bash
# Broad refinement โ agent analyzes gaps across all capabilities
/cli-anything:refine ./gimp
# Focused refinement โ target a specific functionality area
/cli-anything:refine ./gimp "batch processing and filters"
```
**Available Commands**
| Command | Description |
|---------|-------------|
| `/cli-anything ` | Build a complete CLI harness |
| `/cli-anything:refine [focus]` | Refine an existing CLI harness |
| `/cli-anything:test ` | Run tests for a CLI harness |
| `/cli-anything:validate ` | Validate a CLI harness |
| `/cli-anything:list [options]` | List all CLI-Anything tools |
โก OpenCode (Experimental)
**Step 1: Install the Commands**
> **Note:** Please upgrade to the latest OpenCode. Older versions may use a different commands path.
Copy the CLI-Anything commands **and** `HARNESS.md` to your OpenCode commands directory:
```bash
# Clone the repo
git clone https://github.com/HKUDS/CLI-Anything.git
# Global install (available in all projects)
cp CLI-Anything/opencode-commands/*.md ~/.config/opencode/commands/
cp CLI-Anything/cli-anything-plugin/HARNESS.md ~/.config/opencode/commands/
# Or project-level install
cp CLI-Anything/opencode-commands/*.md .opencode/commands/
cp CLI-Anything/cli-anything-plugin/HARNESS.md .opencode/commands/
```
> **Note:** Please upgrade to the latest OpenCode. Older versions use `command/` (singular) instead of `commands/`. If `commands/` does not exist, use `command/` for both global and project-level installs.
> **Note:** `HARNESS.md` is the methodology spec that all commands reference. It must be in the same directory as the commands.
This adds 5 slash commands: `/cli-anything`, `/cli-anything-refine`, `/cli-anything-test`, `/cli-anything-validate`, and `/cli-anything-list`.
**Step 2: Build a CLI in One Command**
```bash
# Generate a complete CLI for GIMP (all 7 phases)
/cli-anything ./gimp
# Build from a GitHub repo
/cli-anything https://github.com/blender/blender
```
The command runs as a subtask and follows the same 7-phase methodology as Claude Code.
**Step 3 (Optional): Refine and Improve the CLI**
```bash
# Broad refinement โ agent analyzes gaps across all capabilities
/cli-anything-refine ./gimp
# Focused refinement โ target a specific functionality area
/cli-anything-refine ./gimp "batch processing and filters"
```
โก Goose (Desktop / CLI) `Experimental` `Community`
**Step 1: Install Goose**
Install Goose (Desktop or CLI) using the official Goose instructions for your OS.
**Step 2: Configure a CLI Provider**
Configure Goose to use a CLI provider such as Claude Code, and make sure that CLI is installed and authenticated.
**Step 3: Use CLI-Anything in a Goose Session**
Once Goose is configured, start a session and use the same CLI-Anything commands described above for Claude Code, for example:
```bash
/cli-anything ./gimp
/cli-anything:refine ./gimp "batch processing and filters"
```
> Note: When Goose runs through a CLI provider, it uses that provider's capabilities and command format.
โก Qodercli `Community`
**Step 1: Register the Plugin**
```bash
git clone https://github.com/HKUDS/CLI-Anything.git
bash CLI-Anything/qoder-plugin/setup-qodercli.sh
```
This registers the cli-anything plugin in `~/.qoder.json`. Start a new Qodercli session after registration.
**Step 2: Use CLI-Anything from Qodercli**
```bash
/cli-anything ./gimp
/cli-anything:refine ./gimp "batch processing and filters"
/cli-anything:validate ./gimp
```
โก OpenClaw `Community`
**Step 1: Install the Skill**
CLI-Anything provides a native OpenClaw `SKILL.md` file. Copy it to your OpenClaw skills directory:
```bash
# Clone the repo
git clone https://github.com/HKUDS/CLI-Anything.git
# Install to the global skills folder
mkdir -p ~/.openclaw/skills/cli-anything
cp CLI-Anything/openclaw-skill/SKILL.md ~/.openclaw/skills/cli-anything/SKILL.md
```
**Step 2: Build a CLI**
Now you can invoke the skill inside OpenClaw:
`@cli-anything build a CLI for ./gimp`
The skill follows the same 7-phase methodology as Claude Code and OpenCode.
โก Codex `Experimental` `Community`
**Step 1: Install the Skill**
Run the bundled installer:
```bash
# Clone the repo
git clone https://github.com/HKUDS/CLI-Anything.git
# Install the skill
bash CLI-Anything/codex-skill/scripts/install.sh
```
On Windows PowerShell, use:
```powershell
.\CLI-Anything\codex-skill\scripts\install.ps1
```
This installs the skill to `$CODEX_HOME/skills/cli-anything` (or `~/.codex/skills/cli-anything` if `CODEX_HOME` is unset).
The installer also vendors the canonical `HARNESS.md`, command specifications,
on-demand guides, reusable helper scripts, skill template, and preview protocol
into the installed skill's `references/` and `scripts/` directories.
This keeps the Codex skill self-contained while using `cli-anything-plugin/` as
the source of truth.
Restart Codex after installation so it is discovered.
**Step 2: Use CLI-Anything from Codex**
Describe the task in natural language, for example:
```text
Use CLI-Anything to build a harness for ./gimp
Use CLI-Anything to refine ./shotcut for picture-in-picture workflows
Use CLI-Anything to validate ./libreoffice
Use CLI-Anything to list generated harnesses under the current directory
```
The Codex skill adapts the same methodology used by the Claude Code plugin and
OpenCode commands, while keeping the generated Python harness format unchanged.
To verify the self-contained Codex installation locally:
```bash
bash CLI-Anything/codex-skill/tests/test_install.sh
```
โก Hermes `Experimental` `Community`
**Step 1: Install the Skill**
Run the bundled installer:
```bash
# Clone the repo
git clone https://github.com/HKUDS/CLI-Anything.git
# Install the skill
bash CLI-Anything/hermes-skill/scripts/install.sh
```
On Windows PowerShell, use:
```powershell
.\CLI-Anything\hermes-skill\scripts\install.ps1
```
This installs the skill to `$HERMES_HOME/skills/cli-anything-hermes` (or `~/.hermes/skills/cli-anything-hermes` if `HERMES_HOME` is unset).
Restart [Hermes Agent](https://github.com/NousResearch/hermes-agent) after installation so it is discovered.
**Step 2: Use CLI-Anything from Hermes**
Describe the task in natural language, for example:
```text
Use CLI-Anything to build a harness for ./gimp
Use CLI-Anything to refine ./shotcut for picture-in-picture workflows
Use CLI-Anything to validate ./libreoffice
```
The Hermes skill adapts the same methodology used by the Claude Code plugin and
Codex skill, binding Hermes's `terminal`, `execute_code`, `delegate_task`, and
`read_file` / `write_file` / `patch` tools to the 7-phase harness workflow while
keeping the generated Python harness format unchanged.
โก Reasonix `Experimental` `Community`
**Step 1: Install the Skill**
Run the bundled installer:
```bash
# Clone the repo
git clone https://github.com/HKUDS/CLI-Anything.git
# Install the skill
bash CLI-Anything/reasonix-skill/scripts/install.sh
```
On Windows PowerShell, use:
```powershell
.\CLI-Anything\reasonix-skill\scripts\install.ps1
```
This installs the skill to Reasonix's global skill directory at `~/.reasonix/skills/cli-anything`.
Restart Reasonix after installation so it is discovered.
**Step 2: Use CLI-Anything from Reasonix**
Describe the task in natural language, for example:
```text
Use CLI-Anything to build a harness for ./gimp
Use CLI-Anything to refine ./shotcut for picture-in-picture workflows
Use CLI-Anything to validate ./libreoffice
```
The Reasonix skill adapts the same methodology used by the Claude Code plugin and
Codex/Hermes skills, binding Reasonix's `bash`, `write_file`, `edit_file`,
`multi_edit`, `grep`, `glob`, and optional `mcp__codegraph__search` / `mcp__codegraph__context` tools to the
7-phase harness workflow while keeping the generated Python harness format unchanged.
โก GitHub Copilot CLI `Community`
**Step 1: Install the Plugin**
```bash
git clone https://github.com/HKUDS/CLI-Anything.git
cd CLI-Anything
copilot plugin install ./cli-anything-plugin
```
This installs the CLI-Anything plugin to GitHub Copilot CLI. The plugin should now be available in your GitHub Copilot CLI session.
**Step 2: Use CLI-Anything from GitHub Copilot CLI**
```bash
/cli-anything ./gimp
/cli-anything:refine ./gimp "batch processing and filters"
/cli-anything:validate ./gimp
```
CLI-Anything is designed to be platform-agnostic. Support for more AI coding agents is planned:
- **Codex** โ available via the bundled skill in `codex-skill/`
- **Cursor** โ coming soon
- **Windsurf** โ coming soon
- **Your favorite tool** โ contributions welcome! See the `opencode-commands/` directory for a reference implementation.
### Use the Generated CLI
Regardless of which platform you used to build it, the generated CLI works the same way:
```bash
# Install to PATH
cd gimp/agent-harness && pip install -e .
# Use from anywhere
cli-anything-gimp --help
cli-anything-gimp project new --width 1920 --height 1080 -o poster.json
cli-anything-gimp --json layer add -n "Background" --type solid --color "#1a1a2e"
# Enter interactive REPL
cli-anything-gimp
```
Each in-repo harness now has a canonical [`SKILL.md`](#-skillmd-generation) at `skills/cli-anything-/SKILL.md`, which makes the monorepo directly discoverable via `npx skills add HKUDS/CLI-Anything --list`. Installed harness packages still ship a compatibility copy at `cli_anything//skills/SKILL.md`, and the REPL banner prefers the repo-root canonical file when present, falling back to the packaged copy otherwise.
---
## ๐ค Empower Your Agents with CLI-Hub
CLI-Hub lets agents autonomously discover, install, and use the CLIs they need.
```bash
npx skills add HKUDS/CLI-Anything --skill cli-hub-meta-skill -g -y
```
**Also available on:** [ClawHub](https://clawhub.ai/yuh-yang/cli-anything-hub), [SkillHub](https://www.skillhub.club/web/skills/itsyuhao-cli-anything-hub), [SkillHub.cn](https://skillhub.cn/skills/cli-hub-meta-skill)
Then prompt:
```text
Find appropriate CLI software in CLI-Hub and complete the task: ...
```
The meta-skill points agents to the live CLI-Hub catalog, where they can choose a CLI, install it, and read its own `SKILL.md` for task-specific usage.
---
## ๐ก CLI-Anything's Vision: Building Agent-Native Software
โข ๐ **Universal Access** - Every software becomes instantly agent-controllable through structured CLI.
โข ๐ **Seamless Integration** - Agents control any application without APIs, GUI, rebuilding or complex wrappers.
โข ๐ **Future-Ready Ecosystem** - Transform human-designed software into agent-native tools with one command.
---
## ๐ง When to Use CLI-Anything
| Category | How to be Agent-native | Notable Examples |
|----------|----------------------|----------|
| **๐ GitHub Repositories** | Transform any open-source project into agent-controllable tools through automatic CLI generation | VSCodium, WordPress, Calibre, Zotero, Joplin, Logseq, Penpot, Super Productivity |
| **๐ค AI/ML Platforms** | Automate model training, inference pipelines, and hyperparameter tuning through structured commands | Stable Diffusion WebUI, ComfyUI, Ollama, InvokeAI, Text-generation-webui, Open WebUI, Fooocus, Kohya_ss, AnythingLLM, SillyTavern |
| **๐ Data & Analytics** | Enable programmatic data processing, visualization, and statistical analysis workflows | JupyterLab, Apache Superset, Metabase, Redash, DBeaver, KNIME, Orange, OpenSearch Dashboards, Lightdash |
| **๐ป Development Tools** | Streamline code editing, building, testing, and deployment processes via command interfaces | Jenkins, Gitea, Hoppscotch, Portainer, pgAdmin, SonarQube, ArgoCD, OpenLens, Insomnia, Beekeeper Studio, **[iTerm2](https://iterm2.com)** |
| **๐จ Creative & Media** | Control content creation, editing, and rendering workflows programmatically | Blender, GIMP, OBS Studio, Audacity, WaveTone, Krita, Kdenlive, Shotcut, Inkscape, Darktable, LMMS, Ardour |
| **๐ฎ Game Development** | Manage game projects, scenes, exports, and scripting through headless engine interfaces | **[Godot Engine](https://godotengine.org)**, **[s&box](https://sbox.game)** |
| **๐ฌ 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 |
| **๐ Communication & Collaboration** | Automate meeting scheduling, participant management, recording retrieval, and reporting through structured CLI | Zoom, Jitsi Meet, BigBlueButton, Mattermost |
| **๐ Diagramming & Visualization** | Create and manipulate diagrams, flowcharts, architecture diagrams, and visual documentation programmatically | Draw.io (diagrams.net), Mermaid, PlantUML, Excalidraw, yEd |
| **๐ Network & Infrastructure** | Manage network services, DNS, ad-blocking, and infrastructure through structured CLI commands | AdGuardHome |
| **๐งช Testing & Mocking** | Control HTTP mock servers, manage test stubs, record and replay API traffic for integration testing | **[WireMock](https://wiremock.org)** |
| **๐ฌ Graphics & GPU Debugging** | Analyze GPU frame captures, inspect pipeline state, export shaders, and diff rendering state | RenderDoc |
| **โ๏ธ Fabrication & Machine Control** | Drive real hardware from design file to physical output โ safety-gated detect, preflight, jog, and framing commands with machine profiles over the software's real backend | MeerK40t (laser), Ink/Stitch (embroidery) |
| **๐ฌ Video & Subtitles** | Transcribe speech, translate subtitles, burn styled captions into video โ full captioning pipeline | VideoCaptioner |
| **๐ AI-Native Search** | Neural and deep web search with structured content retrieval through embedding-based APIs | [Exa](https://exa.ai) |
| **โจ 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
### The Agent-Software Gap
AI agents are great at reasoning but terrible at using real professional software. Current solutions are fragile UI automation, limited APIs, or dumbed-down reimplementations that miss 90% of functionality.
**CLI-Anything's Solution**: Transform any professional software into agent-native tools without losing capabilities.
| **Current Pain Point** | **CLI-Anything's Fix** |
|----------|----------------------|
| ๐ค "AI can't use real tools" | Direct integration with actual software backends (Blender, LibreOffice, FFmpeg) โ full professional capabilities, zero compromises |
| ๐ธ "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" | 2,280+ tests with real software validation. Battle-tested across 18 major applications |
---
## ๐ฏ What Can You Do with CLI-Anything?
| ### ๐ ๏ธ Let Agents Take Your Workflows
Professional or everyday โ just throw the codebase at `/cli-anything`. GIMP, Blender, Shotcut for creative work. LibreOffice, OBS Studio for daily tasks. Don't have the source? Find an open-source alternative and throw *that* in. You'll instantly get a full CLI your agents can use. | ### ๐ Unify Scattered APIs into One CLI
Tired of juggling fragmented web service APIs? Feed the docs or SDK manuscripts to `/cli-anything` and your agents get a **powerful, stateful CLI** that wraps those individual endpoints into coherent command groups. One tool instead of dozens of raw API calls โ stronger capabilities while saving tokens. | ### ๐ Replace or Supercharge GUI Agents
CLI-Anything can flat-out **replace GUI-based agent approaches** โ no more screenshots, no brittle pixel-clicking. But here's the fun part: once you `/cli-anything` a GUI software, you can **synthesize agent tasks, evaluators, and benchmarks** entirely via code and terminal โ fully automated, iteratively refinable, massively more efficient. |
| --- | --- | --- |
---
## โจ โ๏ธ How CLI-Anything Works
| ### ๐๏ธ 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. | ### ๐ฏ 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**. |
| --- | --- |
| ### ๐ Smart Session Management
Persistent project state with undo/redo capabilities, plus unified REPL interface (ReplSkin) that delivers consistent interactive experience across all CLIs. | ### ๐ฆ Zero-Config Installation
Simple pip install -e . puts cli-anything- directly on PATH. Agents discover tools via standard which commands. No setup, no wrappers. |
| ### ๐งช 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. | ### ๐ Clean Package Architecture
All CLIs organized under cli_anything.* namespace โ conflict-free, pip-installable, with consistent naming: cli-anything-gimp, cli-anything-blender, etc. |
### ๐ค SKILL.md Generation
Each generated CLI now has a canonical `SKILL.md` at `skills/cli-anything-/SKILL.md`. This makes the current monorepo directly consumable by `npx skills`, while a packaged compatibility copy at `cli_anything//skills/SKILL.md` preserves installed-harness behavior.
**What SKILL.md provides:**
- **YAML frontmatter** with name and description for agent skill discovery
- **Command groups** with all available subcommands documented
- **Usage examples** for common workflows
- **Agent-specific guidance** for JSON output, error handling, and programmatic use
SKILL.md files are auto-generated during Phase 6.5 of the pipeline using `skill_generator.py`, which extracts metadata directly from the CLI's Click decorators, setup.py, and README. The generator now writes the canonical repo-root skill file and refreshes the package-local compatibility copy used by installed harnesses. Inside this repo, the REPL banner points agents to the canonical root skill path; after `pip install`, it falls back to the packaged copy.
---
## ๐ฌ Real-World Demos
AI agents using generated CLIs to produce complete, useful artifacts โ no GUI needed.
### FreeCAD — Curiosity Rover via Preview, Live Preview, and Trajectory
> **Harness:** `cli-anything-freecad` | **Preview Stack:** `preview` + `preview live` + `trajectory.json` | **Artifact:** Agent-built Curiosity-style rover
An agent incrementally assembles a Curiosity-inspired rover while publishing real FreeCAD preview bundles, refreshing a live preview session, and recording command-to-preview history for later replay. The resulting demo shows the artifact evolving step by step before the final showcase.
### Blender — Orbital Relay Drone via Preview, Live Preview, and Trajectory
> **Harness:** `cli-anything-blender` | **Preview Stack:** `preview` + `preview live` + `trajectory.json` | **Artifact:** Agent-built orbital relay drone
An agent uses the Blender harness to grow a hard-surface orbital relay drone under a real preview loop: each stage pushes new render-backed bundles, the live session tracks the current head, and the trajectory ties every command to the matching visual state. The demo finishes with the completed scene ready for a polished turntable.
### Draw.io — HTTPS Handshake Diagram
> **Harness:** `cli-anything-drawio` | **Time:** ~4 min | **Artifact:** `.drawio` + `.png`
An agent creates a full HTTPS connection lifecycle diagram from scratch โ TCP three-way handshake, TLS negotiation, encrypted data exchange, and TCP four-way termination โ entirely through CLI commands.
Final artifact
*Contributed by [@zhangxilong-43](https://github.com/zhangxilong-43)*
### Slay the Spire II — Game Automation
> **Harness:** `cli-anything-slay-the-spire-ii` | **Artifact:** Automated gameplay session
An agent plays through a Slay the Spire II run using the CLI harness โ reading game state, selecting cards, choosing paths, and making strategic decisions in real-time.
*Contributed by [@TianyuFan0504](https://github.com/TianyuFan0504)*
### VideoCaptioner — Auto-Generated Subtitles
> **Harness:** `cli-anything-videocaptioner` | **Artifact:** Captioned video frames
An agent uses the VideoCaptioner CLI to automatically generate and overlay styled subtitles onto video content, with bilingual text rendering and customizable formatting.
| **Sub A** | **Sub B** |
| --- | --- |
| | |
*Contributed by [@WEIFENG2333](https://github.com/WEIFENG2333)*
### ArcGIS Pro — Live Agent Cartography via the MCP Bridge
> **Harness:** [`arcgis-pro`](https://github.com/Jasper0122/CLI-Anything-Arcgis-Pro) (registered in [`public_registry.json`](public_registry.json)) | **Mode:** live-Pro MCP bridge | **Artifact:** Agent-driven map navigation in a running ArcGIS Pro session
An agent drives a **live, open ArcGIS Pro session** through an MCP bridge โ reading the project, zooming the map to feature layers, running geoprocessing, and exporting layouts โ while each step executes inside Pro as you watch. ArcGIS Pro is Esri's commercial GIS desktop (Windows-only, licensed), so this wraps its official **ArcPy / ArcGIS Pro SDK** rather than being generated from source โ the ArcGIS Pro counterpart to the QGIS harness.
*Contributed by [@Jasper0122](https://github.com/Jasper0122)*
*More CLI demos coming soon.*
---
## ๐ฌ Demonstrations
### ๐ฏ General-Purpose
CLI-Anything works on any software with a codebase โ no domain restrictions or architectural limitations.
### ๐ญ Professional-Grade Testing
Tested across 18 diverse, complex applications spanning creative, productivity, communication, diagramming, AI image generation, AI content generation, network ad blocking, local LLM inference, native debugging, and graphics profiling 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.
| 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 |
| **WaveTone** | Audio Transcription | `cli-anything-wavetone` | JSON manifest + real WaveTone launch | [New](wavetone/agent-harness/) |
| **๐ Browser** | Browser Automation | `cli-anything-browser` | DOMShell MCP + Accessibility Tree | โ
[New](browser/agent-harness/) |
| **[Web Yu-pri](web-yu-pri/agent-harness/)** | Japan Post Shipping Labels | `cli-anything-web-yu-pri` | Playwright + Web Yu-pri forms | โ
[New](web-yu-pri/agent-harness/) |
| **๐ LibreOffice** | Office Suite (Writer, Calc, Impress) | `cli-anything-libreoffice` | ODF generation + headless LO | โ
158 |
| **[OpenRefine](openrefine/agent-harness/)** | Data Cleaning | `cli-anything-openrefine` | OpenRefine local HTTP API | โ
76 |
| **โก [n8n](n8n/agent-harness/)** | Workflow Automation | `cli-anything-n8n` | n8n REST API v1.1.1 | โ
[55+ cmds](n8n/agent-harness/) |
| **๐ง [Mailchimp](mailchimp/agent-harness/)** | Email Marketing & Automation | `cli-anything-mailchimp` | Mailchimp Marketing API v3.0 | โ
[303 cmds](mailchimp/agent-harness/) |
| **๐ [Zotero](zotero/agent-harness/)** | Reference Management | `cli-anything-zotero` | Local SQLite + connector + Local API | โ
[New](zotero/agent-harness/) |
| **๐ [Calibre](calibre/agent-harness/)** | E-book Library Management | `cli-anything-calibre` | calibredb + ebook-convert + ebook-meta | โ
[58](calibre/agent-harness/) |
| **๐ [Joplin](joplin/agent-harness/)** | Note-taking & To-dos | `cli-anything-joplin` | Joplin terminal CLI subprocess | โ
134 |
| **๐ [Mubu](mubu/agent-harness/)** | Knowledge Management & Outlining | `cli-anything-mubu` | Local Mubu data + sync logs | โ
96 |
| **๐น OBS Studio** | Live Streaming & Recording | `cli-anything-obs-studio` | JSON scene + obs-websocket | โ
153 |
| **๐ฑ [NSLogger](nslogger/agent-harness/)** | iOS/macOS Log Capture | `cli-anything-nslogger` | NSLogger wire protocol + native macOS Bonjour | โ
139 |
| **๐๏ธ Kdenlive** | Video Editing | `cli-anything-kdenlive` | MLT XML + melt renderer | โ
155 |
| **๐ฌ Shotcut** | Video Editing | `cli-anything-shotcut` | Direct MLT XML + melt | โ
154 |
| **๐ฌ [Openscreen](openscreen/agent-harness/)** | Screen Recording Editor | `cli-anything-openscreen` | ffmpeg backend | โ
101 |
| **๐ Zoom** | Video Conferencing | `cli-anything-zoom` | Zoom REST API (OAuth2) | โ
22 |
| **๐ต MuseScore** | Music Notation | `cli-anything-musescore` | mscore CLI (MSCX/MusicXML) | โ
56 |
| **๐ Draw.io** | Diagramming | `cli-anything-drawio` | mxGraph XML + draw.io CLI | โ
138 |
| **[EEZ Studio](eez-studio/agent-harness/)** | Embedded UI / Instrument Automation | `cli-anything-eez-studio` | .eez-project JSON + EEZ Studio Node backend | โ
[New](eez-studio/agent-harness/) |
| **โ๏ธ ETH2 QuickStart** | DevOps / Ethereum | `cli-anything-eth2-quickstart` | eth2-quickstart shell automation + JSON health checks | โ
18 |
| **๐ง Mermaid Live Editor** | Diagramming | `cli-anything-mermaid` | Mermaid state + mermaid.ink renderer | โ
10 |
| **โจ AnyGen** | AI Content Generation | `cli-anything-anygen` | AnyGen REST API (anygen.io) | โ
50 |
| **๐ง NotebookLM** | AI Research Assistant | `cli-anything-notebooklm` | NotebookLM CLI wrapper (experimental) | โ
21 |
| **๐งฉ [Dify Workflow](dify-workflow/agent-harness/)** | Dify DSL Editing | `cli-anything-dify-workflow` | Wrapper around the open-source dify-workflow CLI | โ
11 |
| **๐ผ๏ธ ComfyUI** | AI Image Generation | `cli-anything-comfyui` | ComfyUI REST API | โ
70 |
| **๐ก๏ธ AdGuard Home** | Network-wide Ad Blocking | `cli-anything-adguardhome` | AdGuard Home REST API | โ
36 |
| **๐ฆ Ollama** | Local LLM Inference | `cli-anything-ollama` | Ollama REST API | โ
98 |
| **๐งฌ [Uni-Mol Tools](unimol_tools/agent-harness/)** | Molecular Property Prediction (AI4S) | `cli-anything-unimol-tools` | Uni-Mol molecular ML backend | โ
67 |
| **๐ฌ [VideoCaptioner](videocaptioner/agent-harness/)** | AI Video Captioning | `cli-anything-videocaptioner` | videocaptioner CLI (PyPI) | โ
26 |
| **๐จ Sketch** | UI Design | `sketch-cli` | sketch-constructor (Node.js) | โ
19 |
| **๐ฎ Godot Engine** | Game Development | `cli-anything-godot` | Godot 4.x headless subprocess | โ
24 |
| **๐ฆ [s&box](sbox/agent-harness/)** | Game Development | `cli-anything-sbox` | Source 2 game engine - direct file I/O on .scene/.prefab/.vmat/.vsnd JSON | โ
244 |
| **๐ [LLDB](lldb/agent-harness/)** | Native Debugging | `cli-anything-lldb` | LLDB Python API | โ
27 |
| **๐ฉ [Nsight Graphics CLI](nsight-graphics/agent-harness/)** | GPU Debugging & Profiling | `cli-anything-nsight-graphics` | Official ngfx / ngfx-capture orchestration + GPU Trace summary + replay analysis | โ
51 |
| **๐ [Exa](exa/agent-harness/)** | AI-Native Web Search | `cli-anything-exa` | exa-py SDK | โ
40 |
| **๐ [Unreal Insights](unrealinsights/agent-harness/)** | Performance Profiling | `cli-anything-unrealinsights` | Background trace sessions + engine-matched UnrealInsights build + headless export | โ
50 |
| **โ๏ธ [CloudAnalyzer](cloudanalyzer/agent-harness/)** | Point cloud / trajectory QA | `cli-anything-cloudanalyzer` | CloudAnalyzer (Python API) | โ
14 |
| **๐บ๏ธ [QGIS](QGIS/agent-harness/)** | Geospatial Analysis & Mapping | `cli-anything-qgis` | PyQGIS + qgis_process | โ
22 |
| **๐ฉ [3MF](3MF/agent-harness/)** | Mesh geometry editor for 3D printing | `cli-anything-3mf` | numpy, scipy, trimesh | โ
50 |
| **๐๏ธ [Tigris](tigris/agent-harness/)** | Object Storage (S3-compatible, global, no egress) โ buckets, objects, snapshots, IAM, access keys | `cli-anything-tigris` | subprocess wrapping the official `tigris` CLI | โ
[New](tigris/agent-harness/) |
| **Total** | **โ
2,461** | | | |
> **100% pass rate** across all 2,461 tests โ 1,732 unit tests + 579 end-to-end tests + 19 Node.js tests.
---
## ๐ Test Results
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 |
```
================================ Test Summary ================================
gimp 107 passed โ
(64 unit + 43 e2e)
blender 208 passed โ
(150 unit + 58 e2e)
inkscape 202 passed โ
(148 unit + 54 e2e)
audacity 161 passed โ
(107 unit + 54 e2e)
wavetone 30 passed โ
(24 unit + 6 default e2e, 2 backend-gated e2e skipped; 32 passed opt-in)
libreoffice 158 passed โ
(89 unit + 69 e2e)
mubu 96 passed โ
(85 unit + 11 e2e)
obs-studio 153 passed โ
(116 unit + 37 e2e)
nslogger 139 passed โ
(97 unit + 42 e2e)
kdenlive 155 passed โ
(111 unit + 44 e2e)
shotcut 154 passed โ
(110 unit + 44 e2e)
zoom 22 passed โ
(22 unit + 0 e2e)
drawio 138 passed โ
(116 unit + 22 e2e)
eth2-quickstart 18 passed โ
(18 unit + 3 e2e skipped)
mermaid 10 passed โ
(5 unit + 5 e2e)
anygen 50 passed โ
(40 unit + 10 e2e)
notebooklm 21 passed โ
(21 unit + 0 e2e)
comfyui 73 passed โ
(63 unit + 10 e2e)
adguardhome 36 passed โ
(24 unit + 12 e2e)
ollama 98 passed โ
(87 unit + 11 e2e)
sketch 19 passed โ
(19 jest, Node.js)
renderdoc 59 passed โ
(45 unit + 14 e2e)
cloudcompare 88 passed โ
(49 unit + 39 e2e)
openscreen 101 passed โ
(78 unit + 23 e2e)
lldb 27 passed โ
(23 unit + 4 e2e)
nsight-graphics 51 passed โ
(46 unit/CLI + 5 local e2e)
unrealinsights 50 passed โ
(49 unit + 1 e2e, 9 backend-gated e2e skipped)
cloudanalyzer 14 passed โ
(7 unit + 7 e2e)
3mf 50 passed โ
(50 unit)
joplin 134 passed โ
(107 unit + 27 e2e, 1 skipped on Windows)
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
TOTAL 2,464 passed โ
100% pass rate
```
---
## ๐๏ธ CLI-Anything's Architecture
### ๐ฏ 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**.
---
## ๐ Project Structure
```
/* Detailed source-code truncated for AI context efficiency. */
```
Each `agent-harness/` contains an installable Python package under `cli_anything./` with Click CLI, core modules, utils (including `repl_skin.py` and backend wrapper), and comprehensive tests.
---
## ๐ฏ Plugin Commands
| Command | Description |
|---------|-------------|
| `/cli-anything ` | Build complete CLI harness โ all 7 phases |
| `/cli-anything:refine [focus]` | Refine an existing harness โ expand coverage with gap analysis |
| `/cli-anything:test ` | Run tests and update TEST.md with results |
| `/cli-anything:validate ` | Validate against HARNESS.md standards |
### Examples
```bash
# Build a complete CLI for GIMP from local source
/cli-anything /home/user/gimp
# Build from a GitHub repo
/cli-anything https://github.com/blender/blender
# Refine an existing harness โ broad gap analysis
/cli-anything:refine /home/user/gimp
# Refine with a specific focus area
/cli-anything:refine /home/user/shotcut "vid-in-vid and picture-in-picture compositing"
# Run tests and update TEST.md
/cli-anything:test /home/user/inkscape
# Validate against HARNESS.md standards
/cli-anything:validate /home/user/audacity
```
---
## ๐ฎ Demo: Using a Generated CLI
Here's what an agent can do with `cli-anything-libreoffice`:
```bash
# Create a new Writer document
$ cli-anything-libreoffice document new -o report.json --type writer
โ Created Writer document: report.json
# Add content
$ cli-anything-libreoffice --project report.json writer add-heading -t "Q1 Report" --level 1
โ Added heading: "Q1 Report"
$ cli-anything-libreoffice --project report.json writer add-table --rows 4 --cols 3
โ Added 4ร3 table
# Export to real PDF via LibreOffice headless
$ cli-anything-libreoffice --project report.json export render output.pdf -p pdf --overwrite
โ Exported: output.pdf (42,831 bytes) via libreoffice-headless
# JSON mode for agent consumption
$ cli-anything-libreoffice --json document info --project report.json
{
"name": "Q1 Report",
"type": "writer",
"pages": 1,
"elements": 2,
"modified": true
}
```
### REPL Mode
```
$ cli-anything-blender
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ cli-anything-blender v1.0.0 โ
โ Blender CLI for AI Agents โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
blender> scene new --name ProductShot
โ Created scene: ProductShot
blender[ProductShot]> object add-mesh --type cube --location 0 0 1
โ Added mesh: Cube at (0, 0, 1)
blender[ProductShot]*> render execute --output render.png --engine CYCLES
โ Rendered: render.png (1920ร1080, 2.3 MB) via blender --background
blender[ProductShot]> exit
Goodbye! ๐
```
---
## ๐ The Standard Playbook: HARNESS.md
HARNESS.md is our definitive SOP for making any software agent-accessible via automated CLI generation.
It encodes proven patterns and methodologies refined through automated generation processes.
The playbook distills key insights from successfully building all 18 diverse, production-ready harnesses.
### 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. |
> See the full methodology: [`cli-anything-plugin/HARNESS.md`](cli-anything-plugin/HARNESS.md)
---
## ๐ฆ Installation & Usage
### For CLI-Hub Users
```bash
# Install the package manager
pip install cli-anything-hub
# Browse, search, inspect, and install CLIs
cli-hub list
cli-hub search
cli-hub info
cli-hub install
# Manage installed CLIs
cli-hub update
cli-hub uninstall
cli-hub launch [args...]
```
### For Plugin Users (Claude Code)
```bash
# Add marketplace & install (recommended)
/plugin marketplace add HKUDS/CLI-Anything
/plugin install cli-anything
# Build a CLI for any software with a codebase
/cli-anything
```
### For Generated CLIs
```bash
# Install any generated CLI
cd /agent-harness
pip install -e .
# Verify
which cli-anything-
# Use
cli-anything- --help
cli-anything- # enters REPL
cli-anything- --json # JSON output for agents
```
### Running Tests
```bash
# Run tests for a specific CLI
cd /agent-harness
python3 -m pytest cli_anything//tests/ -v
# Force-installed mode (recommended for validation)
CLI_ANYTHING_FORCE_INSTALLED=1 python3 -m pytest cli_anything//tests/ -v -s
```
---
## ๐ค Contributing
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).
- **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
### Limitations
- **Requires strong foundation models** โ CLI-Anything relies on frontier-class models (e.g., Claude Opus 4.6, Claude Sonnet 4.6, GPT-5.4) for reliable harness generation. Weaker or smaller models may produce incomplete or incorrect CLIs that require significant manual correction.
- **Relies on available source code** โ The 7-phase pipeline analyzes and generates from source code. When the target software only provides compiled binaries that require decompilation, harness quality and coverage will degrade substantially.
- **May require iterative refinement** โ A single `/cli-anything` run may not fully cover all capabilities. Running `/refine` one or more times is often needed to push the CLI's performance and coverage to production quality.
### Roadmap
- [ ] Support for more application categories (CAD, DAW, IDE, EDA, scientific tools)
- [ ] Benchmark suite for agent task completion rates
- [ ] Community-contributed CLI harnesses for internal/custom software
- [ ] Integration with additional agent frameworks beyond Claude Code
- [ ] Support packaging APIs for closed-source software and web services into CLIs
- [x] Produce SKILL.md alongside the CLI for agent skill discovery and orchestration
---
## ๐ 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 |
Each generated harness also includes:
- `.md` โ Architecture SOP specific to that application
- `tests/TEST.md` โ Test plan and results documentation
---
## โญ Star History
If CLI-Anything helps make your software Agent-native, give us a star! โญ
---
## ๐ Citation
If you find CLI-Anything useful, please cite our technical report:
```bibtex
@misc{yang2026clianythingagentnativecomputeruse,
title={CLI-Anything: Towards Agent-Native Computer Use},
author={Yuhao Yang and Tianyu Fan and Chao Huang},
year={2026},
eprint={2606.03854},
archivePrefix={arXiv},
primaryClass={cs.HC},
url={https://arxiv.org/abs/2606.03854},
}
```
---
## ๐ License
Apache License 2.0 โ free to use, modify, and distribute.
---
---
## File: adguardhome/agent-harness/cli_anything/adguardhome/README.md
# cli-anything-adguardhome
CLI harness for AdGuardHome - control your ad blocker from the command line or via agents.
## Prerequisites
AdGuardHome must be running. Install:
```bash
# Linux - native
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v
# Docker
docker run --name adguardhome -p 3000:3000 adguard/adguardhome
```
## Installation
```bash
cd agent-harness
pip install -e .
cli-anything-adguardhome --help
```
## Configuration
```bash
export AGH_HOST=localhost
export AGH_PORT=3000
export AGH_USERNAME=admin
export AGH_PASSWORD=secret
# Or save to config file
cli-anything-adguardhome --host localhost --port 3000 --username admin --password secret config save
```
## Usage
```bash
# Interactive REPL (default)
cli-anything-adguardhome
# One-shot commands
cli-anything-adguardhome server status
cli-anything-adguardhome filter list
cli-anything-adguardhome --json stats show
# Filtering
cli-anything-adguardhome filter add --url https://somehost.com/list.txt --name "My List"
cli-anything-adguardhome filter refresh
# DNS rewrites
cli-anything-adguardhome rewrite add --domain "myserver.local" --answer "192.168.1.50"
cli-anything-adguardhome rewrite list
# Clients
cli-anything-adguardhome clients add --name "My PC" --ip 192.168.1.100
# Stats
cli-anything-adguardhome stats show
cli-anything-adguardhome stats reset
```
## Tests
```bash
cd agent-harness
python3 -m pytest cli_anything/adguardhome/tests/test_core.py -v
python3 -m pytest cli_anything/adguardhome/tests/test_full_e2e.py -v -s
CLI_ANYTHING_FORCE_INSTALLED=1 python3 -m pytest cli_anything/adguardhome/tests/ -v -s
```
---
## File: anygen/agent-harness/cli_anything/anygen/README.md
# AnyGen CLI
A stateful command-line interface for AnyGen OpenAPI โ generate professional
slides, documents, websites, diagrams, and more from natural language prompts.
Designed for AI agents and power users.
## Prerequisites
- Python 3.10+
- `requests` (HTTP client)
- `click` (CLI framework)
- AnyGen API key (`sk-xxx`)
Optional (for interactive REPL):
- `prompt_toolkit`
## Install Dependencies
```bash
pip install requests click prompt_toolkit
```
## Get an API Key
1. Go to [anygen.io/home](https://www.anygen.io/home) โ Setting โ Integration
2. Create an API key (format: `sk-xxx`)
3. Configure it:
```bash
# Option 1: Config file (recommended)
cli-anything-anygen config set api_key "sk-xxx"
# Option 2: Environment variable
export ANYGEN_API_KEY="sk-xxx"
```
## How to Run
All commands are run from the `agent-harness/` directory or via the installed command.
### One-shot Commands
```bash
# Show help
cli-anything-anygen --help
# Full workflow: create โ poll โ download
cli-anything-anygen task run --operation slide --prompt "AI trends presentation" --output ./
# Create a task (returns task ID)
cli-anything-anygen task create --operation doc --prompt "Technical design document"
# Check task status
cli-anything-anygen task status task_xxx
# Poll until completion (with auto-download)
cli-anything-anygen task poll task_xxx --output ./
# Download result file
cli-anything-anygen task download task_xxx --output ./
# JSON output for agent consumption
cli-anything-anygen --json task status task_xxx
```
### Interactive REPL
```bash
cli-anything-anygen
```
Inside the REPL, type `help` for all available commands.
## Command Reference
### Task
```bash
task create --operation --prompt [options]
task run --operation --prompt [--output dir] [options]
task status
task poll [--output dir]
task download --output
task thumbnail --output
task list [--limit N] [--status completed]
task prepare --message [--file-token tk_xxx] [--save conv.json]
```
Operations: `slide`, `doc`, `smart_draw`, `chat`, `storybook`, `data_analysis`, `website`
Create / run options:
- `--language` / `-l` โ zh-CN or en-US
- `--slide-count` / `-c` โ Number of slides (slide only)
- `--template` / `-t` โ Slide template (slide only)
- `--ratio` / `-r` โ 16:9 or 4:3 (slide only)
- `--export-format` / `-f` โ pptx/image/thumbnail/docx/drawio/excalidraw
- `--file-token` โ File token from upload (repeatable)
- `--style` / `-s` โ Style preference
### File
```bash
file upload
```
### Config
```bash
config set api_key "sk-xxx"
config set default_language "en-US"
config get [key]
config delete
config path
```
### Session
```bash
session status
session history [--limit N]
session undo
session redo
```
## JSON Mode
Add `--json` before the subcommand for machine-readable output:
```bash
cli-anything-anygen --json task status task_xxx
cli-anything-anygen --json task list --limit 5
```
## Running Tests
```bash
cd agent-harness
# Unit tests (mock HTTP, no API key needed)
python3 -m pytest cli_anything/anygen/tests/test_core.py -v
# E2E tests (requires ANYGEN_API_KEY)
ANYGEN_API_KEY=sk-xxx python3 -m pytest cli_anything/anygen/tests/test_full_e2e.py -v
# All tests
python3 -m pytest cli_anything/anygen/tests/ -v
```
## Example Workflow
```bash
# Configure API key
cli-anything-anygen config set api_key "sk-xxx"
# Upload a reference file
cli-anything-anygen file upload ./quarterly_data.pdf
# Output: โ Uploaded: quarterly_data.pdf โ token: tk_abc123
# Requirement analysis (multi-turn)
cli-anything-anygen task prepare --message "I need a quarterly review slide deck" --save conv.json
# AnyGen asks clarifying questions...
cli-anything-anygen task prepare --message "Focus on revenue growth, 10 slides" --input conv.json --save conv.json
# Status: ready, suggested operation: slide
# Create and download in one step
cli-anything-anygen task run \
--operation slide \
--prompt "Quarterly business review..." \
--file-token tk_abc123 \
--slide-count 10 \
--style "business formal" \
--output ./output/
# Or step-by-step
cli-anything-anygen task create --operation slide --prompt "..."
# Task ID: task_xxx
cli-anything-anygen task poll task_xxx --output ./output/
# โ Downloaded: ./output/presentation.pptx (2,048,576 bytes)
# Verify the file
cli-anything-anygen --json task status task_xxx
```
## Supported Operations
| Operation | Type | Output | Downloadable |
|-----------|------|--------|-------------|
| Slides | `slide` | PPTX | Yes |
| Documents | `doc` | DOCX | Yes |
| Diagrams | `smart_draw` | drawio/excalidraw | Yes |
| General | `chat` | โ | No (URL) |
| Storybooks | `storybook` | โ | No (URL) |
| Data Analysis | `data_analysis` | โ | No (URL) |
| Websites | `website` | โ | No (URL) |
---
## File: audacity/agent-harness/cli_anything/audacity/README.md
# Audacity CLI
A stateful command-line interface for audio editing, following the same patterns
as the GIMP and Blender CLIs in this repo.
## Architecture
- **JSON project format** tracks state (tracks, clips, effects, labels, selection)
- **Python stdlib** (`wave`, `struct`, `math`) handles WAV I/O and audio processing
- **Click** provides the CLI framework with subcommand groups and REPL
- Effects are recorded in the project JSON and applied during export/render
## Install
```bash
pip install click numpy # numpy only needed for tests
```
No other dependencies required. Core functionality uses only Python stdlib.
## Run
```bash
# From the agent-harness/ directory:
cd /root/cli-anything/audacity/agent-harness
# One-shot commands
python3 -m cli.audacity_cli project new --name "My Podcast"
python3 -m cli.audacity_cli track add --name "Voice"
python3 -m cli.audacity_cli clip add 0 /path/to/recording.wav
python3 -m cli.audacity_cli effect add normalize --track 0
python3 -m cli.audacity_cli export render output.wav
# JSON output mode (for agent consumption)
python3 -m cli.audacity_cli --json project info
# Interactive REPL
python3 -m cli.audacity_cli repl
```
## Run Tests
```bash
cd /root/cli-anything/audacity/agent-harness
# All tests
python3 -m pytest cli/tests/ -v
# Unit tests only (no real audio files)
python3 -m pytest cli/tests/test_core.py -v
# E2E tests (generates real WAV files)
python3 -m pytest cli/tests/test_full_e2e.py -v
```
## Evaluation (Eval Harness)
Run a lightweight evaluation suite and generate reports:
```bash
# Default output: eval_results//
python3 -m cli.audacity_cli eval
# Custom output directory
python3 -m cli.audacity_cli eval --out ./eval_out
# Compare to a baseline and fail on regression
python3 -m cli.audacity_cli eval --baseline baseline.json --fail-on-regression
# Update (write) baseline JSON
python3 -m cli.audacity_cli eval --baseline baseline.json --update-baseline
```
Outputs:
- `eval_report.json` and `eval_report.md`
- `artifacts/` directory for task outputs
## Command Groups
| Group | Commands |
|-------|----------|
| `project` | `new`, `open`, `save`, `info`, `settings`, `json` |
| `track` | `add`, `remove`, `list`, `set` |
| `clip` | `import`, `add`, `remove`, `trim`, `split`, `move`, `list` |
| `effect` | `list-available`, `info`, `add`, `remove`, `set`, `list` |
| `selection` | `set`, `all`, `none`, `info` |
| `label` | `add`, `remove`, `list` |
| `media` | `probe`, `check` |
| `export` | `presets`, `preset-info`, `render` |
| `session` | `status`, `undo`, `redo`, `history` |
## Example Workflow
```bash
# Create a podcast project
python3 -m cli.audacity_cli project new --name "Episode 1" -o project.json
# Add tracks
python3 -m cli.audacity_cli --project project.json track add --name "Host"
python3 -m cli.audacity_cli --project project.json track add --name "Guest"
python3 -m cli.audacity_cli --project project.json track add --name "Music"
# Import audio clips
python3 -m cli.audacity_cli --project project.json clip add 0 host_recording.wav
python3 -m cli.audacity_cli --project project.json clip add 1 guest_recording.wav --start 0.5
python3 -m cli.audacity_cli --project project.json clip add 2 music.wav --volume 0.3
# Apply effects
python3 -m cli.audacity_cli --project project.json effect add normalize --track 0 -p target_db=-3.0
python3 -m cli.audacity_cli --project project.json effect add compress --track 0 -p threshold=-20 -p ratio=4.0
python3 -m cli.audacity_cli --project project.json effect add fade_in --track 2 -p duration=2.0
# Add labels
python3 -m cli.audacity_cli --project project.json label add 0.0 --text "Intro"
python3 -m cli.audacity_cli --project project.json label add 30.0 -e 60.0 --text "Main discussion"
# Export
python3 -m cli.audacity_cli --project project.json export render episode1.wav --preset wav
```
---
## File: blender/agent-harness/cli_anything/blender/README.md
# Blender CLI - Agent Harness
A stateful command-line interface for 3D scene editing, following the same
patterns as the GIMP CLI harness. Uses a JSON scene description format
with bpy script generation for actual Blender rendering.
## Installation
```bash
# From the agent-harness directory:
pip install click prompt_toolkit
# No Blender installation required for scene editing.
# Blender is only needed if you want to execute the generated render scripts.
```
## Quick Start
```bash
# Create a new scene
python3 -m cli.blender_cli scene new --name "MyScene" -o scene.json
# Add objects
python3 -m cli.blender_cli --project scene.json object add cube --name "Box"
python3 -m cli.blender_cli --project scene.json object add sphere --name "Ball" -l 3,0,1
# Create and assign materials
python3 -m cli.blender_cli --project scene.json material create --name "Red" --color 1,0,0,1
python3 -m cli.blender_cli --project scene.json material assign 0 0
# Add modifiers
python3 -m cli.blender_cli --project scene.json modifier add subdivision_surface -o 0 -p levels=2
# Add camera and light
python3 -m cli.blender_cli --project scene.json camera add -l 7,-6,5 -r 63,0,46 --active
python3 -m cli.blender_cli --project scene.json light add sun -r -45,0,30
# Save
python3 -m cli.blender_cli --project scene.json scene save
# Generate render script
python3 -m cli.blender_cli --project scene.json render execute render.png --overwrite
# Execute with Blender (if installed)
blender --background --python /path/to/_render_script.py
```
## JSON Output Mode
All commands support `--json` for machine-readable output:
```bash
python3 -m cli.blender_cli --json scene new -o scene.json
python3 -m cli.blender_cli --json --project scene.json object list
```
## Preview and Live Preview
Blender exposes real preview bundles through the `preview` command group.
```bash
# Capture a real preview bundle
cli-anything-blender --json --project scene.blend-cli.json preview capture --recipe quick
# Query the latest bundle
cli-anything-blender --json --project scene.blend-cli.json preview latest --recipe quick
# Start a poll-mode live preview session
cli-anything-blender --json --project scene.blend-cli.json preview live start --recipe quick --mode poll --source-poll-ms 500
# Query current live-session state
cli-anything-blender --json --project scene.blend-cli.json preview live status --recipe quick
```
The default `quick` recipe produces real Blender-rendered `hero.png` and
`workbench.png` artifacts. Live sessions persist:
- `session.json`
- immutable bundle directories
- `trajectory.json`
Inspect or open published preview state with:
```bash
cli-hub previews inspect /path/to/bundle-or-session
cli-hub previews html /path/to/bundle-or-session -o page.html
cli-hub previews watch /path/to/session --open
cli-hub previews open /path/to/bundle-or-session
```
## Interactive REPL
```bash
python3 -m cli.blender_cli repl
# or with existing project:
python3 -m cli.blender_cli repl --project scene.json
```
## Command Groups
### Scene Management
```
scene new - Create a new scene
scene open - Open an existing scene file
scene save - Save the current scene
scene info - Show scene information
scene profiles - List available scene profiles
scene json - Print raw scene JSON
```
### Object Management
```
object add - Add a primitive (cube, sphere, cylinder, cone, plane, torus, monkey, empty)
object remove - Remove an object by index
object duplicate - Duplicate an object
object transform - Translate, rotate, or scale an object
object set - Set an object property
object list - List all objects
object get - Get detailed object info
```
### Material Management
```
material create - Create a new Principled BSDF material
material assign - Assign a material to an object
material set - Set a material property
material list - List all materials
material get - Get detailed material info
```
### Modifier Management
```
modifier list-available - List all available modifier types
modifier info - Show modifier details
modifier add - Add a modifier to an object
modifier remove - Remove a modifier
modifier set - Set a modifier parameter
modifier list - List modifiers on an object
```
### Camera Management
```
camera add - Add a camera
camera set - Set a camera property
camera set-active - Set the active camera
camera list - List all cameras
```
### Light Management
```
light add - Add a light (point, sun, spot, area)
light set - Set a light property
light list - List all lights
```
### Animation
```
animation keyframe - Set a keyframe on an object
animation remove-keyframe - Remove a keyframe
animation frame-range - Set the animation frame range
animation fps - Set the FPS
animation list-keyframes - List keyframes for an object
```
### Render
```
render settings - Configure render settings
render info - Show current render settings
render presets - List available render presets
render execute - Render the scene (generates bpy script)
render script - Generate bpy script to stdout
```
### Session
```
session status - Show session status
session undo - Undo the last operation
session redo - Redo the last undone operation
session history - Show undo history
```
## Running Tests
```bash
# From the agent-harness directory:
# Run all tests
python3 -m pytest cli/tests/ -v
# Run unit tests only
python3 -m pytest cli/tests/test_core.py -v
# Run E2E tests only
python3 -m pytest cli/tests/test_full_e2e.py -v
# Run with coverage
python3 -m pytest cli/tests/ -v --tb=short
```
## Architecture
```
cli/
โโโ __init__.py
โโโ __main__.py # python3 -m cli.blender_cli
โโโ blender_cli.py # Main CLI entry point (Click + REPL)
โโโ core/
โ โโโ __init__.py
โ โโโ scene.py # Scene create/open/save/info
โ โโโ objects.py # 3D object management
โ โโโ materials.py # Material management
โ โโโ modifiers.py # Modifier registry + add/remove/set
โ โโโ lighting.py # Camera and light management
โ โโโ animation.py # Keyframe and timeline management
โ โโโ render.py # Render settings and export
โ โโโ session.py # Stateful session, undo/redo
โโโ utils/
โ โโโ __init__.py
โ โโโ bpy_gen.py # Blender Python script generation
โโโ tests/
โโโ __init__.py
โโโ test_core.py # Unit tests (synthetic data, 100+ tests)
โโโ test_full_e2e.py # E2E tests (script gen, roundtrips, workflows)
```
## JSON Scene Format
The scene is stored as a JSON file with this structure:
```json
{
"version": "1.0",
"name": "scene_name",
"scene": { "fps": 24, "frame_start": 1, "frame_end": 250, ... },
"render": { "engine": "CYCLES", "resolution_x": 1920, "samples": 128, ... },
"world": { "background_color": [0.05, 0.05, 0.05], ... },
"objects": [ { "name": "Cube", "mesh_type": "cube", "location": [0,0,0], ... } ],
"materials": [ { "name": "Material", "color": [0.8,0.8,0.8,1], ... } ],
"cameras": [ { "name": "Camera", "focal_length": 50, ... } ],
"lights": [ { "name": "Light", "type": "POINT", "power": 1000, ... } ],
"collections": [ { "name": "Collection", "objects": [0, 1] } ],
"metadata": { "created": "...", "modified": "...", "software": "blender-cli 1.0" }
}
```
## Rendering
Since Blender's `.blend` format is binary, this CLI uses a JSON scene format
and generates Blender Python (bpy) scripts for rendering. The workflow:
1. Edit the scene using CLI commands (creates/modifies JSON)
2. Generate a bpy script with `render execute` or `render script`
3. Run the script with `blender --background --python script.py`
The generated scripts reconstruct the entire scene in Blender and render it.
---
## File: browser/agent-harness/cli_anything/browser/README.md
# cli-anything-browser โ Browser Automation CLI
A command-line interface for browser automation using [DOMShell](https://github.com/apireno/DOMShell)'s MCP server. Maps Chrome's Accessibility Tree to a virtual filesystem for agent-native browser automation.
## Features
- **Filesystem-first navigation**: Use `ls`, `cd`, `cat` to explore web pages
- **Search**: `grep` for text patterns in the accessibility tree
- **Actions**: `click`, `type` to interact with elements
- **JSON output**: `--json` flag for machine-readable output
- **Interactive REPL**: Stateful session with command history
- **Daemon mode**: Optional persistent connection for faster interactive use
## Installation
### Prerequisites
1. **Node.js and npx** (required for DOMShell MCP server):
```bash
# Install Node.js from https://nodejs.org/
node --version
npx --version
```
2. **Chrome/Chromium** with DOMShell extension:
- Install DOMShell from [Chrome Web Store](https://chromewebstore.google.com/detail/domshell-%E2%80%94-browser-filesy/okcliheamhmijccjknkkplploacoidnp)
- Ensure Chrome is running before using the CLI
3. **Python 3.10+**:
```bash
python --version
```
### Install CLI
```bash
cd browser/agent-harness
pip install -e .
```
Verify installation:
```bash
cli-anything-browser --help
```
## Usage
### One-Shot Commands
```bash
# Open a page
cli-anything-browser page open https://example.com
# List elements at root
cli-anything-browser fs ls /
# Navigate into a section
cli-anything-browser fs cd /main
# List elements in current directory
cli-anything-browser fs ls
# Read element content
cli-anything-browser fs cat /main/button[0]
# Search for text
cli-anything-browser fs grep "Login"
# Click an element
cli-anything-browser act click /main/button[0]
# Type into an input
cli-anything-browser act type /main/input[0] "Hello, World!"
# Get page info
cli-anything-browser page info
# Navigate back/forward
cli-anything-browser page back
cli-anything-browser page forward
```
**Note:** One-shot commands each start with a fresh session (no URL or working directory). For stateful workflows (like `cd` followed by `ls` without a path), use the REPL instead.
### JSON Output
```bash
# Get machine-readable output
cli-anything-browser --json fs ls /
# Returns:
{
"path": "/",
"entries": [
{
"name": "main",
"role": "landmark",
"path": "/main"
}
]
}
```
### Daemon Mode (Persistent Connection)
For faster interactive use, start daemon mode within a REPL session:
```bash
# Start REPL with daemon mode
cli-anything-browser --daemon
# Or start daemon within REPL
session daemon-start
# Run commands (uses persistent connection)
fs ls /
fs cd /main
# Stop daemon when done
session daemon-stop
```
**Note:** Daemon mode only works within a single running process (REPL or `--daemon` flag). State does not persist across separate CLI invocations.
### Interactive REPL
Run without arguments to enter interactive mode:
```bash
cli-anything-browser
```
REPL commands:
- `page open ` โ Open a URL
- `fs ls [path]` โ List elements
- `fs cd ` โ Change directory
- `fs cat [path]` โ Read element
- `fs grep ` โ Search for text
- `fs pwd` โ Print working directory
- `act click ` โ Click element
- `act type ` โ Type text
- `session status` โ Show session state
- `help` โ Show commands
- `quit` โ Exit REPL
## Command Groups
### `page` โ Page Navigation
- `open ` โ Navigate to URL
- `reload` โ Reload current page
- `back` โ Navigate back in history
- `forward` โ Navigate forward in history
- `info` โ Show current page info
### `fs` โ Filesystem Commands
- `ls [path]` โ List elements at path
- `cd ` โ Change directory
- `cat [path]` โ Read element content
- `grep [path]` โ Search for text
- `pwd` โ Print working directory
### `act` โ Action Commands
- `click ` โ Click an element
- `type ` โ Type text into input
### `session` โ Session Management
- `status` โ Show session status
- `daemon-start` โ Start persistent daemon mode
- `daemon-stop` โ Stop daemon mode
## Path Syntax
DOMShell uses a filesystem-like path syntax for the Accessibility Tree:
```
/ โ Root (page)
/main โ Main landmark
/main/div[0] โ First div in main
/main/div[0]/button[2] โ Third button in first div
```
Array indices are 0-based. Use relative paths with `..` to go up.
## Examples
### Basic Navigation
```bash
# Open a page
cli-anything-browser page open https://example.com
# Explore structure
cli-anything-browser fs ls /
cli-anything-browser fs cd /main
cli-anything-browser fs ls
# Go back to root
cli-anything-browser fs cd /
```
### Search and Click
```bash
# Open page and search for login button
cli-anything-browser page open https://example.com/login
cli-anything-browser fs grep "Login"
# Click the login button (adjust path as needed)
cli-anything-browser act click /main/button[0]
```
### Form Fill
```bash
# Type into form fields
cli-anything-browser act type /main/input[0] "user@example.com"
cli-anything-browser act type /main/input[1] "password123"
# Click submit
cli-anything-browser act click /main/button[0]
```
## Testing
Run tests:
```bash
# Unit tests (no Chrome required)
pytest cli_anything/browser/tests/test_core.py -v
# E2E tests (requires Chrome + DOMShell)
pytest cli_anything/browser/tests/test_full_e2e.py -v
```
## Troubleshooting
### "npx not found"
Install Node.js from https://nodejs.org/
### "DOMShell not found"
Run: `npx @apireno/domshell --version` (first run downloads the package)
### "DOMShell MCP call failed"
- Ensure Chrome is running
- Install DOMShell extension from Chrome Web Store
- Check that DOMShell is enabled in Chrome
### Commands hang on first use
First `npx` call downloads DOMShell package (10-50 MB). Subsequent calls are faster. Use `--daemon` mode for persistent connection.
## Architecture
This CLI follows the [CLI-Anything harness methodology](https://github.com/HKUDS/CLI-Anything/tree/main/cli-anything-plugin/HARNESS.md):
- **Backend**: DOMShell MCP server via stdio transport
- **State**: Page state (URL, working directory, navigation history)
- **Pattern**: Filesystem-first commands map to Accessibility Tree
## Links
- [DOMShell GitHub](https://github.com/apireno/DOMShell)
- [CLI-Anything](https://github.com/HKUDS/CLI-Anything)
- [Issue #90](https://github.com/HKUDS/CLI-Anything/issues/90)
## License
Apache License 2.0 โ See [CLI-Anything](https://github.com/HKUDS/CLI-Anything) for details.
---
## File: cli-anything-plugin/guides/filter-translation.md
# Filter Translation Pitfalls
When translating effects between formats (e.g., MLT โ ffmpeg), watch for these common issues.
## Duplicate Filter Types
Some tools (ffmpeg) don't allow the same filter twice in a chain. If your project has both `brightness` and `saturation` filters, and both map to ffmpeg's `eq=`, you must **merge** them into a single `eq=brightness=X:saturation=Y`.
## Ordering Constraints
ffmpeg's `concat` filter requires **interleaved** stream ordering:
`[v0][a0][v1][a1][v2][a2]`, NOT grouped `[v0][v1][v2][a0][a1][a2]`.
The error message ("media type mismatch") is cryptic if you don't know this.
## Parameter Space Differences
Effect parameters often use different scales:
- MLT brightness `1.15` = +15%
- ffmpeg `eq=brightness=0.06` on a -1..1 scale
Document every mapping explicitly.
## Unmappable Effects
Some effects have no equivalent in the render tool. Handle gracefully (warn, skip) rather than crash.
---
## File: cli-anything-plugin/guides/mcp-backend.md
# MCP Backend Pattern
For services that expose an MCP (Model Context Protocol) server instead of a traditional CLI.
## When to Use
- The software has an official or community MCP server
- No native CLI exists, or MCP provides better functionality
- You want to integrate AI/agent tools that speak MCP protocol
**Use case:** When the software provides an MCP server instead of a traditional CLI.
Example: DOMShell provides browser automation via MCP tools.
## Backend Wrapper (`utils/_backend.py`)
```python
import asyncio
from typing import Any
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def _call_tool(tool_name: str, arguments: dict) -> Any:
"""Call an MCP tool."""
server_params = StdioServerParameters(
command="npx",
args=["@apireno/domshell"]
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
result = await session.call_tool(tool_name, arguments)
return result
def is_available() -> bool:
"""Check if MCP server is available."""
# Try to spawn and verify
...
# Sync wrappers for each tool
def ls(path: str = "/") -> dict:
"""List directory contents."""
return asyncio.run(_call_tool("domshell_ls", {"path": path}))
```
## Session Management
- MCP server spawns per command (stateless from server perspective)
- CLI maintains state (URL, working directory, navigation history)
- Each command re-spawns the MCP server process
## Daemon Mode (Optional)
- Spawn MCP server once, reuse connection for multiple commands
- Reduces latency for interactive use
- Requires explicit start/stop or `--daemon` flag
## Dependencies
Add `mcp>=0.1.0` to `install_requires`.
## Example Implementations
- `browser/agent-harness` โ DOMShell MCP server for browser automation
- See: https://github.com/HKUDS/CLI-Anything/tree/main/browser/agent-harness
---
## File: cli-anything-plugin/guides/pypi-publishing.md
# PyPI Publishing and Installation (Phase 7)
After building and testing the CLI, make it installable and discoverable.
All cli-anything CLIs use **PEP 420 namespace packages** under the shared
`cli_anything` namespace. This allows multiple CLI packages to be installed
side-by-side in the same Python environment without conflicts.
## 1. Package Structure
```
agent-harness/
โโโ setup.py
โโโ cli_anything/ # NO __init__.py here (namespace package)
โโโ / # e.g., gimp, blender, audacity
โโโ __init__.py # HAS __init__.py (regular sub-package)
โโโ _cli.py
โโโ core/
โโโ utils/
โโโ tests/
```
The key rule: `cli_anything/` has **no** `__init__.py`. Each sub-package
(`gimp/`, `blender/`, etc.) **does** have `__init__.py`. This is what
enables multiple packages to contribute to the same namespace.
## 2. setup.py Template
Create `setup.py` in the `agent-harness/` directory:
```python
from setuptools import setup, find_namespace_packages
setup(
name="cli-anything-",
version="1.0.0",
packages=find_namespace_packages(include=["cli_anything.*"]),
install_requires=[
"click>=8.0.0",
"prompt-toolkit>=3.0.0",
# Add Python library dependencies here
],
entry_points={
"console_scripts": [
"cli-anything-=cli_anything.._cli:main",
],
},
python_requires=">=3.10",
)
```
**Important details:**
- Use `find_namespace_packages`, NOT `find_packages`
- Use `include=["cli_anything.*"]` to scope discovery
- Entry point format: `cli_anything.._cli:main`
- The **system package** (LibreOffice, Blender, etc.) is a **hard dependency**
that cannot be expressed in `install_requires`. Document it in README.md and
have the backend module raise a clear error with install instructions:
```python
# In utils/_backend.py
def find_():
path = shutil.which("")
if path:
return path
raise RuntimeError(
" is not installed. Install it with:\n"
" apt install # Debian/Ubuntu\n"
" brew install # macOS"
)
```
## 3. Import Convention
All imports use the `cli_anything.` prefix:
```python
from cli_anything.gimp.core.project import create_project
from cli_anything.gimp.core.session import Session
from cli_anything.blender.core.scene import create_scene
```
## 4. Verification Steps
**Test local installation:**
```bash
cd /root/cli-anything//agent-harness
pip install -e .
```
**Verify PATH installation:**
```bash
which cli-anything-
cli-anything- --help
```
**Run tests against the installed command:**
```bash
cd /root/cli-anything//agent-harness
CLI_ANYTHING_FORCE_INSTALLED=1 python3 -m pytest cli_anything//tests/ -v -s
```
The output must show `[_resolve_cli] Using installed command: /path/to/cli-anything-`
confirming subprocess tests ran against the real installed binary, not a module fallback.
**Verify namespace works across packages** (when multiple CLIs installed):
```python
import cli_anything.gimp
import cli_anything.blender
# Both resolve to their respective source directories
```
## Why Namespace Packages
- Multiple CLIs coexist in the same Python environment without conflicts
- Clean, organized imports under a single `cli_anything` namespace
- Each CLI is independently installable/uninstallable via pip
- Agents can discover all installed CLIs via `cli_anything.*`
- Standard Python packaging โ no hacks or workarounds
---
## File: cli-anything-plugin/guides/session-locking.md
# Session File Locking
When saving session JSON, use exclusive file locking to prevent concurrent writes from corrupting data.
## The Problem
Never use bare `open("w") + json.dump()` โ `open("w")` truncates the file before any lock can be acquired.
## The Solution: `_locked_save_json`
Open with `"r+"`, lock, then truncate inside the lock:
```python
def _locked_save_json(path, data, **dump_kwargs) -> None:
"""Atomically write JSON with exclusive file locking."""
try:
f = open(path, "r+") # no truncation on open
except FileNotFoundError:
os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
f = open(path, "w") # first save โ file doesn't exist yet
with f:
_locked = False
try:
import fcntl
fcntl.flock(f.fileno(), fcntl.LOCK_EX)
_locked = True
except (ImportError, OSError):
pass # Windows / unsupported FS โ proceed unlocked
try:
f.seek(0)
f.truncate() # truncate INSIDE the lock
json.dump(data, f, **dump_kwargs)
f.flush()
finally:
if _locked:
fcntl.flock(f.fileno(), fcntl.LOCK_UN)
```
Copy this pattern into `core/session.py` for all session saves.