cmdrun 0.1.0

A CLI tool to register and retrieve terminal commands using natural language and semantic search

cmdrun

Remember terminal commands using natural language and semantic search — entirely offline.

cmdrun "show all pods"

╭─ Best match ────────────────────────────────╮
│ kubectl get pods -A                          │
╰─ similarity 0.87 ───────────────────────────╯

---

Table of contents

• Installation
• Quick start
• Commands
• Architecture
• Configuration
• Development

---

Installation

pip install cmdrun

Requires Python 3.9+. All data is stored locally under ~/.cmdrun/ — nothing leaves your machine.

---

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. Retrieve it with natural language

$ cmdrun "show pods"

╭─ Best match ────────────────────────────────╮
│ kubectl get pods -A                          │
╰─ similarity 0.87 ───────────────────────────╯

3. Run it immediately

$ cmdrun --run "show pods"

Running: kubectl get pods -A

NAME           READY  STATUS   RESTARTS  AGE
...

---

Commands

Command	Description
cmdrun register	Interactively register a new description → command mapping
cmdrun "query"	Retrieve the best-matching command for a natural language query
cmdrun --run "query"	Retrieve and execute the best-matching command
cmdrun list	Show all registered commands in a table
cmdrun remove	Remove a registered command by list index
cmdrun rebuild	Rebuild the FAISS index from commands.json

Options

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

---

Architecture

cmdrun "show all pods"
        │
        ▼
   cli.py  (Typer + Rich)
        │
        ▼
  embeddings.py  — sentence-transformers/all-MiniLM-L6-v2 (384d, lazy-loaded)
        │
        ▼
  vector_store.py  — FAISS IndexFlatIP (cosine similarity via normalised vectors)
        │
        ▼
   matcher.py  — top-k search, threshold filtering, MatchResponse
        │
        ▼
  storage.py  — commands.json  (source of truth, Pydantic models)

Data files

All data lives in ~/.cmdrun/:

File	Purpose
commands.json	Human-readable list of description → command pairs
index.faiss	FAISS binary index (vector search)
metadata.pkl	Maps FAISS vector positions back to CommandEntry objects

Similarity search

1. Query text is embedded with all-MiniLM-L6-v2 (384 dimensions, L2-normalised).
2. FAISS IndexFlatIP performs an inner-product search (≡ cosine similarity for unit vectors).
3. The top-k (default 3) candidates are returned.
4. If the best candidate's similarity is below 0.60 the tool reports "No command found".

---

Configuration

The following constants in cmdrun/config.py can be adjusted:

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

---

Development

# Clone / enter the project
cd cmdrun

# 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/
├── __init__.py       Package metadata
├── cli.py            Typer app — all user-facing commands
├── config.py         Paths, model name, thresholds
├── storage.py        commands.json read/write (Pydantic models)
├── embeddings.py     Lazy-loaded sentence-transformers wrapper
├── vector_store.py   FAISS index management
└── matcher.py        High-level matching pipeline

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

data/
└── commands.json     Seed/example data (empty by default)

pyproject.toml
README.md

---

Examples

Register a handful of commands

cmdrun register
  Description: list all kubernetes pods across namespaces
  Command: kubectl get pods -A

cmdrun register
  Description: list running docker containers
  Command: docker ps

cmdrun register
  Description: show disk usage human readable
  Command: df -h

cmdrun register
  Description: find large files in current directory
  Command: find . -type f -size +100M

cmdrun register
  Description: tail application logs
  Command: tail -f /var/log/app.log

Query examples

cmdrun "pods in kubernetes"
cmdrun "docker running"
cmdrun "how much disk space"
cmdrun "big files"
cmdrun "follow logs"

Execute directly

cmdrun --run "show disk usage"

Manage your catalogue

cmdrun list      # view all entries with their index numbers
cmdrun remove    # choose an entry to delete by number
cmdrun rebuild   # re-sync index after manually editing commands.json

---

Performance

Operation	Typical latency
Cold start (first query, model load)	~1–2 s
Subsequent queries (model cached)	< 50 ms
Index rebuild (100 entries)	~2 s

---

License

MIT