Skip to main content
A Tool does not have to live in Firedrill’s repository. Its author can maintain it in any repository, publish an npm package, or share a Git revision directly. Adding it to the bundled catalog is optional. Discovery is metadata lookup—not installation, code execution, or a security endorsement.

​
Search a catalog

Without an index option, search reads only the catalog shipped with your CLI:
An author, team, or community can share its own index:
Search results include the package name, exact version, declared operations, limits, metadata origin, and an installSource to pass to tool add explicitly. Searching an index never installs or activates its entries. Installing a Tool does not prove its behavior matches a real service; read the source and run its conformance checks before trusting it. Pagination uses offset and limit (default 25, maximum 100). total counts matching active entries. Deprecated and revoked entries are not offered for installation. Search matches the title, package name, description, Tool ID, operation IDs, and keywords, preserving the index’s order. Tool selection searches the full index, not only the displayed page. If the same name or Tool ID has multiple active versions, select an exact name@version or the result’s installSource; Firedrill does not silently pick the last entry.

​
Publish an index

The same version-1 shape is used by the bundled catalog and external indexes. A minimal entry looks like this:
packageVersion is an exact version, never latest, *, or a range. Omitted source means npm distribution. Git-backed entries add an explicit immutable source; subdirectory is optional:
Put that object in the entry’s source field. The full Git revision and subdirectory become the installation selector. Git metadata must still declare the package’s name and exact version, so users can identify it independently of where it is stored. An index cannot substitute a mutable branch for a revision. The public Draft 2020-12 JSON Schema ships at @firedrill/cli/schema/tool-index.json. The matching runtime validator and reader are exported from @firedrill/cli/tool-discovery:
No central registration, Firedrill login, or contribution agreement is required. Package licensing and redistribution remain the author’s responsibility.

​
What is verified

Every index is parsed and validated before results appear. Duplicate package name/version entries and duplicate operation IDs are rejected rather than silently merged. The runtime validator enforces these cross-entry checks in addition to the exported JSON Schema’s structural checks. When the same package name, exact version, and Tool ID are installed locally, discovery reads its declaration without importing its behavior. Operation and limitation metadata then comes from that declaration and is labeled installed-declaration. Otherwise it is labeled publisher. Titles and descriptions always come from the index. Neither label means independent provider-parity verification, signature verification, or safe executable code. The installed check does not establish that a package came from the index’s Git URL; installation provenance and locked build identity are separate checks. Indexes are limited to 2 MiB and 1,000 entries. Remote requests require HTTPS (HTTP is allowed for loopback development), finish within 10 seconds, and never follow redirects or send authentication. Index URLs cannot contain credentials, queries, or fragments. For a private authenticated index, download it through your existing authenticated tooling and pass the local JSON file. Cancellation is supported through the programmatic reader’s signal. The CLI has no background registry lookups. Installed Tools continue working without access to an index.