https://github.com/syshin0116/clidex
CLI tool discovery for AI agents. Search, compare, and install 440+ command-line tools with structured YAML/JSON output.
https://github.com/syshin0116/clidex
ai-agents awesome-cli-apps bm25 claude-code cli cli-tools command-line developer-tools llm mcp package-manager rust search tool-discovery yaml
Last synced: 2 months ago
JSON representation
CLI tool discovery for AI agents. Search, compare, and install 440+ command-line tools with structured YAML/JSON output.
- Host: GitHub
- URL: https://github.com/syshin0116/clidex
- Owner: syshin0116
- License: mit
- Created: 2026-03-13T12:04:41.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-01T07:48:54.000Z (3 months ago)
- Last Synced: 2026-04-01T22:51:10.176Z (3 months ago)
- Topics: ai-agents, awesome-cli-apps, bm25, claude-code, cli, cli-tools, command-line, developer-tools, llm, mcp, package-manager, rust, search, tool-discovery, yaml
- Language: Rust
- Homepage: https://github.com/syshin0116/clidex
- Size: 171 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
CLI tool discovery for AI agents
Search, compare, and install 5,000+ command-line tools with structured YAML/JSON output.
---
## Quickstart
```bash
# Install
cargo install clidex # or: curl -fsSL https://raw.githubusercontent.com/syshin0116/clidex/main/install.sh | sh
# Search (auto-downloads index on first run)
clidex "csv to json" # Pretty output in terminal, YAML in pipes
clidex "csv to json" --json # JSON output
clidex info jq # Detailed tool info
clidex compare jq dasel yq # Side-by-side comparison
```
---
## Why Clidex?
AI agents like Claude Code, Codex, and Gemini CLI can run terminal commands — but they don't know which tools exist beyond the basics. An agent uses `grep` when `ripgrep` is 10x faster, or `find` when `fd` is simpler.
**Clidex bridges this gap.** It's a local CLI that returns structured metadata about CLI tools: what they do, how to install them, and where to find docs. No web search API calls, no HTML parsing, no cost — just a fast local lookup.
### What makes it different
| | awesome-cli-apps / cli-anything | Clidex |
|--|------|------|
| Target user | Humans | AI agents (+ humans) |
| Output | Markdown / TUI | YAML / JSON / Pretty |
| Install info | Links only | `brew install jq` — ready to run |
| Docs access | Click a link | `llms.txt` URL for agents to read |
| Pipeline | No | `clidex ... \| next_tool` (YAML in pipes) |
| Compare | No | `clidex compare jq dasel yq` |
---
## Installation
### With Cargo (all platforms)
```bash
cargo install clidex
```
### Pre-built binaries
**Linux / macOS:**
```bash
curl -fsSL https://raw.githubusercontent.com/syshin0116/clidex/main/install.sh | sh
```
**Windows:**
```bash
curl -fsSL -o clidex.zip https://github.com/syshin0116/clidex/releases/latest/download/clidex-x86_64-pc-windows-msvc.zip
tar -xf clidex.zip
move clidex.exe %USERPROFILE%\.local\bin\
```
Or download directly from [Releases](https://github.com/syshin0116/clidex/releases/latest).
> **Note:** In an interactive terminal, the index is downloaded automatically on first search. In non-interactive environments (CI, pipes), run `clidex update` first.
---
## Usage
### Search
```bash
clidex "csv to json" # Pretty in terminal, YAML in pipes
clidex "csv to json" --yaml # Force YAML output
clidex "csv to json" --json # JSON output
clidex "csv to json" --pretty # Force pretty output
clidex "file manager" -n 3 # Limit to top 3 results
clidex "json processor" --score # Include relevance scores
```
Search also works as an explicit subcommand:
```bash
clidex search "csv to json" --category data -n 5
```
Example output (terminal):
```
jq ★ 34.0k Data Manipulation > Processors [67.8]
JSON processor
$ brew install jq
dasel ★ 7.9k Data Manipulation > Processors [59.9]
JSON/YAML/TOML/XML processor (like jq/yq)
$ brew install dasel
```
### Tool info
```bash
clidex info ripgrep # Detailed tool metadata
clidex info ripgrpe # Typo → "Did you mean: ripgrep"
```
### Compare tools
```bash
clidex compare jq dasel yq # Side-by-side comparison
```
```
jq dasel yq
────────────────────────────── ────────────────────────────── ──────────────────
Description JSON processor JSON/YAML/TOML/XML processor… YAML processor
Category Processors Processors Processors
Stars ★ 30.8k ★ 5.3k ★ 2.6k
Install brew install jq brew install dasel brew install yq
```
### Trending
```bash
clidex trending # Top tools by GitHub stars
clidex trending -n 10 # Top 10
clidex trending --category git # Top Git tools
clidex trending --updated-since 2026-01-01 # Filter by repo activity date
```
### Categories
```bash
clidex categories # List all categories with tool counts
clidex categories git # Filter categories by name
clidex --category docker -n 5 # Browse tools in a category
```
### Index management
```bash
clidex update # Download/update index
clidex stats # Show index statistics
```
### Output format
| Flag | Format | When |
|------|--------|------|
| *(none, terminal)* | Pretty | Auto-detected when stdout is a TTY |
| *(none, pipe)* | YAML | Auto-detected when stdout is piped |
| `--pretty` | Pretty | Force human-friendly table |
| `--yaml` | YAML | Force structured YAML |
| `--json` | JSON | Force JSON |
| `--score` | + Score | Add relevance scores to results |
### Other flags
| Flag | Description |
|------|-------------|
| `-n ` | Max number of results (default: 10) |
---
## Agent integration
Clidex is built for AI agents to consume programmatically. The typical workflow:
1. Agent runs `clidex "task description"` (YAML output when piped)
2. Parses the structured result
3. Extracts `install.brew` or `install.cargo` command
4. Installs and uses the tool
### Output schema
Each tool in the result contains:
```yaml
name: string # Tool name
binary: string? # Binary name (if different from name)
desc: string # One-line description
category: string # Category path (e.g. "Files and Directories > Search")
tags: [string] # Search tags
install: # Install commands by package manager
brew: string?
cargo: string?
npm: string?
pipx: string?
stars: number? # GitHub stars
links:
repo: string? # GitHub repository
homepage: string? # Project homepage
docs: string? # Documentation URL
llms_txt: string? # llms.txt URL (LLM-readable docs)
```
With `--score`, search results use a wrapper schema: `{score: number, ...tool}`. Without `--score`, output is plain `[Tool]` — same schema as `info`/`compare`/`trending`.
The `llms_txt` field is especially useful — it points to [llms.txt](https://llmstxt.org/) files that agents can fetch to learn how to use a tool.
---
## How search works
Clidex uses **BM25** text search with domain-specific optimizations:
- **Field weighting**: Tool name (3x) > tags + category (2x) > description (1x)
- **Synonym expansion**: `grep` → also matches `search`, `find`, `ripgrep`, `rg` (30+ synonym groups)
- **Intent coverage**: Bonuses based on how many query terms appear in tool metadata
- **Category boost**: Query terms matching category names get boosted
- **Popularity boost**: GitHub stars or Homebrew install counts add 0–8 bonus points (tie-breaker, not primary signal)
- **Fuzzy matching**: Catches typos via edit distance (`ripgrpe` → `ripgrep`) and subsequence matching
- **Alias mapping**: `rg` → ripgrep, `btm` → bottom, `z` → zoxide (24 pairs)
- **Confidence gates**: Minimum lexical evidence required to prevent false positives from garbage queries
Search performance: **~3ms per query** on the full 5,000+ tool index (with cached BM25 engine).
---
## Data sources
| Source | What it provides |
|--------|-----------------|
| [awesome-cli-apps](https://github.com/agarrharr/awesome-cli-apps) | Curated tool list with categories |
| [toolleeo/cli-apps](https://github.com/toolleeo/cli-apps) | 2,200+ tools from CSV |
| [modern-unix](https://github.com/ibraheemdev/modern-unix) | Modern replacements for classic tools |
| [awesome-tuis](https://github.com/rothgar/awesome-tuis) | Terminal UI applications |
| [Homebrew](https://formulae.brew.sh/) | `brew install` commands, formulae + casks |
| [GitHub API](https://docs.github.com/en/rest) | Stars, last updated, homepage |
| [crates.io](https://crates.io/) | `cargo install` commands + category-based discovery |
| [npm](https://www.npmjs.com/) | `npm install -g` commands |
| [PyPI](https://pypi.org/) | `pipx install` commands for Python CLI tools |
| [Homebrew analytics](https://formulae.brew.sh/analytics/) | 365-day install counts |
| [llms.txt](https://llmstxt.org/) | LLM-readable documentation probing |
The index is rebuilt daily via GitHub Actions and published as a [release asset](https://github.com/syshin0116/clidex/releases/tag/index).
---
## Build index locally
```bash
cargo run --bin build_index -- index.yaml
```
### Environment variables
| Variable | Default | Description |
|----------|---------|-------------|
| `GITHUB_TOKEN` | — | GitHub API token (increases rate limit from 60 to 5000/hr) |
| `GITHUB_LIMIT` | `50` | Max GitHub API requests |
| `CRATES_LIMIT` | `100` | Max crates.io lookups |
| `NPM_LIMIT` | `50` | Max npm registry lookups |
| `LLMS_LIMIT` | `100` | Max llms.txt probes |
---
## Contributing
Contributions are welcome! Some areas that could use help:
- **Adding tools to the index**: Suggest popular CLI tools that are missing
- **Search quality**: Report queries that return unexpected results
- **New data sources**: Integrations with other package managers
- **Platform support**: Testing on different OS/architecture combinations
```bash
# Development
cargo build
cargo test
cargo clippy
cargo fmt
```
---
## License
[MIT](LICENSE)