clingy-cli 1.0.0

Context-aware CLI framework with fuzzy search menus and auto-discovery - Build interactive command-line tools that cling to your workflow

clingy

Context-aware CLI framework for building interactive command-line tools with fuzzy search menus and modular command architecture. Works like Git, Poetry, or Terraform—install once, use everywhere.

---

The Problem & The Solution

Building CLI tools often feels like choosing between two extremes: a rigid, complex framework that takes days to learn, or a messy collection of scripts that are impossible to maintain.

Clingy was born to bridge that gap. It solves the "CLI fatigue" by providing a framework where automation meets interaction.

Why Clingy?

• Zero-Boilerplate Discovery: Just drop a file in your commands/ folder, and it's instantly available in your CLI. No manual registration, no complex routing.
• Interactive by Default: Every command you write automatically gains a, fuzzy-searchable menu (powered by fzf). You build the logic once; the framework provides the interface.
• Submenu Architecture: Use our intuitive node-based system to build complex, nested menus that feel like professional-grade software.
• Context-Aware: Like Git, Clingy automatically detects your project root. Run it from any subdirectory, and it knows exactly where it is.

---

Documentation Hub

See the Interactive Documentation.

Navigate through the project documentation:

Framework Reference

• Architecture — Internal design and execution flow.
• Creating Commands — Guide for building custom CLI commands.

Project Templates

• Basic Template — Simple CLI for prototyping.
• Konfig Template — Dotfiles and symlink manager.
• Serverless Template — AWS Lambda + Go workflow manager.

---

Showcase

Clingy basic starter template

https://github.com/user-attachments/assets/61247d3c-2900-472d-a4fc-a7b3b551edf7

Clingy konfigs template

https://github.com/user-attachments/assets/c11d5731-9a4e-4163-8b86-06463003d677

---

Installation

# Using uv (recommended)
uv pip install clingy

# Using pip
pip install clingy

Required Dependency: fzf (fuzzy finder). Install via your package manager (brew, apt, pacman, etc.).

---

Quick Start

1. Initialize

mkdir my-tool && cd my-tool
clingy init

2. Run

clingy                # Interactive mode (fzf menu)
clingy greet --name User  # CLI mode

3. Update Framework

If a template update is available, sync your project files while preserving your configuration:

clingy --update-template

---

Contributing & Testing

# Install in editable mode
pip install -e .

# Run tests
pytest tests/

# Format code
black . --line-length 100
isort . --profile black

---

License

MIT Maintainer: @ncasatti