CLI tool discovery for AI agents

Search, compare, and install 5,309+ command-line tools with structured YAML/JSON output.

---

Quickstart

# 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 "json processor"         # Pretty output in terminal, YAML in pipes
clidex "json processor" --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, and no cost. It is 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)

cargo install clidex

Pre-built binaries

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/syshin0116/clidex/main/install.sh | sh

Windows:

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.

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

clidex "json processor"             # Pretty in terminal, YAML in pipes
clidex "json processor" --yaml      # Force YAML output
clidex "json processor" --json      # JSON output
clidex "json processor" --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:

clidex search "json processor" --category data -n 5

Example output (terminal):

  jq                ★ 34.0k  Data Manipulation > Processors [68.7]
  JSON processor
  $ brew install jq

  dasel              ★ 7.9k  Data Manipulation > Processors [60.7]
  JSON/YAML/TOML/XML processor (like jq/yq)
  $ brew install dasel

Tool info

clidex info ripgrep               # Detailed tool metadata
clidex info ripgrpe               # Typo → "Did you mean: ripgrep"

Compare tools

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

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

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

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 <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:

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], the same schema as info/compare/trending.

The llms_txt field is especially useful because it points to llms.txt files that agents can fetch to learn how to use a tool.

See agent integration examples for a safe subprocess workflow and reusable Codex or Claude Code instructions.

---

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 to 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,309+ tool index (with cached BM25 engine).

---

Data sources

Source	What it provides
awesome-cli-apps	Curated tool list with categories
toolleeo/cli-apps	2,200+ tools from CSV
modern-unix	Modern replacements for classic tools
awesome-tuis	Terminal UI applications
Homebrew	brew install commands, formulae + casks
GitHub API	Stars, last updated, homepage
crates.io	cargo install commands + category-based discovery
npm	npm install -g commands
PyPI	pipx install commands for Python CLI tools
Homebrew analytics	365-day install counts
llms.txt	LLM-readable documentation probing

The index is rebuilt daily via GitHub Actions and published as a release asset.

---

Build index locally

cargo run --bin build_index -- index.yaml

Environment variables

Variable	Default	Description
GITHUB_TOKEN	unset	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

# Development
cargo build
cargo test
cargo clippy
cargo fmt

Read CONTRIBUTING.md before opening a pull request. Use the search quality issue form for missing or poorly ranked results. Report suspected vulnerabilities according to SECURITY.md.

---

License

MIT