Command-line reference

CLI Finder Command-Line Tool

Search the registry, inspect tools, and write skills, agent policies, or JSON manifests to stdout from a terminal.

Run from a Repository Checkout

The CLI uses Node.js 18.17 or newer and has no runtime dependencies. packages/cli is currently private and has not been published to npm.

Use npm exec

shell

git clone https://github.com/chaoshipit/clifinder-net.git
cd clifinder-net
npm exec --package ./packages/cli -- clifinder help

Run with Node.js directly

shell

git clone https://github.com/chaoshipit/clifinder-net.git
cd clifinder-net
node packages/cli/bin/clifinder.mjs help

Do not assume a public npm package

Do not currently run npm install -g clifinder or npx clifinder. The npm exec --package ./packages/cli form above uses the local repository directory and does not claim or depend on a published npm package.

Search and Inspect

Human-readable output is the default. Add --json to any command for parseable JSON. A search with no matches exits with code 3.

search

Search with a natural-language task and apply agent, environment, risk, output, category, evidence, or limit filters. A task can span multiple positional arguments.

shell

npm exec --package ./packages/cli -- clifinder search \
  "review pull requests" \
  --agent codex \
  --environment headless \
  --risk R0 \
  --output json \
  --limit 5

inspect

Read one tool by slug. Terminal output includes its command, publisher, readiness, risk, evidence, output, and recommended installation.

shell

npm exec --package ./packages/cli -- clifinder inspect github-cli

npm exec --package ./packages/cli -- clifinder inspect github-cli --json \
  | jq '{slug, readiness: .readiness.score, risk: .operationalRisk.defaultLevel}'

Search option	Values	Meaning
--agent	claude \| codex \| gemini \| copilot	Canonical names such as claude-code, gemini-cli, and copilot-cli are also accepted.
--environment	local \| ci \| container \| headless \| remote	The runtime-environment filter sent to the registry API.
--risk	R0 \| R1 \| R2 \| R3	The CLI uppercases the value before the API validates it.
--output	format	For example json, yaml, or csv.
--category	category slug	For example code-collaboration or data-text.
--evidence	confidence	For example verified or docs-verified.
--limit	1–100	The CLI validates the integer range before the request.
--json	flag	Print the registry data object rather than the HTTP code/message/data envelope.

Generate Skills, Policies, and Manifests

skill and policy require --agent, and mode defaults to read-only. Generated content is written to stdout, so shell redirection can save it.

skill

shell

npm exec --package ./packages/cli -- clifinder skill github-cli \
  --agent codex --mode read-only > SKILL.md

policy

shell

npm exec --package ./packages/cli -- clifinder policy github-cli \
  --agent claude --mode standard > claude-settings.json

json

shell

npm exec --package ./packages/cli -- clifinder json github-cli \
  > github-cli.clifinder.json

Command	Usage	Output
skill	skill <slug> --agent <agent> [--mode <mode>]	Writes SKILL.md content to stdout by default; --json prints the artifact data object.
policy	policy <slug> --agent <agent> [--mode <mode>]	Claude, Codex, and Gemini receive native policies; Copilot receives AGENTS.md.
json	json <slug>	Parses and formats the one-tool JSON manifest by default; --json prints the artifact data object containing content.
--mode	read-only \| standard \| advanced	The generated policy posture; read-only is the default.

Help, Version, and API Origin

help prints the overview or one command usage. version, --version, and -v print the CLI version. CLIFINDER_API_URL can point the client at local or alternate deployments.

shell

node packages/cli/bin/clifinder.mjs help
node packages/cli/bin/clifinder.mjs help search
node packages/cli/bin/clifinder.mjs version
node packages/cli/bin/clifinder.mjs --version --json

shell

CLIFINDER_API_URL=http://localhost:3000 \
  node packages/cli/bin/clifinder.mjs search "parse yaml" --json

CLIFINDER_API_URL

The default is https://clifinder.net. The value must be a valid http or https URL; the CLI removes trailing slashes and appends /api/registry/.... Network requests time out after 15 seconds and follow redirects.

Stable Exit Codes

Scripts should branch on exit codes rather than parsing human-readable error text. Errors go to stderr and successful content goes to stdout.

Exit code	Meaning	Suggested handling
0	Success	The command completed; consume stdout.
2	Usage error	A command, option, or positional argument is missing or unknown, or the agent, mode, limit, or API URL is invalid.
3	Not found	A search has no matches or the registry API returns 404 for a tool.
4	Network failure	Connection failure, DNS error, or the 15-second timeout; retry according to your policy.
5	API or response error	A rejected filter value, another non-404 API error, non-JSON response, missing data, or invalid artifact response.

shell

if node packages/cli/bin/clifinder.mjs inspect github-cli --json > tool.json; then
  jq '.readiness.score' tool.json
else
  status=$?
  echo "clifinder failed with exit code $status" >&2
  exit "$status"
fi

Related Machine Interfaces

Full Registry API reference /api/registry/tools?limit=5 /registry.json