🧰 TermKitCLI

The Action Engine for your Terminal.
Safe. Reversible. Productive.

TermKitCLI is a "Swiss-Army Knife" for heavy terminal users who want the speed of the CLI without the risk of irreversible mistakes. It replaces dangerous commands with smart, localized actions backed by a persistent SQLite history engine.

---

🚀 Why TermKitCLI?

• 🛡️ Safety First: Never lose a file again. Every destructive action is reversible.
• ↩️ Undo/Redo: Mistakenly deleted a file? termkitcli undo. Changed your mind? termkitcli redo.
• 🗑️ Smart Trash: A project-aware trash system that lists and restores files by ID.
• 📦 Shelf: Need to clear your workspace? Shelf your files temporarily and restore them later.
• 🧹 Clean: Intelligently scan projects for junk (.tmp, __pycache__) and remove them safely.
• 👀 Watch: Monitor running commands and see diffs of output changes in real-time.

---

📥 Installation

We provide an automated installer that sets up an isolated environment for you.

Quick Install

# 1. Clone the repository
git clone https://github.com/yourusername/termkitcli.git
cd termkitcli

# 2. Run the installer script
./init.sh

The script will automatically:

• Check for Python 3.10+
• Install via pipx (if available) for global access.
• OR create a local verified virtual environment (.venv).

Manual Install

If you prefer standard pip:

pip install .

---

📖 User Manual

1. Trash (Safe Delete)

Stop using rm. Use trash to archive files safely.

Command	Description
termkitcli trash put <files>	Move files to the trash.
termkitcli trash list	View files currently in the trash.
termkitcli undo	Restore the last trashed items.

Example:

$ termkitcli trash put main.py README.old
[green]Trashed 2 files.[/green]

$ termkitcli undo
[green]Undid action:[/green] trash.put (8a2b3c...)

2. Shelf (Temporary Storage)

The "Shelf" is for files you generally want to keep but need out of the way right now. Perfect for clearing screenshots or logs before a demo.

Command	Description
termkitcli shelf put <files>	Move files to the shelf.
termkitcli shelf list	See what's on the shelf.
termkitcli undo	Bring shelved items back.

3. Clean (Junk Removal)

Scans your directory for common clutter (.DS_Store, *.tmp, __pycache__, etc.) and offers to trash them.

Command	Description
termkitcli clean scan <path>	Preview junk files found in the path.
termkitcli clean apply <path>	Move identified junk to the trash.

Note: Since clean apply uses the trash module, you can undo a cleanup if it removed something important!

4. Watch (Live Monitoring)

Run a command repeatedly and highlight exactly what changed between runs.

Command	Description
termkitcli watch "<cmd>"	Run command every 2s.
--every <seconds>	Set the interval.
--only-change	Only update screen when output changes.

Example:

# Watch for file changes
termkitcli watch "ls -la" --every 1 --only-change

5. Global Action History

TermKitCLI remembers what you did.

Command	Description
termkitcli history	Show a log of all actions.
termkitcli undo	Reverse the most recent action.
termkitcli redo	Re-apply the last undone action.

---

⚙️ Architecture

TermKitCLI is built on the Command Pattern.

• Database: SQLite (~/.termkit/actions.db) stores action state.
• Reversibility: Every action class implements both execute and inverse.
• Isolation: Modules (Trash, Shelf) are independent but share the core Action Engine.

🤝 Contributing

1. Fork the repo.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

---

License: MIT
Author: Antigravity