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

> Explore the Service Discovery CLI for workers search and AIOS Registry integration. Learn to discover, inspect, and list workers efficiently using a cached registry with 5-minute TTL.

- Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/.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`.

```bash
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()`.

```bash
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()`.

```bash
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`](https://github.com/SynkraAI/aios-core/blob/main/service-registry.json) catalog.

### The Registry Loader ([`registry-loader.js`](https://github.com/SynkraAI/aios-core/blob/main/registry-loader.js))

The file [`.aios-core/core/registry/registry-loader.js`](https://github.com/SynkraAI/aios-core/blob/main/.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`.

```javascript
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`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/core/registry/service-registry.json) (generated by [`build-registry.js`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/build-registry.js))

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

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

```javascript
// 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:

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

```bash

# 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`](https://github.com/SynkraAI/aios-core/blob/main/docs/guides/service-discovery.md)** – User-facing documentation covering CLI commands, registry API, and usage examples.
- **[`.aios-core/core/registry/registry-loader.js`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/core/registry/build-registry.js)** – Scans the repository for workers and generates the [`service-registry.json`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/core/registry/build-registry.js), which scans the codebase to generate [`service-registry.json`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/service-registry.json) file, produced by [`.aios-core/core/registry/build-registry.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/core/registry/build-registry.js). At runtime, [`.aios-core/core/registry/registry-loader.js`](https://github.com/SynkraAI/aios-core/blob/main/.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.