Service Discovery CLI for Workers Search: Complete Guide to AIOS Registry Integration

The Service Discovery CLI provides three commands (aios discover, aios info, aios list) to search and inspect workers in the AIOS Service Registry, leveraging a cached Registry class from registry-loader.js with a 5-minute TTL.

The Service Discovery CLI for workers search is a core component of the SynkraAI/aios-core framework, enabling developers to locate tasks, templates, scripts, and workflows registered in the centralized Service Registry. This system bridges command-line usability with programmatic registry integration through a lazy-loaded, cached architecture that ensures high-performance worker discovery.

Core CLI Commands for Worker Discovery

The CLI exposes three primary commands that wrap the underlying registry API. These commands reside in the entry point at bin/aios and delegate to the Registry class defined in .aios-core/core/registry/registry-loader.js.

aios discover: Full-Text Registry Search

The aios discover command performs full-text or filtered searches across all registered workers. It accepts a search term and optional flags for --category, --tag, and --agent.

aios discover "create story" --category task --agent dev

Internally, this invokes registry.search(term, options) with O(1) indexed lookups for tags and categories.

aios info: Detailed Worker Metadata

The aios info command retrieves comprehensive metadata for a specific worker by its ID. This maps directly to registry.getById(id) and registry.getInfo().

aios info create-story

Output includes the worker's path, tags, supported agents, input schema, and documentation links.

aios list: Category and Agent Filtering

The aios list command enumerates workers by category or agent, utilizing registry.getByCategory() and registry.getForAgent().

aios list tasks --agent dev

This supports pagination and sorting via the underlying Registry API.

Registry Integration Architecture

The CLI commands are thin wrappers around the registry loader, which manages the lifecycle of the service-registry.json catalog.

The Registry Loader (registry-loader.js)

The file .aios-core/core/registry/registry-loader.js exports two primary functions:

• loadRegistry() – Loads the registry data once and returns the raw JSON payload.
• getRegistry() – Returns a singleton Registry instance with methods including getById, getByCategory, getByTag, getForAgent, search, getInfo, getCategories, getTags, count, clearCache, and isCached.

const { getRegistry } = require('./.aios-core/core/registry/registry-loader');

const registry = getRegistry(); // Singleton instance
const worker = registry.getById('create-story');

Lazy Loading and Caching Mechanism

The registry implements a lazy-loading pattern with a 5-minute TTL (time-to-live) cache:

1. Bootstrap: The first call to getRegistry() instantiates the Registry class.
2. Lazy Load: The first query triggers registry.load(), which reads .aios-core/core/registry/service-registry.json (generated by build-registry.js).
3. Indexing: The loader creates O(1) lookup indexes for IDs, categories, tags, and agents.
4. Cache TTL: Results remain cached for 5 minutes; subsequent calls return cached data unless registry.load(true) is invoked to force a refresh.

Registry Build Process (build-registry.js)

The file .aios-core/core/registry/build-registry.js scans the repository for workers (tasks, templates, scripts, workflows) and generates the service-registry.json catalog. This build step must run before the CLI can discover workers, typically during installation or CI/CD pipelines.

node .aios-core/core/registry/build-registry.js

Programmatic Usage Examples

Beyond CLI usage, the registry loader enables direct JavaScript integration for custom tooling and automation.

Search Workers from a Node Script

The following example demonstrates how to search workers programmatically using the search method with category and agent filters:

// src/search-workers.js
const { getRegistry } = require('./.aios-core/core/registry/registry-loader');

async function searchWorkers(term, opts = {}) {
  const registry = getRegistry();          // singleton, may trigger lazy load
  const results = await registry.search(term, {
    category: opts.category,               // e.g. 'task'
    tag: opts.tag,                         // e.g. 'testing'
    agent: opts.agent,                     // e.g. 'dev'
    maxResults: opts.maxResults ?? 10,
  });
  return results;
}

// Example usage
searchWorkers('create story', { category: 'task', agent: 'dev' })
  .then(console.log)
  .catch(console.error);

Run a CLI-Like Discover Command from Code

To replicate CLI behavior within an application, invoke the registry methods directly and format the output:

const { getRegistry } = require('./.aios-core/core/registry/registry-loader');

async function cliDiscover(args) {
  const registry = getRegistry();
  const results = await registry.search(args.query, {
    category: args.category,
    tag: args.tag,
    agent: args.agent,
    maxResults: args.max ?? 20,
  });
  // Simple console formatting (mirrors `aios discover` output)
  console.log(`Found ${results.length} workers matching "${args.query}":`);
  results.forEach(w => {
    console.log(`  [${w.category}] ${w.id}\n       Path: ${w.path}\n       Tags: ${w.tags.join(', ')}\n       Agents: ${w.agents.join(', ')}`);
  });
}

// Run with demo arguments
cliDiscover({ query: 'create story', category: 'task', tag: 'development', agent: 'dev' });

Force a Registry Refresh in CI Pipelines

When running in automated environments, bypass the cache to ensure the latest workers are available:

# Rebuild the JSON catalog

node .aios-core/core/registry/build-registry.js

# Or programmatically bypass the cache

node -e "
  const { getRegistry } = require('./.aios-core/core/registry/registry-loader');
  (async () => {
    const reg = getRegistry();
    await reg.load(true);   // true => force reload
    console.log('Registry refreshed, total workers:', (await reg.getInfo()).totalWorkers);
  })();
"

Key Implementation Files

The Service Discovery CLI and its registry integration rely on the following components:

• docs/guides/service-discovery.md – User-facing documentation covering CLI commands, registry API, and usage examples.
• .aios-core/core/registry/registry-loader.js – Implements lazy loading, singleton pattern, caching (5-minute TTL), and the Registry class with methods like search, getById, and getForAgent.
• .aios-core/core/registry/build-registry.js – Scans the repository for workers and generates the service-registry.json catalog consumed by the loader.
• bin/aios – CLI entry point that maps discover, info, and list commands to registry-loader methods and formats human-readable output.
• service-registry.json (generated) – Persistent JSON catalog containing all worker metadata, indexed for O(1) lookups.

Summary

• The Service Discovery CLI exposes three commands (aios discover, aios info, aios list) to search and inspect workers in the AIOS Service Registry.
• Registry integration relies on .aios-core/core/registry/registry-loader.js, which provides a singleton Registry class with O(1) lookup methods and a 5-minute TTL cache.
• The registry is built by .aios-core/core/registry/build-registry.js, which scans the codebase to generate service-registry.json.
• Developers can use the registry API programmatically via getRegistry() for custom tooling, CI pipelines, or automation scripts.

Frequently Asked Questions

How do I force the Service Discovery CLI to refresh its worker cache?

You can force a refresh by running node .aios-core/core/registry/build-registry.js to rebuild the service-registry.json catalog, or programmatically call await registry.load(true) where true bypasses the cache. The registry loader in .aios-core/core/registry/registry-loader.js manages a 5-minute TTL by default.

What is the difference between aios discover and aios list?

The aios discover command performs full-text searches across worker metadata using registry.search(), supporting fuzzy matching and filters like --category or --tag. In contrast, aios list enumerates workers by specific dimensions using registry.getByCategory() or registry.getForAgent(), making it ideal for browsing rather than searching.

Can I use the Service Discovery features programmatically without the CLI?

Yes, the registry API is fully accessible via JavaScript by importing getRegistry from .aios-core/core/registry/registry-loader.js. This returns a singleton Registry instance with methods like search, getById, getInfo, and clearCache, enabling you to build custom tooling, automation scripts, or CI integrations without invoking shell commands.

Where is the worker metadata stored and how is it indexed?

Worker metadata is stored in the generated service-registry.json file, produced by .aios-core/core/registry/build-registry.js. At runtime, .aios-core/core/registry/registry-loader.js loads this JSON and creates in-memory indexes for O(1) lookups by ID, category, tag, and agent, with results cached for 5 minutes to optimize performance.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}