magic-terminal-cli 1.0.0

A magical terminal assistant that understands natural language and makes command-line operations effortless

🪄 Magic Terminal

Magic Terminal is a cross-platform, AI-assisted command-line copilot that converts natural language instructions into safe, auditable shell commands. It streamlines installation, automation, diagnostics, and development workflows while providing human-readable previews, intelligent recovery, and multi-model failovers.

---

🔥 Highlights

• Natural Language Automation — Describe desired outcomes (e.g., "install docker and start it") and Magic Terminal synthesizes the shell commands.
• Safety First — Every command is previewed with context, destructive patterns are flagged, and execution requires confirmation (unless auto-confirm is enabled).
• Intelligent Recovery — When commands fail, Magic Terminal analyzes stderr, suggests fixes, and retries with smarter alternatives.
• Multi-LLM Backends — Works with OpenAI, Grok (xAI), and local Ollama models; degrades gracefully to deterministic heuristics.
• Cross-Platform Tooling — Supports package managers, filesystem operations, process management, system monitoring, and development workflows on macOS, Linux, and Windows.
• Persistent Experience — Saves history, configuration, bookmarks, and aliases to the user's home directory.

---

⚡ Quick Start

# Clone repository
git clone https://github.com/Yogesh-developer/magic-terminal.git
cd magic-terminal

# Install dependencies
pip3 install -r requirements.txt

# Install Magic Terminal in editable mode
pip3 install -e .

# Launch the assistant
magic-terminal

If your shell cannot find the magic-terminal script, append the Python user-bin path to PATH (macOS example):

echo 'export PATH="$HOME/Library/Python/3.9/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Aliases magic and mt are also installed for convenience.

---

📦 Installation Methods

• PyPI install (users)

  pip install magic-terminal-cli
  

• Editable install (development)

  pip3 install -e .
  

• Direct GitHub install (users)

  pip install git+https://github.com/Yogesh-developer/magic-terminal.git
  

• Virtual environment isolation

  python3 -m venv venv
  source venv/bin/activate
  pip install -e .
  

---

🤖 Configuring AI Backends

Magic Terminal automatically selects the first available backend in this order:

1. OpenAI (requires OPENAI_API_KEY)
2. Grok / X.AI (XAI_API_KEY or GROK_API_KEY)
3. Ollama (local models at OLLAMA_URL, default http://localhost:11434)
4. Heuristic fallback

Set environment variables in your shell profile:

export OPENAI_API_KEY="sk-..."          # Optional: OpenAI GPT
export XAI_API_KEY="xai-..."            # Optional: Grok
export GROK_API_KEY="xai-..."           # Alias for Grok
export OLLAMA_URL="http://localhost:11434"
export AI_TERMINAL_ALLOW_FALLBACK=1      # Allow heuristics when LLM fails

Ollama Setup (local LLM)

curl -fsSL https://ollama.ai/install.sh | sh
ollama pull llama3:8b
ollama serve

Run magic-terminal --setup to verify connectivity and dependencies.

---

🕹️ Usage Guide

Launching the CLI:

magic-terminal

Example interactions:

🪄 Magic-Terminal> install docker desktop
🪄 Magic-Terminal> show me running processes using too much memory
🪄 Magic-Terminal> create python backup_logs.py that compresses yesterday's logs
🪄 Magic-Terminal> delete all .tmp files in the current directory

Each request produces an execution plan similar to:

🎯 Install Docker Desktop
📂 Working Directory: /Users/alex
⚡ Commands:
  brew install --cask docker
✅ Execute these commands? [y/N]:

Commands are executed only after confirmation (unless configured otherwise). Output is streamed live, and failures trigger automatic recovery attempts.

Exit the assistant with exit, quit, or Ctrl+C.

---

📚 Command Catalogue

Magic Terminal’s LLM-guided behavior covers a wide range of topics:

• Package Management — install/uninstall packages, update systems, search repositories.
• File & Project Operations — create templates, organize directories, scaffold projects.
• Process & Service Control — list processes, kill tasks, inspect services, analyze logs.
• System Monitoring — inspect CPU/memory usage, disk utilization, network stats, system info.
• Development Tooling — manage git workflows, run tests, configure environments, lint code.
• Navigation & Productivity — change directories intelligently, bookmark locations, manage aliases.

Because results are LLM-driven, review the command preview carefully before approving execution.

---

🔁 Intelligent Recovery

When a command fails, Magic Terminal:

1. Parses stderr and identifies known failure patterns.
2. Suggests alternative commands (e.g., macOS top -o %MEM ➜ top -o mem -l 1).
3. Executes alternatives automatically until a success or all options are exhausted.
4. Falls back to heuristic commands if the LLM backend is unavailable.

Recovery activity is logged to ~/.magic_terminal_logs/enhanced_terminal.log for auditing.

---

⚙️ Configuration & Persistence

• Configuration file: ~/.magic_terminal_config.json

  {
    "auto_confirm_safe": false,
    "use_trash": true,
    "max_history": 1000,
    "bookmarks": {},
    "aliases": {},
    "preferred_package_manager": null
  }
  

• Command history: ~/.magic_terminal_history
• Logs: ~/.magic_terminal_logs/

Bookmarks, aliases, and preferences can be updated interactively or by editing the config file.

---

🛠️ Development Workflow

git clone https://github.com/Yogesh-developer/magic-terminal.git
cd magic-terminal

python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -e .[dev]
pre-commit install

# Run automated tests
pytest

---

✅ Testing Checklist

• Automated tests: pytest (covers config migrations, HTTP retry logic, and safety auditing)
• Manual scenarios:
  • Offline mode (no API keys, Ollama down) ➜ verify heuristic fallback
  • Package installation on macOS/Linux/Windows ➜ confirm smart suggestions
  • Resource monitoring commands ➜ confirm platform-specific handling
• Smoke test: python3 ai_terminal/main.py
• Formatting (optional): black ai_terminal/

---

🐞 Troubleshooting

• Command not found (magic-terminal) — add the user scripts directory to PATH (see Quick Start).
• LLM response invalid / JSON parsing errors — check logs and ensure the system prompt enforces JSON; fallback is automatic after three attempts.
• urllib3 NotOpenSSLWarning on macOS — macOS ships LibreSSL; install Python via Homebrew or ignore (warning only).
• Permission denied — Magic Terminal detects destructive commands and prompts for confirmation; rerun with sudo if needed.
• Ollama connection errors — verify ollama serve is running and OLLAMA_URL matches.

---

❓ FAQ

• Does Magic Terminal require internet access? No, if you use Ollama with local models. OpenAI and Grok require internet access.

• Can I run it non-interactively? Batch mode is on the roadmap. For now, use the interactive CLI or integrate EnhancedAITerminal directly in Python scripts.

• How do I disable command confirmation? Set "auto_confirm_safe": true in the configuration file (feature toggle coming to CLI).

• Is Windows supported? Yes. Package suggestions use Chocolatey (choco) or Winget, and PowerShell commands are generated when appropriate.

• How do I uninstall?

  pip3 uninstall magic-terminal-cli
  

---

🙌 Acknowledgements

{{ ... }}

• OpenAI and Grok for compatible API backends.
• Rich for terminal rendering utilities.
• psutil for system metrics collection.

---

📄 License

Magic Terminal is distributed under the MIT License. See LICENSE for full details.