HTTP reference
CLI Finder Registry API
Search CLI tools, read evidence, and generate agent-ready artifacts through unauthenticated, read-only JSON endpoints.
Quick Request
The base URL is https://clifinder.net. Every public registry endpoint accepts GET or OPTIONS and requires no API key.
curl --get 'https://clifinder.net/api/registry/tools' \
--data-urlencode 'q=review pull requests' \
--data-urlencode 'agent=codex' \
--data-urlencode 'environment=headless' \
--data-urlencode 'maxRisk=R1' \
--data-urlencode 'output=json' \
--data-urlencode 'limit=5'Success response envelope
Public /api/registry/* endpoints return { code: 0, message: "ok", data: ... }. Clients should check code and data rather than treating HTTP 200 alone as the complete success condition.
Endpoints
Search returns match reasons with complete tool objects, detail returns one complete tool, and artifact generation returns a filename, media type, and textual content.
Search Parameters
Each parameter may appear once. agent, environment, risk, category, and evidence accept comma-separated values; maxRisk accepts one value; unknown parameters return HTTP 400.
| Parameter | Values | Meaning |
|---|---|---|
| q | string ≤ 200 | Task, tool name, or capability phrase; omit it to browse all tools through filters. |
| agent | claude-code, codex, gemini-cli, copilot-cli | Filter by explicitly recorded agent compatibility; comma-separated values are accepted. All four agents can invoke a shell, so compatibility must not be read as executed verification. |
| environment | local, ci, container, headless, remote | Filter by explicitly recorded runtime environment. An absent environment means the registry does not claim compatibility, not that execution is impossible. |
| risk | R0, R1, R2, R3 | Match tools with commands at the requested risk level; risk is a command-level signal. |
| maxRisk | R0, R1, R2, R3 | Return only tools whose maximumLevel does not exceed this value. It matches the website maximum-risk filter and accepts one value. |
| output | format string | Match a recorded output format such as json, yaml, or csv; comma-separated values are accepted. |
| category | code-collaboration, deployment-cloud, containers-kubernetes, databases, data-text, http-webhooks, web-automation, security, operations-infrastructure | Filter by registry category slug; comma-separated values are accepted. |
| evidence | verified, docs-verified, maintainer-submitted, community-reported, unverified | Filter by evidence confidence, which is separate from readiness and low risk. |
| limit | 1–100; default 20 | Limit the number of returned items; total still reports every match. |
Artifact Types
A type is required for /api/registry/artifacts/:slug. mode accepts read-only, standard, or advanced; agent accepts claude-code, codex, gemini-cli, or copilot-cli.
| type | Filename | Purpose |
|---|---|---|
| skill-md | SKILL.md | An agent-facing tool skill. |
| agents-md | AGENTS.md | Agent instructions that can be incorporated into a repository. |
| claude-md | CLAUDE.md | A Claude Code instruction fragment that can be incorporated into CLAUDE.md. |
| claude-policy | claude-settings.json | A command policy for an agent or shell. |
| codex-policy | codex-policy.rules | A command policy for an agent or shell. |
| gemini-policy | gemini-policy.toml | A command policy for an agent or shell. |
| shell-allowlist | shell-allowlist.txt | A command policy for an agent or shell. |
| manifest-json | clifinder.json | A machine-readable manifest for one tool. |
| manifest-yaml | clifinder.yaml | A machine-readable manifest for one tool. |
| manifest-schema | clifinder.schema.json | An independent JSON Schema for validating a single-tool manifest. |
| dockerfile | Dockerfile | A runtime file for an automation project. |
| github-actions | clifinder.yml | A runtime file for an automation project. |
Policy type constraints
claude-policy supports agent=claude-code, codex-policy supports agent=codex, and gemini-policy supports agent=gemini-cli. If agent is omitted, the service infers it from the policy type; conflicting combinations return HTTP 400.
Safety mode boundaries
read-only keeps R0 and forbids R1-R3; standard prompts for R1 by default and forbids R2-R3; advanced may expand R2 to explicit approval while still forbidding R3. Only an individually audited R0/R1 prefix marked suffix-safe can be auto-allowed; every other available prefix prompts.
Responses, Errors, and Caching
API errors use an HTTP status with code=-1 and are never cached. Preserve message for diagnostics, but do not branch on its text.
Success example
{
"code": 0,
"message": "ok",
"data": {
"query": "review pull requests",
"filters": { "agent": "codex", "maxRisk": "R1" },
"items": [],
"total": 0,
"limit": 5
}
}Error example
{
"code": -1,
"message": "Limit must be an integer between 1 and 100"
}| Status | Scenario | Handling |
|---|---|---|
| 200 | code=0 | The request succeeded; read data. An empty search also returns 200 with empty items. |
| 204 | OPTIONS | A successful CORS preflight with no body. |
| 400 | code=-1 | Missing type, unknown or duplicate parameter, invalid enum, limit, or slug. |
| 404 | code=-1 | The slug format is valid, but the tool is absent from the registry. |
CORS
Access-Control-Allow-Origin is *, GET and OPTIONS are allowed, and a preflight can be cached for 86400 seconds.
Cache policy
API: 60 seconds in browsers, 300 seconds in shared caches, and 86400 seconds stale-while-revalidate. registry.json: 300 seconds in browsers and 3600 in shared caches. Errors are no-store.