hey-cli-python 1.0.0__tar.gz

hey_cli_python-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohit S.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hey_cli_python-1.0.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: hey-cli-python
+Version: 1.0.0
+Summary: A secure, zero-bloat CLI companion that turns natural language and error logs into executable commands.
+Author: Mohit S.
+Project-URL: Homepage, https://github.com/sinsniwal/hey-cli
+Project-URL: Repository, https://github.com/sinsniwal/hey-cli
+Project-URL: Issues, https://github.com/sinsniwal/hey-cli/issues
+Keywords: cli,llm,bash,terminal,ollama,sysadmin
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: ollama>=0.1.0
+Requires-Dist: rich>=13.0.0
+Dynamic: license-file
+
+<div align="center">
+  <h1>hey-cli 🤖</h1>
+  <p><strong>A zero-bloat, privacy-first, locally-hosted CLI agent powered by Ollama.</strong></p>
+
+  <img src="https://img.shields.io/badge/Python-3.9+-blue.svg" alt="Python Version" />
+  <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License" />
+  <img src="https://img.shields.io/badge/Ollama-Local-orange.svg" alt="Ollama Local" />
+</div>
+
+<br>
+
+`hey` isn't just an LLM wrapper. It's a context-aware system agent designed to bridge the gap between human language and POSIX shell utilities natively on your host machine.
+
+> Ask it to parse your error logs, debug Docker, clear DNS caches, or execute complex file maneuvers—all while executing safely behind a dynamic zero-trust governance matrix.
+
+## 🚀 Why `hey-cli` over Copilot/ChatGPT?
+1. **Total Privacy**: Your code and system logs never leave your physical CPU. All context gathering and reasoning is done locally via [Ollama](https://ollama.com).
+2. **True Cross-Platform Skills**: Under the hood, `hey-cli`'s "Skills Engine" detects if you're on macOS (BSD), Ubuntu (GNU), Windows (PowerShell), or Arch Linux, and actively refuses to generate incompatible flags like `xargs -d` on Mac.
+3. **Agentic Execution**: Ask "is docker running?" and `hey` will silently execute `docker info` in the background, read the stdout, analyze it, and return a plain English answer.
+4. **Security Governance**: Built-in AST-level parsing. Safe commands (like `git status`) auto-run. Destructive commands (`rm -rf`, `-exec delete`) require explicit typed confirmation.
+
+## 📦 Installation
+
+**Prerequisite:** You must have [Python 3.9+](https://www.python.org/downloads/) installed.
+
+### macOS & Linux
+Paste this snippet into your terminal to auto-install `pipx`, `ollama`, pull the required language model, and build `hey-cli` natively.
+```bash
+curl -sL https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.sh | bash
+```
+
+### Windows (PowerShell)
+Paste this into your PowerShell terminal:
+```powershell
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.ps1" -OutFile "$env:TEMP\hey_install.ps1"; & "$env:TEMP\hey_install.ps1"
+```
+
+## 🛠️ Usage
+
+Simply type `hey` followed by your objective.
+
+**Context-Gathering (Zero-Trust)**
+```bash
+hey is my docker hub running?
+```
+*`hey` will silently run `systemctl is-active docker` or `docker info`, see that it failed to connect to the socket, and explain the situation.*
+
+**Execution (Governance Protected)**
+```bash
+hey forcefully delete all .pyc files
+```
+*`hey` parses the generated `find . -name "*.pyc" -exec rm -f {} +` command, detects `rm` and `-exec` triggers, and pauses execution until you explicitly type `rm` to authorize.*
+
+**Debugging Logs**
+```bash
+npm run build 2>&1 | hey what is causing this webpack error?
+```
+
+## 🛡️ Governance Matrix
+Safety is a first-class citizen. `hey-cli` maintains a local governance database (`~/.hey-rules.json`):
+- **Never List**: Things like `rm -rf /` and `mkfs` are permanently blocked at the compiler level.
+- **Explicit Confirm**: High-risk ops (`truncate`, `drop`, `rm`) require typing exact keyword verification.
+- **Y/N Confirm**: Moderate risk ops requiring a quick `y`.
+- **Allowed List**: Safe diagnostics like `cat`, `ls`, `grep` auto-run natively.
+
+## 🤝 Adding OS Skills
+Is `hey` generating incorrect shell semantics for your niche operating system? 
+
+You can make it permanently smarter without touching code! Simply open `hey_cli/skills/` and create a markdown file for your OS containing explicit English instructions (e.g. "Do not use apt on Alpine, use apk add"). The engine dynamically parses `.md` rulesites at runtime. Pull requests are heavily welcomed!

hey_cli_python-1.0.0/README.md

@@ -0,0 +1,69 @@
+<div align="center">
+  <h1>hey-cli 🤖</h1>
+  <p><strong>A zero-bloat, privacy-first, locally-hosted CLI agent powered by Ollama.</strong></p>
+
+  <img src="https://img.shields.io/badge/Python-3.9+-blue.svg" alt="Python Version" />
+  <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License" />
+  <img src="https://img.shields.io/badge/Ollama-Local-orange.svg" alt="Ollama Local" />
+</div>
+
+<br>
+
+`hey` isn't just an LLM wrapper. It's a context-aware system agent designed to bridge the gap between human language and POSIX shell utilities natively on your host machine.
+
+> Ask it to parse your error logs, debug Docker, clear DNS caches, or execute complex file maneuvers—all while executing safely behind a dynamic zero-trust governance matrix.
+
+## 🚀 Why `hey-cli` over Copilot/ChatGPT?
+1. **Total Privacy**: Your code and system logs never leave your physical CPU. All context gathering and reasoning is done locally via [Ollama](https://ollama.com).
+2. **True Cross-Platform Skills**: Under the hood, `hey-cli`'s "Skills Engine" detects if you're on macOS (BSD), Ubuntu (GNU), Windows (PowerShell), or Arch Linux, and actively refuses to generate incompatible flags like `xargs -d` on Mac.
+3. **Agentic Execution**: Ask "is docker running?" and `hey` will silently execute `docker info` in the background, read the stdout, analyze it, and return a plain English answer.
+4. **Security Governance**: Built-in AST-level parsing. Safe commands (like `git status`) auto-run. Destructive commands (`rm -rf`, `-exec delete`) require explicit typed confirmation.
+
+## 📦 Installation
+
+**Prerequisite:** You must have [Python 3.9+](https://www.python.org/downloads/) installed.
+
+### macOS & Linux
+Paste this snippet into your terminal to auto-install `pipx`, `ollama`, pull the required language model, and build `hey-cli` natively.
+```bash
+curl -sL https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.sh | bash
+```
+
+### Windows (PowerShell)
+Paste this into your PowerShell terminal:
+```powershell
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.ps1" -OutFile "$env:TEMP\hey_install.ps1"; & "$env:TEMP\hey_install.ps1"
+```
+
+## 🛠️ Usage
+
+Simply type `hey` followed by your objective.
+
+**Context-Gathering (Zero-Trust)**
+```bash
+hey is my docker hub running?
+```
+*`hey` will silently run `systemctl is-active docker` or `docker info`, see that it failed to connect to the socket, and explain the situation.*
+
+**Execution (Governance Protected)**
+```bash
+hey forcefully delete all .pyc files
+```
+*`hey` parses the generated `find . -name "*.pyc" -exec rm -f {} +` command, detects `rm` and `-exec` triggers, and pauses execution until you explicitly type `rm` to authorize.*
+
+**Debugging Logs**
+```bash
+npm run build 2>&1 | hey what is causing this webpack error?
+```
+
+## 🛡️ Governance Matrix
+Safety is a first-class citizen. `hey-cli` maintains a local governance database (`~/.hey-rules.json`):
+- **Never List**: Things like `rm -rf /` and `mkfs` are permanently blocked at the compiler level.
+- **Explicit Confirm**: High-risk ops (`truncate`, `drop`, `rm`) require typing exact keyword verification.
+- **Y/N Confirm**: Moderate risk ops requiring a quick `y`.
+- **Allowed List**: Safe diagnostics like `cat`, `ls`, `grep` auto-run natively.
+
+## 🤝 Adding OS Skills
+Is `hey` generating incorrect shell semantics for your niche operating system? 
+
+You can make it permanently smarter without touching code! Simply open `hey_cli/skills/` and create a markdown file for your OS containing explicit English instructions (e.g. "Do not use apt on Alpine, use apk add"). The engine dynamically parses `.md` rulesites at runtime. Pull requests are heavily welcomed!

hey_cli_python-1.0.0/hey_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

hey_cli_python-1.0.0/hey_cli/cli.py

@@ -0,0 +1,81 @@
+import argparse
+import sys
+import os
+
+from .governance import GovernanceEngine
+from .llm import generate_command
+from .history import HistoryManager
+from .runner import CommandRunner
+from rich.console import Console
+
+console = Console()
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="hey-cli: a secure, zero-bloat CLI companion.",
+        formatter_class=argparse.RawTextHelpFormatter
+    )
+    
+    parser.add_argument("objective", nargs="*", help="Goal or task description")
+    parser.add_argument("--level", type=int, choices=[0, 1, 2, 3], default=None,
+                        help="0: Dry-Run\n1: Supervised (Default)\n2: Unrestricted (Danger)\n3: Troubleshooter")
+    parser.add_argument("--init", action="store_true", help="Initialize ~/.hey-rules.json")
+    parser.add_argument("--clear", action="store_true", help="Clear conversational memory history")
+    parser.add_argument("--check-cache", type=str, help="Check local cache for instant fix")
+    
+    args = parser.parse_args()
+    
+    gov = GovernanceEngine()
+    history_mgr = HistoryManager()
+    
+    if args.clear:
+        history_mgr.clear()
+        console.print("[dim]Conversational history wiped clean.[/dim]")
+        sys.exit(0)
+    
+    active_level = args.level
+    if active_level is None:
+        active_level = gov.rules.get("config", {}).get("default_level", 1)
+        
+    model_name = gov.rules.get("config", {}).get("model", "gpt-oss:20b-cloud")
+    
+    if args.init:
+        if gov.init_rules():
+            console.print(f"Initialized security rules at {gov.rules_path}")
+        else:
+            console.print(f"Rules already exist at {gov.rules_path}")
+        sys.exit(0)
+        
+    if args.check_cache:
+        sys.exit(0)
+
+    piped_data = ""
+    if not sys.stdin.isatty():
+        try:
+            piped_data = sys.stdin.read()
+            sys.stdin = open('/dev/tty')
+        except Exception:
+            pass
+
+    objective = " ".join(args.objective).strip()
+    if not objective and not piped_data:
+        parser.print_help()
+        sys.exit(1)
+        
+    # Build complete user message for saving later
+    user_prompt = objective
+    if piped_data:
+        user_prompt += f"\n\n[Piped Data]:\n{piped_data}"
+        
+    console.print("[bold yellow]●[/bold yellow] Thinking...")
+    past_messages = history_mgr.load()
+    response = generate_command(objective, context=piped_data, model_name=model_name, history=past_messages)
+    
+    # Save the user query to history IMMEDIATELY
+    history_mgr.append("user", user_prompt)
+    
+    runner = CommandRunner(governance=gov, level=active_level, model_name=model_name, history_mgr=history_mgr)
+    runner.execute_flow(response, objective)
+
+if __name__ == "__main__":
+    main()

hey_cli_python-1.0.0/hey_cli/governance.py

@@ -0,0 +1,85 @@
+import json
+import os
+from pathlib import Path
+
+DEFAULT_RULES = {
+    "config": {
+        "default_level": 1,
+        "model": "gpt-oss:20b-cloud"
+    },
+    "never": [
+        "rm -rf /", 
+        "mkfs", 
+        "dropdb",
+        "chmod -R 777"
+    ],
+    "require_confirmation": [
+        "docker run", 
+        "docker build", 
+        "npm publish", 
+        "git push",
+        "kubectl delete"
+    ],
+    "allowed": [
+        "ls", "cat", "pwd", "grep", "find", "echo", "tail"
+    ],
+    "high_risk_keywords": [
+        "reset", "delete", "drop", "truncate", "prune", "rm", "-exec", ">"
+    ]
+}
+
+class Action(str):
+    BLOCKED = "blocked"
+    EXPLICIT_CONFIRM = "explicit_confirm"
+    YN_CONFIRM = "yn_confirm"
+    PROCEED = "proceed"
+
+class GovernanceEngine:
+    def __init__(self, rules_path: str = "~/.hey-rules.json"):
+        self.rules_path = Path(os.path.expanduser(rules_path))
+        self.rules = self._load()
+
+    def _load(self):
+        if not self.rules_path.exists():
+            return DEFAULT_RULES
+        with open(self.rules_path, "r") as f:
+            return json.load(f)
+
+    def init_rules(self):
+        if not self.rules_path.exists():
+            with open(self.rules_path, "w") as f:
+                json.dump(DEFAULT_RULES, f, indent=2)
+            return True
+        return False
+
+    def evaluate(self, command: str) -> tuple[str, str]:
+        """
+        Evaluate a command against the security matrix.
+        Returns a tuple: (Action, Reason/Keyword)
+        """
+        if not command:
+             return Action.BLOCKED, "Empty command"
+             
+        # 1. Never List
+        for never_cmd in self.rules.get("never", []):
+            if never_cmd in command:
+                 return Action.BLOCKED, f"Matches never list: {never_cmd}"
+                 
+        # 2. High Risk
+        for hr_kw in self.rules.get("high_risk_keywords", []):
+            if hr_kw in command:
+                 return Action.EXPLICIT_CONFIRM, hr_kw
+                 
+        # 3. Require Confirmation
+        for req_cmd in self.rules.get("require_confirmation", []):
+            if req_cmd in command:
+                 return Action.YN_CONFIRM, req_cmd
+                 
+        # 4. Allowed List
+        for allow_cmd in self.rules.get("allowed", []):
+            # Check if it's the start of the command (e.g. 'ls -la')
+            if command.strip().startswith(allow_cmd):
+                 return Action.PROCEED, "Allowed command"
+        
+        # Default behavior: if not explicitly allowed, still require y/N confirm for safety
+        return Action.YN_CONFIRM, "Command not explicitly in allowed list"

hey_cli_python-1.0.0/hey_cli/history.py

@@ -0,0 +1,32 @@
+import json
+import os
+from pathlib import Path
+
+class HistoryManager:
+    def __init__(self, path: str = "~/.hey-history.json", max_messages: int = 15):
+        self.path = Path(os.path.expanduser(path))
+        self.max_messages = max_messages
+
+    def load(self) -> list:
+        if not self.path.exists():
+            return []
+        try:
+            with open(self.path, "r") as f:
+                return json.load(f)
+        except Exception:
+            return []
+
+    def append(self, role: str, content: str):
+        history = self.load()
+        history.append({"role": role, "content": content})
+        
+        # Enforce rolling window
+        if len(history) > self.max_messages:
+            history = history[-self.max_messages:]
+            
+        with open(self.path, "w") as f:
+            json.dump(history, f, indent=2)
+
+    def clear(self):
+        if self.path.exists():
+            self.path.unlink()

hey_cli_python-1.0.0/hey_cli/llm.py

@@ -0,0 +1,130 @@
+import json
+import os
+import platform
+import ollama
+from .models import CommandResponse, TroubleshootResponse
+
+DEFAULT_MODEL = "gpt-oss:20b-cloud"
+
+SYSTEM_PROMPT = r"""You are hey-cli, an autonomous, minimalist CLI companion and terminal expert. 
+Your primary goal is to turn natural language objectives and error logs into actionable shell commands.
+Your user intends to execute the command you provide.
+Do NOT output markdown blocks or conversational text outside the required JSON schema.
+Only output valid JSON matching the requested schema exactly.
+You MUST provide "command", "explanation", and "needs_context" fields in your JSON output.
+WARNING: Ensure any quotes inside your command (e.g. echo 'text') are single quotes, or properly escaped double quotes, to maintain valid JSON string structure.
+CRITICAL PARSING RULE: If the user provides a specific filename, directory name, string, or port, you MUST preserve it EXACTLY as written. Do not autocorrect spelling, abbreviate, or drop extensions (e.g., if asked to make 'temporarily', do not output 'temporay').
+
+IMPORTANT AGENTIC INSTRUCTION:
+If the user asks ANY question about their system state, files, or environment (e.g., "is docker running?", "what is my IP?", "explain this folder"), you MUST set `needs_context = true` and target a bash command to silently gather the data.
+ONLY set `needs_context = false` when you are providing the FINAL answer. 
+If your final answer is an explanation or simply answering a question, leave the `command` field empty `""` and put a high-quality Markdown response in the `explanation` field. Do NOT write bash `echo` or `printf` statements.
+If your final answer requires an action to be ran (e.g., "start docker", "delete the folder"), put the executable bash string in `command`.
+CRITICAL JSON REQUIREMENT: If your bash command contains any backslashes (e.g. for regex like `\.` or escaping spaces), you MUST double-escape them (`\\\\.`) so the output remains valid JSON!
+"""
+
+from .skills import get_compiled_skills
+
+def get_system_context() -> str:
+    os_name = platform.system()
+    os_release = platform.release()
+    arch = platform.machine()
+    shell = os.environ.get("SHELL", "unknown")
+    
+    skills_block = f"\n\n{get_compiled_skills()}"
+         
+    return f"Operating System: {os_name} {os_release} ({arch})\nCurrent Shell: {shell}{skills_block}"
+
+TROUBLESHOOT_PROMPT = r"""You are acting as an iterative troubleshooter. 
+You will be provided with an objective, the previous commands attempted, and the stdout/stderr.
+Determine the next command to run to resolve the issue, OR if the issue is resolved, indicate it.
+Keep your explanation brief and chill. If a file or tests do not exist, do not try to aggressively brute-force create configurations. Just explain the situation and set is_resolved=True to gracefully stop.
+"""
+
+def generate_command(prompt: str, context: str = "", model_name: str = DEFAULT_MODEL, history: list = None) -> CommandResponse:
+    content = prompt
+    if context:
+        content = f"Context (e.g. error logs or piped data):\n{context}\n\nObjective:\n{prompt}"
+        
+    try:
+        sys_context = f"--- ENVIRONMENT ---\n{get_system_context()}\n-------------------\n"
+        msgs = [{"role": "system", "content": SYSTEM_PROMPT + "\n\n" + sys_context}]
+        if history:
+            msgs.extend(history)
+        msgs.append({"role": "user", "content": content})
+        
+        response = ollama.chat(
+            model=model_name,
+            messages=msgs,
+            format="json",
+            options={"temperature": 0.0}
+        )
+        
+        content = response["message"]["content"]
+        # In case ollama returns markdown format code block for JSON
+        if content.startswith("```json"):
+            content = content[7:-3].strip()
+        elif content.startswith("```"):
+            content = content[3:-3].strip()
+            
+        data = json.loads(content)
+        return CommandResponse(**data)
+    except Exception as e:
+        raw_val = content if 'content' in locals() else "None"
+        
+        # Check if the error was caused by a safety refusal schema validation failure
+        if "refusal" in raw_val.lower() or "sorry" in raw_val.lower():
+            return CommandResponse(
+                command="",
+                explanation=f"LLM Safety Trigger: The model refused to generate this command.\n\nRaw output: {raw_val.strip()}",
+                needs_context=False
+            )
+            
+        # Fallback empty block on failure
+        return CommandResponse(
+            command="", 
+            explanation=f"Error generating command from LLM: {str(e)}\nRaw Output:\n{raw_val}"
+        )
+
+def generate_troubleshoot_step(objective: str, history: list, model_name: str = DEFAULT_MODEL) -> TroubleshootResponse:
+    history_text = "\n".join([
+        f"Cmd: {h['cmd']}\nExit: {h['exit_code']}\nOut/Err:\n{h['output']}"
+        for h in history
+    ])
+    
+    content = f"Objective:\n{objective}\n\nHistory of execution:\n{history_text}\n\nAnalyze the specific error and provide the NEXT logical command to test or fix. Re-read logs carefully."
+    
+    try:
+        sys_context = f"--- ENVIRONMENT ---\n{get_system_context()}\n-------------------\n"
+        response = ollama.chat(
+            model=model_name,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT + "\n" + TROUBLESHOOT_PROMPT + "\n\n" + sys_context},
+                {"role": "user", "content": content}
+            ],
+            format="json",
+            options={"temperature": 0.0}
+        )
+        
+        content = response["message"]["content"].strip()
+        if not content:
+            return TroubleshootResponse(
+                command=None,
+                explanation="LLM returned empty JSON object.",
+                is_resolved=False
+            )
+            
+        if content.startswith("```json"):
+            content = content[7:-3].strip()
+        elif content.startswith("```"):
+            content = content[3:-3].strip()
+            
+        data = json.loads(content)
+        return TroubleshootResponse(**data)
+    except Exception as e:
+        raw_val = content if 'content' in locals() else "None"
+        return TroubleshootResponse(
+            command=None,
+            explanation=f"Error analyzing execution: {str(e)}\nRaw Output:\n{raw_val}",
+            is_resolved=False
+        )

hey_cli_python-1.0.0/hey_cli/models.py

@@ -0,0 +1,12 @@
+from pydantic import BaseModel, ConfigDict
+from typing import Optional
+
+class CommandResponse(BaseModel):
+    command: str
+    explanation: str = ""
+    needs_context: bool = False
+
+class TroubleshootResponse(BaseModel):
+    command: Optional[str] = None
+    explanation: str = ""
+    is_resolved: bool = False

hey_cli_python-1.0.0/hey_cli/runner.py

@@ -0,0 +1,195 @@
+import subprocess
+import sys
+from typing import Optional
+
+from .governance import GovernanceEngine, Action
+from .llm import CommandResponse, TroubleshootResponse, generate_troubleshoot_step, generate_command
+from rich.console import Console
+from rich.markdown import Markdown
+
+class CommandRunner:
+    def __init__(self, governance: GovernanceEngine, level: int = 1, model_name: str = "gpt-oss:20b-cloud", history_mgr=None):
+        self.gov = governance
+        self.level = level
+        self.model_name = model_name
+        self.history_mgr = history_mgr
+        self.console = Console()
+
+    def run_command(self, cmd: str) -> tuple[int, str]:
+        """Executes a command and returns exit code and combined output."""
+        try:
+            result = subprocess.run(
+                cmd, 
+                shell=True, 
+                stdout=subprocess.PIPE, 
+                stderr=subprocess.STDOUT, 
+                text=True
+            )
+            return result.returncode, result.stdout
+        except Exception as e:
+            return -1, str(e)
+
+    def _prompt_user(self, prompt: str) -> bool:
+        try:
+            sys.stdout.write(f"{prompt} ")
+            sys.stdout.flush()
+            ans = sys.stdin.readline().strip().lower()
+            return ans in ('y', 'yes')
+        except KeyboardInterrupt:
+            print("\nAborted.")
+            return False
+
+    def _prompt_exact(self, prompt: str, expected_match: str) -> bool:
+        try:
+            sys.stdout.write(f"\033[93m{prompt}\033[0m ")
+            sys.stdout.flush()
+            ans = sys.stdin.readline().strip()
+            return ans == expected_match
+        except KeyboardInterrupt:
+            print("\nAborted.")
+            return False
+
+    def _check_governance(self, cmd: str) -> bool:
+        """Run command through governance and output proper CLI prompts."""
+        action, reason = self.gov.evaluate(cmd)
+        
+        if action == Action.BLOCKED:
+            self.console.print(f"[bold red]● [BLOCKED][/bold red] {reason}")
+            return False
+            
+        elif action == Action.EXPLICIT_CONFIRM:
+            self.console.print(f"[bold yellow]● [WARNING] High risk command detected![/bold yellow]")
+            if not self._prompt_exact(f"Type '{reason}' to confirm execution:", reason):
+                self.console.print("[dim]Confirmation failed. Aborted.[/dim]")
+                return False
+            return True
+            
+        elif action == Action.YN_CONFIRM:
+            if self.level >= 2:
+                if self.level == 2:
+                    self.console.print(f"[dim]● Auto-approving (Level {self.level}): {reason}[/dim]")
+                return True
+            if not self._prompt_user("Execute this command? [y/N]:"):
+                 self.console.print("[dim]Aborted.[/dim]")
+                 return False
+            return True
+            
+        elif action == Action.PROCEED:
+            # Completely silent for PROCEED
+            return True
+            
+        return False
+
+    def execute_flow(self, initial_response: CommandResponse, original_objective: str):
+        current_response = initial_response
+        current_context = ""
+        
+        # Micro-Agent Context Gathering Loop (Active for Level 1, 2)
+        if self.level in (1, 2):
+            iteration = 0
+            executed_commands = set()
+            while current_response.needs_context and iteration < 5:
+                cmd_stripped = current_response.command.strip()
+                if cmd_stripped in executed_commands:
+                    self.console.print(f"[bold red]●[/bold red] Loop detected on: [bold]{cmd_stripped}[/bold]. Forcing final answer.")
+                    current_context += f"\n\n[System]: You already ran '{cmd_stripped}'. Stop gathering context and provide the final answer with needs_context=false."
+                    current_response = generate_command(original_objective, context=current_context, model_name=self.model_name)
+                    iteration += 1
+                    continue
+                    
+                executed_commands.add(cmd_stripped)
+                self.console.print(f"[bold cyan]●[/bold cyan] [bold]{current_response.command}[/bold]")
+                if not self._check_governance(current_response.command):
+                    self.console.print(f"[bold red]●[/bold red] Context gathering blocked by governance. Reverting to manual answer.")
+                    break
+                    
+                code, out = self.run_command(current_response.command)
+                clean_out = out.strip()
+                if len(clean_out) > 5000:
+                    clean_out = clean_out[:5000] + "\n...[Output Truncated]"
+                    
+                current_context += f"\n\n[Output of {current_response.command}]:\n{clean_out}"
+                
+                self.console.print("[bold dim]● Analyzing output...[/bold dim]")
+                current_response = generate_command(original_objective, context=current_context, model_name=self.model_name)
+                iteration += 1
+
+        cmd = current_response.command.strip() if current_response.command else ""
+        
+        # Save final outcome to history
+        if self.history_mgr:
+            if not cmd or cmd.startswith("echo ") or cmd.startswith("printf "):
+                self.history_mgr.append("assistant", current_response.explanation)
+            else:
+                self.history_mgr.append("assistant", current_response.model_dump_json())
+
+        # Level 0 = Dry Run
+        if self.level == 0:
+            self.console.print("[dim]● Dry run (Level 0). Exiting without execution.[/dim]")
+            return
+
+        if not cmd:
+            self.console.print("\n[bold green]● TASK RESULT:[/bold green]")
+            self.console.print(Markdown(current_response.explanation))
+            return
+
+        # Action mode (command generated)
+        if self.level != 3:
+            if current_response.explanation:
+                self.console.print("\n[bold green]● TASK RESULT:[/bold green]")
+                self.console.print(Markdown(current_response.explanation))
+            self.console.print(f"Command: [bold yellow]{cmd}[/bold yellow]\n")
+
+        # Levels 1 and 2
+        if self.level in (1, 2):
+            if self._check_governance(cmd):
+                self.console.print(f"[bold green]● Running:[/bold green] {cmd}")
+                code, out = self.run_command(cmd)
+                if out.strip():
+                    print(out.strip())
+                sys.exit(code)
+            else:
+                sys.exit(1)
+
+        # Level 3 = Iterative Troubleshooter
+        if self.level == 3:
+            history = []
+            current_cmd = cmd
+            
+            print("\033[96m[hey]\033[0m Iterative Troubleshooter Started:")
+            
+            tr = None
+            for iteration in range(1, 6): # Max 5 iterations
+                if not self._check_governance(current_cmd):
+                    print("  \033[91m-> Blocked by governance.\033[0m")
+                    break
+                    
+                print(f"  \033[93mStep {iteration}\033[0m: \033[1m{current_cmd}\033[0m", end=" ")
+                code, out = self.run_command(current_cmd)
+                
+                clean_out = out.strip()
+                if clean_out:
+                    print(f"\n  \033[90m> {clean_out[:200]}{'...' if len(clean_out) > 200 else ''}\033[0m")
+                else:
+                    print(f" \033[92m(done)\033[0m")
+                
+                history.append({
+                    "cmd": current_cmd,
+                    "exit_code": code,
+                    "output": clean_out
+                })
+                
+                tr = generate_troubleshoot_step(original_objective, history, model_name=self.model_name)
+                if tr.is_resolved:
+                    print(f"\n\033[92m[hey] {tr.explanation}\033[0m")
+                    sys.exit(0)
+                    
+                current_cmd = tr.command
+                if not current_cmd:
+                    print(f"\n\033[92m[hey] {tr.explanation}\033[0m")
+                    sys.exit(0)
+
+            if tr:
+                print(f"\n\033[93m[hey] Pausing after 5 steps. Final assessment:\033[0m")
+                print(f"\033[92m{tr.explanation}\033[0m")
+            sys.exit(0)

hey_cli_python-1.0.0/hey_cli/skills.py

@@ -0,0 +1,115 @@
+"""
+Modular skills registry for hey-cli.
+Dynamically loads OS-specific and universal shell heuristics from markdown files
+in the skills/ directory and injects them into the LLM system prompt.
+
+Add new skills by creating/editing .md files in hey_cli/skills/:
+  - shell.md        → Universal rules (applied on ALL platforms)
+  - darwin.md       → macOS specific
+  - ubuntu_debian.md → Ubuntu/Debian specific
+  - fedora_rhel.md  → Fedora/RHEL/CentOS specific
+  - arch_linux.md   → Arch/Manjaro specific
+  - windows_powershell.md → Windows PowerShell
+  - windows_wsl.md  → WSL specific
+  - alpine.md       → Alpine Linux specific
+  - freebsd.md      → FreeBSD specific
+  - opensuse.md     → openSUSE/SLES specific
+  - chromeos.md     → ChromeOS Crostini specific
+"""
+
+import platform
+from pathlib import Path
+
+# Map platform.system() output to skill file basenames
+OS_SKILL_MAP = {
+    "Darwin": ["darwin"],
+    "Linux": [],       # Resolved dynamically below based on distro detection
+    "Windows": ["windows_powershell"],
+    "FreeBSD": ["freebsd"],
+}
+
+# Linux distro detection → skill file mapping
+LINUX_DISTRO_MAP = {
+    "ubuntu": "ubuntu_debian",
+    "debian": "ubuntu_debian",
+    "pop": "ubuntu_debian",       # Pop!_OS
+    "mint": "ubuntu_debian",      # Linux Mint
+    "fedora": "fedora_rhel",
+    "rhel": "fedora_rhel",
+    "centos": "fedora_rhel",
+    "rocky": "fedora_rhel",       # Rocky Linux
+    "alma": "fedora_rhel",        # AlmaLinux
+    "arch": "arch_linux",
+    "manjaro": "arch_linux",
+    "endeavouros": "arch_linux",
+    "alpine": "alpine",
+    "opensuse": "opensuse",
+    "sles": "opensuse",
+    "suse": "opensuse",
+    "chromeos": "chromeos",
+}
+
+SKILLS_DIR = Path(__file__).parent / "skills"
+
+
+def _detect_linux_distro() -> str:
+    """Detect Linux distribution from /etc/os-release."""
+    try:
+        with open("/etc/os-release", "r") as f:
+            content = f.read().lower()
+            for key, skill_file in LINUX_DISTRO_MAP.items():
+                if key in content:
+                    return skill_file
+    except FileNotFoundError:
+        pass
+    
+    # Fallback: check for WSL
+    try:
+        with open("/proc/version", "r") as f:
+            if "microsoft" in f.read().lower():
+                return "windows_wsl"
+    except FileNotFoundError:
+        pass
+    
+    # Default to ubuntu_debian as most common
+    return "ubuntu_debian"
+
+
+def _load_skill_file(filename: str) -> str:
+    """Load a skill markdown file and return its content as plain text."""
+    filepath = SKILLS_DIR / f"{filename}.md"
+    if filepath.exists():
+        return filepath.read_text(encoding="utf-8").strip()
+    return ""
+
+
+def get_compiled_skills() -> str:
+    """
+    Compiles a formatted string of applicable operational skills
+    based on host OS and distro. Always includes shell.md (universal).
+    """
+    os_name = platform.system()
+    
+    # Always load universal shell skills
+    sections = []
+    shell_content = _load_skill_file("shell")
+    if shell_content:
+        sections.append(shell_content)
+    
+    # Load OS-specific skills
+    os_files = OS_SKILL_MAP.get(os_name, [])
+    
+    # For Linux, detect the specific distro
+    if os_name == "Linux":
+        distro_file = _detect_linux_distro()
+        os_files = [distro_file]
+    
+    for skill_file in os_files:
+        content = _load_skill_file(skill_file)
+        if content:
+            sections.append(content)
+    
+    if not sections:
+        return ""
+    
+    return "### OPERATIONAL SKILLS & HEURISTICS\n\n" + "\n\n---\n\n".join(sections)

hey_cli_python-1.0.0/hey_cli_python.egg-info/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: hey-cli-python
+Version: 1.0.0
+Summary: A secure, zero-bloat CLI companion that turns natural language and error logs into executable commands.
+Author: Mohit S.
+Project-URL: Homepage, https://github.com/sinsniwal/hey-cli
+Project-URL: Repository, https://github.com/sinsniwal/hey-cli
+Project-URL: Issues, https://github.com/sinsniwal/hey-cli/issues
+Keywords: cli,llm,bash,terminal,ollama,sysadmin
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: ollama>=0.1.0
+Requires-Dist: rich>=13.0.0
+Dynamic: license-file
+
+<div align="center">
+  <h1>hey-cli 🤖</h1>
+  <p><strong>A zero-bloat, privacy-first, locally-hosted CLI agent powered by Ollama.</strong></p>
+
+  <img src="https://img.shields.io/badge/Python-3.9+-blue.svg" alt="Python Version" />
+  <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License" />
+  <img src="https://img.shields.io/badge/Ollama-Local-orange.svg" alt="Ollama Local" />
+</div>
+
+<br>
+
+`hey` isn't just an LLM wrapper. It's a context-aware system agent designed to bridge the gap between human language and POSIX shell utilities natively on your host machine.
+
+> Ask it to parse your error logs, debug Docker, clear DNS caches, or execute complex file maneuvers—all while executing safely behind a dynamic zero-trust governance matrix.
+
+## 🚀 Why `hey-cli` over Copilot/ChatGPT?
+1. **Total Privacy**: Your code and system logs never leave your physical CPU. All context gathering and reasoning is done locally via [Ollama](https://ollama.com).
+2. **True Cross-Platform Skills**: Under the hood, `hey-cli`'s "Skills Engine" detects if you're on macOS (BSD), Ubuntu (GNU), Windows (PowerShell), or Arch Linux, and actively refuses to generate incompatible flags like `xargs -d` on Mac.
+3. **Agentic Execution**: Ask "is docker running?" and `hey` will silently execute `docker info` in the background, read the stdout, analyze it, and return a plain English answer.
+4. **Security Governance**: Built-in AST-level parsing. Safe commands (like `git status`) auto-run. Destructive commands (`rm -rf`, `-exec delete`) require explicit typed confirmation.
+
+## 📦 Installation
+
+**Prerequisite:** You must have [Python 3.9+](https://www.python.org/downloads/) installed.
+
+### macOS & Linux
+Paste this snippet into your terminal to auto-install `pipx`, `ollama`, pull the required language model, and build `hey-cli` natively.
+```bash
+curl -sL https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.sh | bash
+```
+
+### Windows (PowerShell)
+Paste this into your PowerShell terminal:
+```powershell
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.ps1" -OutFile "$env:TEMP\hey_install.ps1"; & "$env:TEMP\hey_install.ps1"
+```
+
+## 🛠️ Usage
+
+Simply type `hey` followed by your objective.
+
+**Context-Gathering (Zero-Trust)**
+```bash
+hey is my docker hub running?
+```
+*`hey` will silently run `systemctl is-active docker` or `docker info`, see that it failed to connect to the socket, and explain the situation.*
+
+**Execution (Governance Protected)**
+```bash
+hey forcefully delete all .pyc files
+```
+*`hey` parses the generated `find . -name "*.pyc" -exec rm -f {} +` command, detects `rm` and `-exec` triggers, and pauses execution until you explicitly type `rm` to authorize.*
+
+**Debugging Logs**
+```bash
+npm run build 2>&1 | hey what is causing this webpack error?
+```
+
+## 🛡️ Governance Matrix
+Safety is a first-class citizen. `hey-cli` maintains a local governance database (`~/.hey-rules.json`):
+- **Never List**: Things like `rm -rf /` and `mkfs` are permanently blocked at the compiler level.
+- **Explicit Confirm**: High-risk ops (`truncate`, `drop`, `rm`) require typing exact keyword verification.
+- **Y/N Confirm**: Moderate risk ops requiring a quick `y`.
+- **Allowed List**: Safe diagnostics like `cat`, `ls`, `grep` auto-run natively.
+
+## 🤝 Adding OS Skills
+Is `hey` generating incorrect shell semantics for your niche operating system? 
+
+You can make it permanently smarter without touching code! Simply open `hey_cli/skills/` and create a markdown file for your OS containing explicit English instructions (e.g. "Do not use apt on Alpine, use apk add"). The engine dynamically parses `.md` rulesites at runtime. Pull requests are heavily welcomed!

hey_cli_python-1.0.0/hey_cli_python.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+hey_cli/__init__.py
+hey_cli/cli.py
+hey_cli/governance.py
+hey_cli/history.py
+hey_cli/llm.py
+hey_cli/models.py
+hey_cli/runner.py
+hey_cli/skills.py
+hey_cli_python.egg-info/PKG-INFO
+hey_cli_python.egg-info/SOURCES.txt
+hey_cli_python.egg-info/dependency_links.txt
+hey_cli_python.egg-info/entry_points.txt
+hey_cli_python.egg-info/requires.txt
+hey_cli_python.egg-info/top_level.txt
+tests/test_cli.py

hey_cli_python-1.0.0/hey_cli_python.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hey_cli_python-1.0.0/hey_cli_python.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hey = hey_cli.cli:main

hey_cli_python-1.0.0/hey_cli_python.egg-info/requires.txt

@@ -0,0 +1,3 @@
+pydantic>=2.0.0
+ollama>=0.1.0
+rich>=13.0.0

hey_cli_python-1.0.0/hey_cli_python.egg-info/top_level.txt

@@ -0,0 +1 @@
+hey_cli

hey_cli_python-1.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hey-cli-python"
+version = "1.0.0"
+description = "A secure, zero-bloat CLI companion that turns natural language and error logs into executable commands."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+  {name = "Mohit S."}
+]
+keywords = ["cli", "llm", "bash", "terminal", "ollama", "sysadmin"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "pydantic>=2.0.0",
+    "ollama>=0.1.0",
+    "rich>=13.0.0"
+]
+urls.Homepage = "https://github.com/sinsniwal/hey-cli"
+urls.Repository = "https://github.com/sinsniwal/hey-cli"
+urls.Issues = "https://github.com/sinsniwal/hey-cli/issues"
+
+[project.scripts]
+hey = "hey_cli.cli:main"
+
+[tool.setuptools]
+packages = ["hey_cli"]

hey_cli_python-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hey_cli_python-1.0.0/tests/test_cli.py

@@ -0,0 +1,42 @@
+import pytest
+import os
+import platform
+from hey_cli.llm import generate_command
+from hey_cli.governance import GovernanceEngine, Action
+
+def test_governance_engine_safe_command():
+    gov = GovernanceEngine()
+    # Explicitly test an allowed command
+    action, keyword = gov.evaluate("ls -la")
+    assert action == Action.PROCEED
+
+def test_governance_engine_unsafe_command():
+    gov = GovernanceEngine()
+    # Explicitly test a blocked command
+    action, keyword = gov.evaluate("rm -rf /")
+    assert action == Action.BLOCKED
+    
+def test_governance_engine_explicit_confirm():
+    gov = GovernanceEngine()
+    # Explicit test for dangerous keywords
+    action, keyword = gov.evaluate("find . -name temp -exec rm -f {} +")
+    assert action == Action.EXPLICIT_CONFIRM
+    assert keyword in ["-exec", "rm"]
+
+def test_system_prompt_structure():
+    from hey_cli.llm import SYSTEM_PROMPT
+    assert "CRITICAL PARSING RULE:" in SYSTEM_PROMPT
+    assert "needs_context" in SYSTEM_PROMPT
+
+def test_skill_compiler():
+    from hey_cli.skills import get_compiled_skills
+    skills = get_compiled_skills()
+    assert isinstance(skills, str)
+    # The universal shell sheet is always loaded
+    assert "Universal Shell Skills" in skills
+    # The OS-specific sheet should be loaded dynamically
+    os_name = platform.system()
+    if os_name == "Windows":
+        assert "Windows" in skills
+    elif os_name == "Darwin":
+        assert "macOS" in skills