hey-cli-python 1.0.3__tar.gz → 1.0.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. hey_cli_python-1.0.5/PKG-INFO +203 -0
  2. hey_cli_python-1.0.5/README.md +175 -0
  3. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/hey_cli/cli.py +4 -1
  4. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/hey_cli/llm.py +4 -0
  5. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/hey_cli/runner.py +3 -1
  6. hey_cli_python-1.0.5/hey_cli_python.egg-info/PKG-INFO +203 -0
  7. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/pyproject.toml +1 -1
  8. hey_cli_python-1.0.3/PKG-INFO +0 -97
  9. hey_cli_python-1.0.3/README.md +0 -69
  10. hey_cli_python-1.0.3/hey_cli_python.egg-info/PKG-INFO +0 -97
  11. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/LICENSE +0 -0
  12. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/hey_cli/__init__.py +0 -0
  13. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/hey_cli/governance.py +0 -0
  14. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/hey_cli/history.py +0 -0
  15. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/hey_cli/models.py +0 -0
  16. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/hey_cli/skills.py +0 -0
  17. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/hey_cli_python.egg-info/SOURCES.txt +0 -0
  18. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/hey_cli_python.egg-info/dependency_links.txt +0 -0
  19. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/hey_cli_python.egg-info/entry_points.txt +0 -0
  20. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/hey_cli_python.egg-info/requires.txt +0 -0
  21. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/hey_cli_python.egg-info/top_level.txt +0 -0
  22. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/setup.cfg +0 -0
  23. {hey_cli_python-1.0.3 → hey_cli_python-1.0.5}/tests/test_cli.py +0 -0
@@ -0,0 +1,203 @@
1
+ Metadata-Version: 2.4
2
+ Name: hey-cli-python
3
+ Version: 1.0.5
4
+ Summary: A secure, zero-bloat CLI companion that turns natural language and error logs into executable commands.
5
+ Author: Mohit Singh Sinsniwal
6
+ Project-URL: Homepage, https://github.com/sinsniwal/hey-cli
7
+ Project-URL: Repository, https://github.com/sinsniwal/hey-cli
8
+ Project-URL: Issues, https://github.com/sinsniwal/hey-cli/issues
9
+ Keywords: cli,llm,bash,terminal,ollama,sysadmin
10
+ Classifier: Development Status :: 5 - Production/Stable
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Operating System :: MacOS
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Classifier: Operating System :: Microsoft :: Windows
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Requires-Python: >=3.9
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Requires-Dist: rich>=13.0.0
27
+ Dynamic: license-file
28
+
29
+ <div align="center">
30
+ <h1>hey-cli</h1>
31
+ <p><strong>Your terminal buddy that turns plain English into shell scripts — and runs them for you.</strong></p>
32
+
33
+ <a href="https://pypi.org/project/hey-cli-python/"><img src="https://img.shields.io/pypi/v/hey-cli-python?label=PyPI&color=blue" alt="PyPI" /></a>
34
+ <img src="https://img.shields.io/pypi/pyversions/hey-cli-python?color=blue" alt="Python" />
35
+ <a href="https://github.com/sinsniwal/hey-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License" /></a>
36
+ <a href="https://github.com/sinsniwal/hey-cli/releases/latest"><img src="https://img.shields.io/github/v/release/sinsniwal/hey-cli?label=Release&color=orange" alt="Release" /></a>
37
+ </div>
38
+
39
+ <br>
40
+
41
+ `hey` is a terminal-native AI assistant that translates plain English into executable shell commands using a locally-hosted LLM via [Ollama](https://ollama.com). Your data never leaves your machine.
42
+
43
+ ```
44
+ $ hey find all python files modified in the last 24 hours
45
+ ● Thinking...
46
+
47
+ ▶ find . -name "*.py" -mtime -1 -type f
48
+
49
+ Run this command? [Y/n]:
50
+ ```
51
+
52
+ ---
53
+
54
+ ## Features
55
+
56
+ - **100% Local & Private** — All reasoning happens on your machine via Ollama. No API keys, no cloud, no telemetry.
57
+ - **Cross-Platform Intelligence** — Detects your OS (macOS/Linux/Windows) and generates the correct flags. Won't suggest `xargs -d` on BSD or `apt` on Arch.
58
+ - **Agentic Context Gathering** — Ask "is Docker running?" and `hey` silently runs diagnostics, reads the output, and answers in plain English.
59
+ - **Security Governance** — Dangerous commands (`rm -rf`, `mkfs`, `DROP TABLE`) are intercepted and require explicit confirmation before execution.
60
+ - **Pipe-Friendly** — Pipe error logs directly: `npm run build 2>&1 | hey what is causing this error?`
61
+ - **Conversational Memory** — Remembers your recent interactions for follow-up questions.
62
+
63
+ ---
64
+
65
+ ## Installation
66
+
67
+ `hey` requires [Ollama](https://ollama.com) running locally. Install it first, then choose your platform:
68
+
69
+ ### macOS (Homebrew)
70
+
71
+ ```bash
72
+ brew tap sinsniwal/hey-cli
73
+ brew install hey-cli
74
+ ```
75
+
76
+ ### macOS & Linux (curl)
77
+
78
+ ```bash
79
+ curl -sL https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.sh | bash
80
+ ```
81
+
82
+ ### Windows (Scoop)
83
+
84
+ ```powershell
85
+ scoop install https://raw.githubusercontent.com/sinsniwal/hey-cli/main/scoop/hey-cli.json
86
+ ```
87
+
88
+ ### Windows (PowerShell Installer)
89
+
90
+ ```powershell
91
+ Invoke-WebRequest -Uri "https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.ps1" -OutFile "$env:TEMP\hey_install.ps1"; & "$env:TEMP\hey_install.ps1"
92
+ ```
93
+
94
+ ### Windows (Standalone Binary)
95
+
96
+ Download `hey.exe` from the [latest release](https://github.com/sinsniwal/hey-cli/releases/latest). No Python required.
97
+
98
+ ### pip / pipx
99
+
100
+ ```bash
101
+ pipx install hey-cli-python
102
+ ```
103
+
104
+ > **Note:** After installation, pull the default model: `ollama pull gpt-oss:20b-cloud`
105
+
106
+ ---
107
+
108
+ ## Usage
109
+
110
+ ```bash
111
+ hey <your objective in plain English>
112
+ ```
113
+
114
+ ### Examples
115
+
116
+ | Command | What happens |
117
+ |---------|-------------|
118
+ | `hey list all running docker containers` | Generates and runs `docker ps` |
119
+ | `hey is port 8080 in use?` | Silently runs `lsof -i :8080`, reads output, answers in English |
120
+ | `hey forcefully delete all .pyc files` | Generates `find . -name "*.pyc" -delete`, pauses for confirmation |
121
+ | `hey compress this folder into a tar.gz` | Generates the correct `tar` command for your OS |
122
+ | `npm run build 2>&1 \| hey what broke?` | Reads piped stderr and explains the error |
123
+ | `hey --clear` | Wipes conversational memory |
124
+
125
+ ### Execution Levels
126
+
127
+ | Level | Flag | Behavior |
128
+ |-------|------|----------|
129
+ | 0 | `--level 0` | Dry-run — shows the command but never executes |
130
+ | 1 | *(default)* | Supervised — safe commands auto-run, risky ones ask for confirmation |
131
+ | 2 | `--level 2` | Unrestricted — executes everything without confirmation |
132
+ | 3 | `--level 3` | Troubleshooter — iteratively debugs until the objective is resolved |
133
+
134
+ ---
135
+
136
+ ## Security
137
+
138
+ Safety is enforced at runtime via a local governance engine (`~/.hey-rules.json`):
139
+
140
+ - **Blocked** — `rm -rf /`, `mkfs`, `:(){ :|:& };:` are permanently rejected.
141
+ - **Explicit Confirm** — High-risk operations (`rm`, `truncate`, `DROP`) require typing a keyword to authorize.
142
+ - **Y/N Confirm** — Moderate-risk operations require a quick `y`.
143
+ - **Auto-Run** — Safe diagnostics (`ls`, `cat`, `grep`, `git status`) execute immediately.
144
+
145
+ Initialize or customize your rules:
146
+
147
+ ```bash
148
+ hey --init
149
+ ```
150
+
151
+ ---
152
+
153
+ ## OS Skills
154
+
155
+ `hey` ships with built-in knowledge for macOS, Ubuntu/Debian, Arch Linux, Fedora/RHEL, Windows PowerShell, FreeBSD, and ChromeOS.
156
+
157
+ **Want to improve it for your OS?** Add a Markdown file to `hey_cli/skills/` with plain-English rules (e.g., "On Alpine, use `apk add` instead of `apt install`"). The engine loads them dynamically at runtime.
158
+
159
+ Pull requests for new OS skills are welcome!
160
+
161
+ ---
162
+
163
+ ## Architecture
164
+
165
+ ```
166
+ hey "your question"
167
+
168
+
169
+ ┌──────────────┐ ┌──────────────────┐
170
+ │ CLI Parser │────▶│ Governance Check │
171
+ └──────────────┘ └────────┬─────────┘
172
+
173
+ ┌─────────▼──────────┐
174
+ │ Ollama (local LLM)│
175
+ │ localhost:11434 │
176
+ └─────────┬──────────┘
177
+
178
+ ┌─────────▼──────────┐
179
+ │ Command Runner │
180
+ │ (execute / confirm)│
181
+ └────────────────────┘
182
+ ```
183
+
184
+ - **Zero external API calls** — communicates with Ollama via `localhost:11434` using Python's built-in `urllib`.
185
+ - **Zero compiled dependencies** — the only runtime dependency is `rich` (for terminal formatting).
186
+ - **Pure Python 3.9–3.14** — no C extensions, no Rust, no build tools required.
187
+
188
+ ---
189
+
190
+ ## Contributing
191
+
192
+ 1. Fork the repository
193
+ 2. Create a feature branch: `git checkout -b feature/my-feature`
194
+ 3. Commit changes: `git commit -m "feat: add my feature"`
195
+ 4. Push and open a Pull Request
196
+
197
+ See [RELEASING.md](RELEASING.md) for maintainer release instructions.
198
+
199
+ ---
200
+
201
+ ## License
202
+
203
+ [MIT](LICENSE) — Mohit Singh Sinsniwal
@@ -0,0 +1,175 @@
1
+ <div align="center">
2
+ <h1>hey-cli</h1>
3
+ <p><strong>Your terminal buddy that turns plain English into shell scripts — and runs them for you.</strong></p>
4
+
5
+ <a href="https://pypi.org/project/hey-cli-python/"><img src="https://img.shields.io/pypi/v/hey-cli-python?label=PyPI&color=blue" alt="PyPI" /></a>
6
+ <img src="https://img.shields.io/pypi/pyversions/hey-cli-python?color=blue" alt="Python" />
7
+ <a href="https://github.com/sinsniwal/hey-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License" /></a>
8
+ <a href="https://github.com/sinsniwal/hey-cli/releases/latest"><img src="https://img.shields.io/github/v/release/sinsniwal/hey-cli?label=Release&color=orange" alt="Release" /></a>
9
+ </div>
10
+
11
+ <br>
12
+
13
+ `hey` is a terminal-native AI assistant that translates plain English into executable shell commands using a locally-hosted LLM via [Ollama](https://ollama.com). Your data never leaves your machine.
14
+
15
+ ```
16
+ $ hey find all python files modified in the last 24 hours
17
+ ● Thinking...
18
+
19
+ ▶ find . -name "*.py" -mtime -1 -type f
20
+
21
+ Run this command? [Y/n]:
22
+ ```
23
+
24
+ ---
25
+
26
+ ## Features
27
+
28
+ - **100% Local & Private** — All reasoning happens on your machine via Ollama. No API keys, no cloud, no telemetry.
29
+ - **Cross-Platform Intelligence** — Detects your OS (macOS/Linux/Windows) and generates the correct flags. Won't suggest `xargs -d` on BSD or `apt` on Arch.
30
+ - **Agentic Context Gathering** — Ask "is Docker running?" and `hey` silently runs diagnostics, reads the output, and answers in plain English.
31
+ - **Security Governance** — Dangerous commands (`rm -rf`, `mkfs`, `DROP TABLE`) are intercepted and require explicit confirmation before execution.
32
+ - **Pipe-Friendly** — Pipe error logs directly: `npm run build 2>&1 | hey what is causing this error?`
33
+ - **Conversational Memory** — Remembers your recent interactions for follow-up questions.
34
+
35
+ ---
36
+
37
+ ## Installation
38
+
39
+ `hey` requires [Ollama](https://ollama.com) running locally. Install it first, then choose your platform:
40
+
41
+ ### macOS (Homebrew)
42
+
43
+ ```bash
44
+ brew tap sinsniwal/hey-cli
45
+ brew install hey-cli
46
+ ```
47
+
48
+ ### macOS & Linux (curl)
49
+
50
+ ```bash
51
+ curl -sL https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.sh | bash
52
+ ```
53
+
54
+ ### Windows (Scoop)
55
+
56
+ ```powershell
57
+ scoop install https://raw.githubusercontent.com/sinsniwal/hey-cli/main/scoop/hey-cli.json
58
+ ```
59
+
60
+ ### Windows (PowerShell Installer)
61
+
62
+ ```powershell
63
+ Invoke-WebRequest -Uri "https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.ps1" -OutFile "$env:TEMP\hey_install.ps1"; & "$env:TEMP\hey_install.ps1"
64
+ ```
65
+
66
+ ### Windows (Standalone Binary)
67
+
68
+ Download `hey.exe` from the [latest release](https://github.com/sinsniwal/hey-cli/releases/latest). No Python required.
69
+
70
+ ### pip / pipx
71
+
72
+ ```bash
73
+ pipx install hey-cli-python
74
+ ```
75
+
76
+ > **Note:** After installation, pull the default model: `ollama pull gpt-oss:20b-cloud`
77
+
78
+ ---
79
+
80
+ ## Usage
81
+
82
+ ```bash
83
+ hey <your objective in plain English>
84
+ ```
85
+
86
+ ### Examples
87
+
88
+ | Command | What happens |
89
+ |---------|-------------|
90
+ | `hey list all running docker containers` | Generates and runs `docker ps` |
91
+ | `hey is port 8080 in use?` | Silently runs `lsof -i :8080`, reads output, answers in English |
92
+ | `hey forcefully delete all .pyc files` | Generates `find . -name "*.pyc" -delete`, pauses for confirmation |
93
+ | `hey compress this folder into a tar.gz` | Generates the correct `tar` command for your OS |
94
+ | `npm run build 2>&1 \| hey what broke?` | Reads piped stderr and explains the error |
95
+ | `hey --clear` | Wipes conversational memory |
96
+
97
+ ### Execution Levels
98
+
99
+ | Level | Flag | Behavior |
100
+ |-------|------|----------|
101
+ | 0 | `--level 0` | Dry-run — shows the command but never executes |
102
+ | 1 | *(default)* | Supervised — safe commands auto-run, risky ones ask for confirmation |
103
+ | 2 | `--level 2` | Unrestricted — executes everything without confirmation |
104
+ | 3 | `--level 3` | Troubleshooter — iteratively debugs until the objective is resolved |
105
+
106
+ ---
107
+
108
+ ## Security
109
+
110
+ Safety is enforced at runtime via a local governance engine (`~/.hey-rules.json`):
111
+
112
+ - **Blocked** — `rm -rf /`, `mkfs`, `:(){ :|:& };:` are permanently rejected.
113
+ - **Explicit Confirm** — High-risk operations (`rm`, `truncate`, `DROP`) require typing a keyword to authorize.
114
+ - **Y/N Confirm** — Moderate-risk operations require a quick `y`.
115
+ - **Auto-Run** — Safe diagnostics (`ls`, `cat`, `grep`, `git status`) execute immediately.
116
+
117
+ Initialize or customize your rules:
118
+
119
+ ```bash
120
+ hey --init
121
+ ```
122
+
123
+ ---
124
+
125
+ ## OS Skills
126
+
127
+ `hey` ships with built-in knowledge for macOS, Ubuntu/Debian, Arch Linux, Fedora/RHEL, Windows PowerShell, FreeBSD, and ChromeOS.
128
+
129
+ **Want to improve it for your OS?** Add a Markdown file to `hey_cli/skills/` with plain-English rules (e.g., "On Alpine, use `apk add` instead of `apt install`"). The engine loads them dynamically at runtime.
130
+
131
+ Pull requests for new OS skills are welcome!
132
+
133
+ ---
134
+
135
+ ## Architecture
136
+
137
+ ```
138
+ hey "your question"
139
+
140
+
141
+ ┌──────────────┐ ┌──────────────────┐
142
+ │ CLI Parser │────▶│ Governance Check │
143
+ └──────────────┘ └────────┬─────────┘
144
+
145
+ ┌─────────▼──────────┐
146
+ │ Ollama (local LLM)│
147
+ │ localhost:11434 │
148
+ └─────────┬──────────┘
149
+
150
+ ┌─────────▼──────────┐
151
+ │ Command Runner │
152
+ │ (execute / confirm)│
153
+ └────────────────────┘
154
+ ```
155
+
156
+ - **Zero external API calls** — communicates with Ollama via `localhost:11434` using Python's built-in `urllib`.
157
+ - **Zero compiled dependencies** — the only runtime dependency is `rich` (for terminal formatting).
158
+ - **Pure Python 3.9–3.14** — no C extensions, no Rust, no build tools required.
159
+
160
+ ---
161
+
162
+ ## Contributing
163
+
164
+ 1. Fork the repository
165
+ 2. Create a feature branch: `git checkout -b feature/my-feature`
166
+ 3. Commit changes: `git commit -m "feat: add my feature"`
167
+ 4. Push and open a Pull Request
168
+
169
+ See [RELEASING.md](RELEASING.md) for maintainer release instructions.
170
+
171
+ ---
172
+
173
+ ## License
174
+
175
+ [MIT](LICENSE) — Mohit Singh Sinsniwal
@@ -93,7 +93,10 @@ def main():
93
93
 
94
94
  console.print("[bold yellow]●[/bold yellow] Thinking...")
95
95
  past_messages = history_mgr.load()
96
- response = generate_command(objective, context=piped_data, model_name=model_name, history=past_messages)
96
+ try:
97
+ response = generate_command(objective, context=piped_data, model_name=model_name, history=past_messages)
98
+ except urllib.error.URLError:
99
+ check_ollama() # always fails here — shows the panel and exits
97
100
 
98
101
  # Save the user query to history IMMEDIATELY
99
102
  history_mgr.append("user", user_prompt)
@@ -85,6 +85,8 @@ def generate_command(prompt: str, context: str = "", model_name: str = DEFAULT_M
85
85
  data = json.loads(content_str)
86
86
  return CommandResponse(**data)
87
87
 
88
+ except urllib.error.URLError:
89
+ raise # Ollama not reachable — don't retry, bubble up to cli
88
90
  except Exception as e:
89
91
  last_error = e
90
92
  if "refusal" in raw_val.lower() or "sorry" in raw_val.lower():
@@ -150,6 +152,8 @@ def generate_troubleshoot_step(objective: str, history: list, model_name: str =
150
152
  data = json.loads(content_str)
151
153
  return TroubleshootResponse(**data)
152
154
 
155
+ except urllib.error.URLError:
156
+ raise # Ollama not reachable — don't retry, bubble up to cli
153
157
  except Exception as e:
154
158
  last_error = e
155
159
  msgs.append({"role": "assistant", "content": raw_val})
@@ -1,5 +1,7 @@
1
1
  import subprocess
2
2
  import sys
3
+ import json
4
+ import dataclasses
3
5
  from typing import Optional
4
6
 
5
7
  from .governance import GovernanceEngine, Action
@@ -121,7 +123,7 @@ class CommandRunner:
121
123
  if not cmd or cmd.startswith("echo ") or cmd.startswith("printf "):
122
124
  self.history_mgr.append("assistant", current_response.explanation)
123
125
  else:
124
- self.history_mgr.append("assistant", current_response.model_dump_json())
126
+ self.history_mgr.append("assistant", json.dumps(dataclasses.asdict(current_response)))
125
127
 
126
128
  # Level 0 = Dry Run
127
129
  if self.level == 0:
@@ -0,0 +1,203 @@
1
+ Metadata-Version: 2.4
2
+ Name: hey-cli-python
3
+ Version: 1.0.5
4
+ Summary: A secure, zero-bloat CLI companion that turns natural language and error logs into executable commands.
5
+ Author: Mohit Singh Sinsniwal
6
+ Project-URL: Homepage, https://github.com/sinsniwal/hey-cli
7
+ Project-URL: Repository, https://github.com/sinsniwal/hey-cli
8
+ Project-URL: Issues, https://github.com/sinsniwal/hey-cli/issues
9
+ Keywords: cli,llm,bash,terminal,ollama,sysadmin
10
+ Classifier: Development Status :: 5 - Production/Stable
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Operating System :: MacOS
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Classifier: Operating System :: Microsoft :: Windows
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Requires-Python: >=3.9
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Requires-Dist: rich>=13.0.0
27
+ Dynamic: license-file
28
+
29
+ <div align="center">
30
+ <h1>hey-cli</h1>
31
+ <p><strong>Your terminal buddy that turns plain English into shell scripts — and runs them for you.</strong></p>
32
+
33
+ <a href="https://pypi.org/project/hey-cli-python/"><img src="https://img.shields.io/pypi/v/hey-cli-python?label=PyPI&color=blue" alt="PyPI" /></a>
34
+ <img src="https://img.shields.io/pypi/pyversions/hey-cli-python?color=blue" alt="Python" />
35
+ <a href="https://github.com/sinsniwal/hey-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License" /></a>
36
+ <a href="https://github.com/sinsniwal/hey-cli/releases/latest"><img src="https://img.shields.io/github/v/release/sinsniwal/hey-cli?label=Release&color=orange" alt="Release" /></a>
37
+ </div>
38
+
39
+ <br>
40
+
41
+ `hey` is a terminal-native AI assistant that translates plain English into executable shell commands using a locally-hosted LLM via [Ollama](https://ollama.com). Your data never leaves your machine.
42
+
43
+ ```
44
+ $ hey find all python files modified in the last 24 hours
45
+ ● Thinking...
46
+
47
+ ▶ find . -name "*.py" -mtime -1 -type f
48
+
49
+ Run this command? [Y/n]:
50
+ ```
51
+
52
+ ---
53
+
54
+ ## Features
55
+
56
+ - **100% Local & Private** — All reasoning happens on your machine via Ollama. No API keys, no cloud, no telemetry.
57
+ - **Cross-Platform Intelligence** — Detects your OS (macOS/Linux/Windows) and generates the correct flags. Won't suggest `xargs -d` on BSD or `apt` on Arch.
58
+ - **Agentic Context Gathering** — Ask "is Docker running?" and `hey` silently runs diagnostics, reads the output, and answers in plain English.
59
+ - **Security Governance** — Dangerous commands (`rm -rf`, `mkfs`, `DROP TABLE`) are intercepted and require explicit confirmation before execution.
60
+ - **Pipe-Friendly** — Pipe error logs directly: `npm run build 2>&1 | hey what is causing this error?`
61
+ - **Conversational Memory** — Remembers your recent interactions for follow-up questions.
62
+
63
+ ---
64
+
65
+ ## Installation
66
+
67
+ `hey` requires [Ollama](https://ollama.com) running locally. Install it first, then choose your platform:
68
+
69
+ ### macOS (Homebrew)
70
+
71
+ ```bash
72
+ brew tap sinsniwal/hey-cli
73
+ brew install hey-cli
74
+ ```
75
+
76
+ ### macOS & Linux (curl)
77
+
78
+ ```bash
79
+ curl -sL https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.sh | bash
80
+ ```
81
+
82
+ ### Windows (Scoop)
83
+
84
+ ```powershell
85
+ scoop install https://raw.githubusercontent.com/sinsniwal/hey-cli/main/scoop/hey-cli.json
86
+ ```
87
+
88
+ ### Windows (PowerShell Installer)
89
+
90
+ ```powershell
91
+ Invoke-WebRequest -Uri "https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.ps1" -OutFile "$env:TEMP\hey_install.ps1"; & "$env:TEMP\hey_install.ps1"
92
+ ```
93
+
94
+ ### Windows (Standalone Binary)
95
+
96
+ Download `hey.exe` from the [latest release](https://github.com/sinsniwal/hey-cli/releases/latest). No Python required.
97
+
98
+ ### pip / pipx
99
+
100
+ ```bash
101
+ pipx install hey-cli-python
102
+ ```
103
+
104
+ > **Note:** After installation, pull the default model: `ollama pull gpt-oss:20b-cloud`
105
+
106
+ ---
107
+
108
+ ## Usage
109
+
110
+ ```bash
111
+ hey <your objective in plain English>
112
+ ```
113
+
114
+ ### Examples
115
+
116
+ | Command | What happens |
117
+ |---------|-------------|
118
+ | `hey list all running docker containers` | Generates and runs `docker ps` |
119
+ | `hey is port 8080 in use?` | Silently runs `lsof -i :8080`, reads output, answers in English |
120
+ | `hey forcefully delete all .pyc files` | Generates `find . -name "*.pyc" -delete`, pauses for confirmation |
121
+ | `hey compress this folder into a tar.gz` | Generates the correct `tar` command for your OS |
122
+ | `npm run build 2>&1 \| hey what broke?` | Reads piped stderr and explains the error |
123
+ | `hey --clear` | Wipes conversational memory |
124
+
125
+ ### Execution Levels
126
+
127
+ | Level | Flag | Behavior |
128
+ |-------|------|----------|
129
+ | 0 | `--level 0` | Dry-run — shows the command but never executes |
130
+ | 1 | *(default)* | Supervised — safe commands auto-run, risky ones ask for confirmation |
131
+ | 2 | `--level 2` | Unrestricted — executes everything without confirmation |
132
+ | 3 | `--level 3` | Troubleshooter — iteratively debugs until the objective is resolved |
133
+
134
+ ---
135
+
136
+ ## Security
137
+
138
+ Safety is enforced at runtime via a local governance engine (`~/.hey-rules.json`):
139
+
140
+ - **Blocked** — `rm -rf /`, `mkfs`, `:(){ :|:& };:` are permanently rejected.
141
+ - **Explicit Confirm** — High-risk operations (`rm`, `truncate`, `DROP`) require typing a keyword to authorize.
142
+ - **Y/N Confirm** — Moderate-risk operations require a quick `y`.
143
+ - **Auto-Run** — Safe diagnostics (`ls`, `cat`, `grep`, `git status`) execute immediately.
144
+
145
+ Initialize or customize your rules:
146
+
147
+ ```bash
148
+ hey --init
149
+ ```
150
+
151
+ ---
152
+
153
+ ## OS Skills
154
+
155
+ `hey` ships with built-in knowledge for macOS, Ubuntu/Debian, Arch Linux, Fedora/RHEL, Windows PowerShell, FreeBSD, and ChromeOS.
156
+
157
+ **Want to improve it for your OS?** Add a Markdown file to `hey_cli/skills/` with plain-English rules (e.g., "On Alpine, use `apk add` instead of `apt install`"). The engine loads them dynamically at runtime.
158
+
159
+ Pull requests for new OS skills are welcome!
160
+
161
+ ---
162
+
163
+ ## Architecture
164
+
165
+ ```
166
+ hey "your question"
167
+
168
+
169
+ ┌──────────────┐ ┌──────────────────┐
170
+ │ CLI Parser │────▶│ Governance Check │
171
+ └──────────────┘ └────────┬─────────┘
172
+
173
+ ┌─────────▼──────────┐
174
+ │ Ollama (local LLM)│
175
+ │ localhost:11434 │
176
+ └─────────┬──────────┘
177
+
178
+ ┌─────────▼──────────┐
179
+ │ Command Runner │
180
+ │ (execute / confirm)│
181
+ └────────────────────┘
182
+ ```
183
+
184
+ - **Zero external API calls** — communicates with Ollama via `localhost:11434` using Python's built-in `urllib`.
185
+ - **Zero compiled dependencies** — the only runtime dependency is `rich` (for terminal formatting).
186
+ - **Pure Python 3.9–3.14** — no C extensions, no Rust, no build tools required.
187
+
188
+ ---
189
+
190
+ ## Contributing
191
+
192
+ 1. Fork the repository
193
+ 2. Create a feature branch: `git checkout -b feature/my-feature`
194
+ 3. Commit changes: `git commit -m "feat: add my feature"`
195
+ 4. Push and open a Pull Request
196
+
197
+ See [RELEASING.md](RELEASING.md) for maintainer release instructions.
198
+
199
+ ---
200
+
201
+ ## License
202
+
203
+ [MIT](LICENSE) — Mohit Singh Sinsniwal
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "hey-cli-python"
7
- version = "1.0.3"
7
+ version = "1.0.5"
8
8
  description = "A secure, zero-bloat CLI companion that turns natural language and error logs into executable commands."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.9"
@@ -1,97 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: hey-cli-python
3
- Version: 1.0.3
4
- Summary: A secure, zero-bloat CLI companion that turns natural language and error logs into executable commands.
5
- Author: Mohit Singh Sinsniwal
6
- Project-URL: Homepage, https://github.com/sinsniwal/hey-cli
7
- Project-URL: Repository, https://github.com/sinsniwal/hey-cli
8
- Project-URL: Issues, https://github.com/sinsniwal/hey-cli/issues
9
- Keywords: cli,llm,bash,terminal,ollama,sysadmin
10
- Classifier: Development Status :: 5 - Production/Stable
11
- Classifier: Environment :: Console
12
- Classifier: Intended Audience :: Developers
13
- Classifier: License :: OSI Approved :: MIT License
14
- Classifier: Operating System :: MacOS
15
- Classifier: Operating System :: POSIX :: Linux
16
- Classifier: Operating System :: Microsoft :: Windows
17
- Classifier: Programming Language :: Python :: 3.9
18
- Classifier: Programming Language :: Python :: 3.10
19
- Classifier: Programming Language :: Python :: 3.11
20
- Classifier: Programming Language :: Python :: 3.12
21
- Classifier: Programming Language :: Python :: 3.13
22
- Classifier: Programming Language :: Python :: 3.14
23
- Requires-Python: >=3.9
24
- Description-Content-Type: text/markdown
25
- License-File: LICENSE
26
- Requires-Dist: rich>=13.0.0
27
- Dynamic: license-file
28
-
29
- <div align="center">
30
- <h1>hey-cli 🤖</h1>
31
- <p><strong>A zero-bloat, privacy-first, locally-hosted CLI agent powered by Ollama.</strong></p>
32
-
33
- <img src="https://img.shields.io/badge/Python-3.9+-blue.svg" alt="Python Version" />
34
- <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License" />
35
- <img src="https://img.shields.io/badge/Ollama-Local-orange.svg" alt="Ollama Local" />
36
- </div>
37
-
38
- <br>
39
-
40
- `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.
41
-
42
- > 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.
43
-
44
- ## 🚀 Why `hey-cli` over Copilot/ChatGPT?
45
- 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).
46
- 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.
47
- 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.
48
- 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.
49
-
50
- ## 📦 Installation
51
-
52
- **Prerequisite:** You must have [Python 3.9+](https://www.python.org/downloads/) installed.
53
-
54
- ### macOS & Linux
55
- Paste this snippet into your terminal to auto-install `pipx`, `ollama`, pull the required language model, and build `hey-cli` natively.
56
- ```bash
57
- curl -sL https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.sh | bash
58
- ```
59
-
60
- ### Windows (PowerShell)
61
- Paste this into your PowerShell terminal:
62
- ```powershell
63
- Invoke-WebRequest -Uri "https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.ps1" -OutFile "$env:TEMP\hey_install.ps1"; & "$env:TEMP\hey_install.ps1"
64
- ```
65
-
66
- ## 🛠️ Usage
67
-
68
- Simply type `hey` followed by your objective.
69
-
70
- **Context-Gathering (Zero-Trust)**
71
- ```bash
72
- hey is my docker hub running?
73
- ```
74
- *`hey` will silently run `systemctl is-active docker` or `docker info`, see that it failed to connect to the socket, and explain the situation.*
75
-
76
- **Execution (Governance Protected)**
77
- ```bash
78
- hey forcefully delete all .pyc files
79
- ```
80
- *`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.*
81
-
82
- **Debugging Logs**
83
- ```bash
84
- npm run build 2>&1 | hey what is causing this webpack error?
85
- ```
86
-
87
- ## 🛡️ Governance Matrix
88
- Safety is a first-class citizen. `hey-cli` maintains a local governance database (`~/.hey-rules.json`):
89
- - **Never List**: Things like `rm -rf /` and `mkfs` are permanently blocked at the compiler level.
90
- - **Explicit Confirm**: High-risk ops (`truncate`, `drop`, `rm`) require typing exact keyword verification.
91
- - **Y/N Confirm**: Moderate risk ops requiring a quick `y`.
92
- - **Allowed List**: Safe diagnostics like `cat`, `ls`, `grep` auto-run natively.
93
-
94
- ## 🤝 Adding OS Skills
95
- Is `hey` generating incorrect shell semantics for your niche operating system?
96
-
97
- 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!
@@ -1,69 +0,0 @@
1
- <div align="center">
2
- <h1>hey-cli 🤖</h1>
3
- <p><strong>A zero-bloat, privacy-first, locally-hosted CLI agent powered by Ollama.</strong></p>
4
-
5
- <img src="https://img.shields.io/badge/Python-3.9+-blue.svg" alt="Python Version" />
6
- <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License" />
7
- <img src="https://img.shields.io/badge/Ollama-Local-orange.svg" alt="Ollama Local" />
8
- </div>
9
-
10
- <br>
11
-
12
- `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.
13
-
14
- > 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.
15
-
16
- ## 🚀 Why `hey-cli` over Copilot/ChatGPT?
17
- 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).
18
- 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.
19
- 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.
20
- 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.
21
-
22
- ## 📦 Installation
23
-
24
- **Prerequisite:** You must have [Python 3.9+](https://www.python.org/downloads/) installed.
25
-
26
- ### macOS & Linux
27
- Paste this snippet into your terminal to auto-install `pipx`, `ollama`, pull the required language model, and build `hey-cli` natively.
28
- ```bash
29
- curl -sL https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.sh | bash
30
- ```
31
-
32
- ### Windows (PowerShell)
33
- Paste this into your PowerShell terminal:
34
- ```powershell
35
- Invoke-WebRequest -Uri "https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.ps1" -OutFile "$env:TEMP\hey_install.ps1"; & "$env:TEMP\hey_install.ps1"
36
- ```
37
-
38
- ## 🛠️ Usage
39
-
40
- Simply type `hey` followed by your objective.
41
-
42
- **Context-Gathering (Zero-Trust)**
43
- ```bash
44
- hey is my docker hub running?
45
- ```
46
- *`hey` will silently run `systemctl is-active docker` or `docker info`, see that it failed to connect to the socket, and explain the situation.*
47
-
48
- **Execution (Governance Protected)**
49
- ```bash
50
- hey forcefully delete all .pyc files
51
- ```
52
- *`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.*
53
-
54
- **Debugging Logs**
55
- ```bash
56
- npm run build 2>&1 | hey what is causing this webpack error?
57
- ```
58
-
59
- ## 🛡️ Governance Matrix
60
- Safety is a first-class citizen. `hey-cli` maintains a local governance database (`~/.hey-rules.json`):
61
- - **Never List**: Things like `rm -rf /` and `mkfs` are permanently blocked at the compiler level.
62
- - **Explicit Confirm**: High-risk ops (`truncate`, `drop`, `rm`) require typing exact keyword verification.
63
- - **Y/N Confirm**: Moderate risk ops requiring a quick `y`.
64
- - **Allowed List**: Safe diagnostics like `cat`, `ls`, `grep` auto-run natively.
65
-
66
- ## 🤝 Adding OS Skills
67
- Is `hey` generating incorrect shell semantics for your niche operating system?
68
-
69
- 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!
@@ -1,97 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: hey-cli-python
3
- Version: 1.0.3
4
- Summary: A secure, zero-bloat CLI companion that turns natural language and error logs into executable commands.
5
- Author: Mohit Singh Sinsniwal
6
- Project-URL: Homepage, https://github.com/sinsniwal/hey-cli
7
- Project-URL: Repository, https://github.com/sinsniwal/hey-cli
8
- Project-URL: Issues, https://github.com/sinsniwal/hey-cli/issues
9
- Keywords: cli,llm,bash,terminal,ollama,sysadmin
10
- Classifier: Development Status :: 5 - Production/Stable
11
- Classifier: Environment :: Console
12
- Classifier: Intended Audience :: Developers
13
- Classifier: License :: OSI Approved :: MIT License
14
- Classifier: Operating System :: MacOS
15
- Classifier: Operating System :: POSIX :: Linux
16
- Classifier: Operating System :: Microsoft :: Windows
17
- Classifier: Programming Language :: Python :: 3.9
18
- Classifier: Programming Language :: Python :: 3.10
19
- Classifier: Programming Language :: Python :: 3.11
20
- Classifier: Programming Language :: Python :: 3.12
21
- Classifier: Programming Language :: Python :: 3.13
22
- Classifier: Programming Language :: Python :: 3.14
23
- Requires-Python: >=3.9
24
- Description-Content-Type: text/markdown
25
- License-File: LICENSE
26
- Requires-Dist: rich>=13.0.0
27
- Dynamic: license-file
28
-
29
- <div align="center">
30
- <h1>hey-cli 🤖</h1>
31
- <p><strong>A zero-bloat, privacy-first, locally-hosted CLI agent powered by Ollama.</strong></p>
32
-
33
- <img src="https://img.shields.io/badge/Python-3.9+-blue.svg" alt="Python Version" />
34
- <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License" />
35
- <img src="https://img.shields.io/badge/Ollama-Local-orange.svg" alt="Ollama Local" />
36
- </div>
37
-
38
- <br>
39
-
40
- `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.
41
-
42
- > 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.
43
-
44
- ## 🚀 Why `hey-cli` over Copilot/ChatGPT?
45
- 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).
46
- 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.
47
- 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.
48
- 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.
49
-
50
- ## 📦 Installation
51
-
52
- **Prerequisite:** You must have [Python 3.9+](https://www.python.org/downloads/) installed.
53
-
54
- ### macOS & Linux
55
- Paste this snippet into your terminal to auto-install `pipx`, `ollama`, pull the required language model, and build `hey-cli` natively.
56
- ```bash
57
- curl -sL https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.sh | bash
58
- ```
59
-
60
- ### Windows (PowerShell)
61
- Paste this into your PowerShell terminal:
62
- ```powershell
63
- Invoke-WebRequest -Uri "https://raw.githubusercontent.com/sinsniwal/hey-cli/main/install.ps1" -OutFile "$env:TEMP\hey_install.ps1"; & "$env:TEMP\hey_install.ps1"
64
- ```
65
-
66
- ## 🛠️ Usage
67
-
68
- Simply type `hey` followed by your objective.
69
-
70
- **Context-Gathering (Zero-Trust)**
71
- ```bash
72
- hey is my docker hub running?
73
- ```
74
- *`hey` will silently run `systemctl is-active docker` or `docker info`, see that it failed to connect to the socket, and explain the situation.*
75
-
76
- **Execution (Governance Protected)**
77
- ```bash
78
- hey forcefully delete all .pyc files
79
- ```
80
- *`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.*
81
-
82
- **Debugging Logs**
83
- ```bash
84
- npm run build 2>&1 | hey what is causing this webpack error?
85
- ```
86
-
87
- ## 🛡️ Governance Matrix
88
- Safety is a first-class citizen. `hey-cli` maintains a local governance database (`~/.hey-rules.json`):
89
- - **Never List**: Things like `rm -rf /` and `mkfs` are permanently blocked at the compiler level.
90
- - **Explicit Confirm**: High-risk ops (`truncate`, `drop`, `rm`) require typing exact keyword verification.
91
- - **Y/N Confirm**: Moderate risk ops requiring a quick `y`.
92
- - **Allowed List**: Safe diagnostics like `cat`, `ls`, `grep` auto-run natively.
93
-
94
- ## 🤝 Adding OS Skills
95
- Is `hey` generating incorrect shell semantics for your niche operating system?
96
-
97
- 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!
File without changes
File without changes