cmds

System command discovery tool. Connects user intent to executable commands using semantic search and a curated knowledge base.

Built for both human developers and LLM agents.

Features

• Natural language command search (cmds find "find large files")
• Semantic search via [xdb] with fuzzy fallback
• Detailed command info from tldr-pages data
• Category-based browsing
• Auto-detect TTY for human-readable vs JSON output
• All subcommands support --json

Install

From npm

npm install -g @theclawlab/cmds

From source

npm install
npm run build
npm link

# Scan system commands (required before first use)
cmds scan

Quick Start

# Search by intent
cmds find "compress a directory"

# Command info
cmds info curl

# Browse by category
cmds list
cmds list --category network

# JSON output for scripts/agents
cmds find "disk usage" --json --limit 3

Commands

Command	Description
cmds find <query>	Search commands by natural language query
cmds info <command>	Detailed command info
cmds list [--category <type>]	Browse commands by category
cmds scan	Scan system and build runtime index

Search Strategy

1. If [xdb] is installed — embedding-based semantic search
2. Fallback — fuzzysort matching against command name, description, and examples

xdb availability is detected during cmds scan and cached in the runtime index. If xdb is present, scan also ingests command data into xdb for semantic retrieval.

Data

• Static: tldr-pages index bundled at dist/data/tldr-index.json
• Runtime: ~/.config/cmds/index.json (generated by cmds scan)

Documentation

• USAGE.md — Full usage guide