Metadata-Version: 2.4
Name: cmdrun
Version: 0.1.1
Summary: A CLI tool to register and retrieve terminal commands using natural language and semantic search
Project-URL: Homepage, https://github.com/your-username/cmdrun
Project-URL: Repository, https://github.com/your-username/cmdrun
Project-URL: Issues, https://github.com/your-username/cmdrun/issues
Project-URL: Changelog, https://github.com/your-username/cmdrun/releases
Author: cmdrun contributors
License: MIT License
        
        Copyright (c) 2025 cmdrun contributors
        
        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.
License-File: LICENSE
Keywords: cli,commands,embeddings,nlp,semantic-search,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: faiss-cpu>=1.8.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# cmdrun

Stop googling the same commands. Describe what you want in plain English — cmdrun finds it instantly and copies it to your clipboard.

```
$ cmdrun "show all pods"
kubectl get pods -A
Copied to clipboard.
```

Runs entirely offline. No data leaves your machine.

---

## Table of contents

- [Installation](#installation)
- [Quick start](#quick-start)
- [Commands](#commands)
- [How it works](#how-it-works)
- [Performance](#performance)
- [Configuration](#configuration)
- [Development](#development)

---

## Installation

```bash
pip install cmdrun
```

Requires Python 3.9+.

---

## Quick start

### 1. Register a command

```
$ cmdrun register

Register a new command

  Description: list all kubernetes pods
  Command: kubectl get pods -A

✓ Registered: 'list all kubernetes pods' → kubectl get pods -A
```

### 2. Find it with natural language

```
$ cmdrun "show pods"
kubectl get pods -A
Copied to clipboard.
```

The matched command is printed and automatically copied to your clipboard.

### 3. Execute it directly

```
$ cmdrun --run "show pods"
kubectl get pods -A
Copied to clipboard.

Running: kubectl get pods -A
...
```

---

## Commands

| Command | Description |
|---|---|
| `cmdrun register` | Interactively save a new description → command pair |
| `cmdrun "query"` | Find the best-matching command and copy it to clipboard |
| `cmdrun --run "query"` | Find and immediately execute the best-matching command |
| `cmdrun list` | Show all saved commands in a table |
| `cmdrun remove` | Delete a saved command by its list index |
| `cmdrun clear` | Delete all saved commands |
| `cmdrun rebuild` | Rebuild the search index from `commands.json` |

### Flags

| Flag | Description |
|---|---|
| `--run` / `-r` | Execute the matched command after displaying it |
| `--verbose` / `-v` | Enable debug-level logging |

---

## How it works

cmdrun uses semantic search to match your natural language query against saved command descriptions — so "show pods", "list k8s containers", and "kubernetes running services" all find the same command.

**Search pipeline**

```
cmdrun "show all pods"
        │
        ▼
  daemon.py  ← persistent background process, model loaded once
        │
        ▼
  embeddings.py  — sentence-transformers/all-MiniLM-L6-v2 (384d, offline)
        │
        ▼
  vector_store.py  — FAISS IndexFlatIP (cosine similarity)
        │
        ▼
  matcher.py  — top-k search + threshold filtering
        │
        ▼
  storage.py  — commands.json (source of truth)
```

**Background daemon**

On the first query, cmdrun starts a background daemon that loads the embedding model once and keeps it in memory. Every subsequent query connects to the daemon via a Unix socket — no model reloading, no cold-start delay.

The daemon exits automatically after 30 minutes of inactivity and restarts on the next query.

**Similarity search**

1. Query text is embedded with `all-MiniLM-L6-v2` (384 dimensions, L2-normalised).
2. FAISS `IndexFlatIP` performs an inner-product search (equivalent to cosine similarity for unit vectors).
3. The top-3 candidates are evaluated.
4. If the best match scores below **0.60** cosine similarity, the result is rejected.

**Data files** — all stored in `~/.cmdrun/`

| File | Purpose |
|---|---|
| `commands.json` | Human-readable list of saved description → command pairs |
| `index.faiss` | FAISS binary index |
| `metadata.pkl` | Maps FAISS positions back to `CommandEntry` objects |
| `daemon.sock` | Unix socket used by the background daemon |

---

## Performance

| Operation | Latency |
|---|---|
| First query (daemon cold start) | ~1–2 s |
| Subsequent queries (daemon warm) | ~300–400 ms |
| `register` (daemon warm) | ~300–400 ms |

The ~300–400 ms on warm queries is Python's own startup time. The model inference and FAISS lookup together take under 15 ms inside the daemon.

---

## Configuration

Adjust constants in `cmdrun/config.py`:

| Constant | Default | Description |
|---|---|---|
| `SIMILARITY_THRESHOLD` | `0.60` | Minimum cosine similarity to accept a match |
| `TOP_K` | `3` | Number of candidates to evaluate per query |
| `EMBEDDING_MODEL` | `sentence-transformers/all-MiniLM-L6-v2` | HuggingFace model ID |

---

## Development

```bash
# Install in editable mode with dev extras
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=cmdrun --cov-report=term-missing

# Lint
ruff check cmdrun tests

# Type-check
mypy cmdrun
```

**Project layout**

```
cmdrun/
├── cli.py            Typer app — all user-facing commands
├── config.py         Paths, model name, thresholds
├── daemon.py         Background server — keeps model warm, handles queries
├── client.py         Thin socket client used by cli.py
├── embeddings.py     sentence-transformers wrapper (lazy-loaded, noise-suppressed)
├── storage.py        commands.json read/write (Pydantic models)
├── vector_store.py   FAISS index management
└── matcher.py        High-level matching pipeline

tests/
└── test_matcher.py   pytest suite (embeddings, vector store, matcher, storage)
```

---
