cmdrun 0.1.1

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

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
• Quick start
• Commands
• How it works
• Performance
• Configuration
• Development

---

Installation

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

# 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)

---