CLI-Anything/CONTRIBUTING.md

Contributing to CLI-Anything

Thank you for your interest in contributing to CLI-Anything! This guide will help you get started.

Types of Contributions

We welcome three main categories of contributions:

A) CLIs for New Software

Adding a new CLI harness is the most impactful contribution. Before submitting a PR, ensure the following are in place:

1. <SOFTWARE>.md — the SOP document exists at <software>/agent-harness/<SOFTWARE>.md describing the harness architecture.
2. SKILL.md — the AI-discoverable skill definition exists inside the Python package at cli_anything/<software>/SKILL.md.
3. Tests — unit tests (test_core.py, passable without backend) and E2E tests (test_full_e2e.py) are present and passing.
4. README.md — the project README includes the new software with a link to its harness directory.
5. registry.json — add an entry for the new software so it appears on the CLI-Hub.
6. repl_skin.py — an unmodified copy from the plugin exists in utils/.

B) New Features

Feature contributions improve existing harnesses or the plugin framework. Examples include new CLI commands, output formats, backend improvements, or cross-platform fixes.

• Open an issue first to discuss the feature before starting work.
• Follow existing code patterns and conventions in the target harness.
• Include tests for any new functionality.

C) Bug Fixes

Bug fixes resolve incorrect behavior in existing harnesses or the plugin.

• Reference the related issue in your PR (e.g., Fixes #123).
• Include a test that reproduces the bug and verifies the fix.
• Ensure all existing tests for the affected harness still pass.

CLI-Hub & Registry

All available CLIs are listed in registry.json at the repo root and displayed on the CLI-Hub. The hub reads registry.json directly from main, so it updates immediately when a PR is merged.

Adding a new CLI to the Hub

Include an entry in registry.json as part of your PR. Each entry has this shape:

{
  "name": "my-software",
  "display_name": "My Software",
  "version": "1.0.0",
  "description": "Short description of what the CLI does",
  "requires": "backend software or null",
  "install_cmd": "pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=my-software/agent-harness",
  "entry_point": "cli-anything-my-software",
  "skill_md": "my-software/agent-harness/cli_anything/my_software/skills/SKILL.md",
  "category": "category-name"
}

Updating an existing CLI on the Hub

When you modify an existing harness, update its registry.json entry in the same PR:

• Bump the version field to reflect the change.
• Update description, requires, or category if they changed.
• The hub will reflect the update as soon as the PR is merged to main.

Development Setup

Each generated CLI lives in <software>/agent-harness/ and is an independent Python package:

# Clone the repo
git clone https://github.com/HKUDS/CLI-Anything.git
cd CLI-Anything

# Install a harness in editable mode
cd <software>/agent-harness
pip install -e .

# Run tests
python3 -m pytest cli_anything/<software>/tests/ -v

Requirements

• Python 3.10+
• Click 8.0+
• pytest 7.0+

Code Style

• Follow PEP 8 conventions.
• Use type hints where practical.
• All CLI commands must support the --json flag for machine-readable output.

Commit Messages

Use clear, descriptive commit messages following the conventional format:

feat: add Krita CLI harness
fix: resolve Blender backend path on macOS
docs: update README with new software entry
test: add unit tests for Inkscape layer commands

Running Tests

# Unit tests (no backend software needed)
python3 -m pytest cli_anything/<software>/tests/test_core.py -v

# E2E tests (requires real backend installed)
python3 -m pytest cli_anything/<software>/tests/test_full_e2e.py -v

# All tests for a harness
python3 -m pytest cli_anything/<software>/tests/ -v

Submitting a Pull Request

1. Fork the repository and create a feature branch from main.
2. Make your changes following the guidelines above.
3. Ensure all tests pass for any harnesses you modified.
4. Push your branch and open a Pull Request against main.
5. Fill out the PR template completely.

Questions?

If you have questions, feel free to open a Discussion or an issue tagged with type: question.