semvec/pypi-packages huggingface dataset:
ShellSteward 0.2.0
ShellSteward: AI-powered CLI assistant for shell command generation and retrieval
License: MIT
Requires Python: >=3.7

# 🧠 ShellSteward — Your AI-Powered Shell Companion

ShellSteward is a smart command-line assistant that translates natural language prompts into shell commands using semantic search. Whether you're navigating directories, inspecting files, or debugging your environment, ShellSteward helps you do it faster and smarter.

---

## 🚀 Features

- 🔍 Natural language to shell command retrieval  
- 🧠 Semantic search using SentenceTransformers + FAISS  
- 🛠️ Cross-shell support (bash, zsh, cmd, PowerShell)  
- 🧪 Doctor command to verify setup and dependencies  
- 📋 History tracking and clipboard support  
- ⚙️ Configurable shell preferences and onboarding  

---

## 📦 Installation

```bash
pip install shellsteward
```

Or from source:

```bash
git clone https://github.com/ABHIJEETRAI-AV/Catalyst.git
cd shellsteward
pip install -e .
```

---

## 🧑‍💻 CLI Usage

### `shellsteward init`

Initializes the FAISS index from `commands.json`.

- Embeds all prompt-command pairs  
- Saves the index to `index/faiss.index`  
- Required before using `ask`

```bash
shellsteward init
```

---

### `shellsteward ask "<your prompt>"`

Retrieves the best matching shell command for your natural language query.

```bash
shellsteward ask "How do I list all files including hidden ones?"
```

Options:
- `--copy` → Copies the command to clipboard  
- `--explain` → Shows the explanation instead of the command  
- `--shell bash|zsh|cmd|powershell` → Tailors output to your shell  

---

### `shellsteward doctor`

Checks if your environment is ready.

- Verifies `commands.json` is accessible  
- Confirms FAISS index exists  
- Checks if SentenceTransformer model is loaded  

```bash
shellsteward doctor
```

---

### `shellsteward history`

Displays previously retrieved commands.

```bash
shellsteward history
```

Options:
- `--copy <index>` → Copies a specific command from history  
- `--explain <index>` → Shows explanation for a specific entry  

---

### `shellsteward config` *(coming soon)*

Manage persistent settings like default shell, verbosity, and model preferences.

---

## 🧠 How It Works

ShellSteward uses:

- `commands.json` → A curated list of prompt-command-explanation triples  
- `SentenceTransformer` → Converts prompts into embeddings  
- `FAISS` → Performs fast vector similarity search  
- `Typer` → Powers the CLI interface  

---

## 📄 License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

---

## 🤝 Contributing

Pull requests are welcome! For major changes, open an issue first to discuss what you'd like to improve.

---

Made with ❤️ by Abhijeet Rai

---