Skip to main content

atmos plugin search

Search cached plugin metadata from OCI repositories and optional catalogs.
Experimental
atmos plugin search --help

Usage​

atmos plugin search [query] [--registry <alias>] [--refresh]

Arguments and flags​

query
Case-insensitive package name or description text.
--registry
Search only this configured registry alias, including its repositories and optional catalog.
--capability
Filter by an exported capability, such as auth.provider.
--runtime
Filter by runtime, such as native.
--refresh
Revalidate discovery sources even when the local cache is fresh. Fails when offline policy is enabled.
--format
Output format: table (default), json, yaml, csv, or tsv. Set ATMOS_PLUGIN_FORMAT to change the default; an explicit flag takes precedence.

Interactive table output uses the shared Atmos list styling. When piped, table output becomes plain tab-separated rows. JSON and YAML retain complete discovery entries, including available versions and capabilities. Each result identifies its configured registry alias.

Discovery sources and freshness​

A small collection can list repositories directly; a public or curated collection can publish a catalog snapshot. Both use the same search and installation commands:

plugins:
  max_concurrency: 4
  discovery:
    cache_ttl: 15m
  registries:
    team:
      host: registry.example.com
      repositories:
        - oci://registry.example.com/team/oidc
        - oci://registry.example.com/team/credentials
    infrastructure:
      catalog: oci://ghcr.io/acme/infrastructure/catalog:stable
    developer-tools:
      catalog: oci://ghcr.io/acme/developer-tools/catalog:stable

Direct discovery reads tags and static release metadata from the explicitly listed repositories. It does not enumerate the registry, download executable payloads, or run plugins. Refreshes reuse metadata for unchanged release digests. Source requests use the plugins.max_concurrency limit.

The cache defaults to fifteen minutes of freshness. Set plugins.discovery.cache_ttl to a nonnegative Go duration, such as 30m or 1h; 0 revalidates every online search. --refresh bypasses freshness. Offline policy (plugins.policy.offline: true) permits stale cached discovery, but a missing or corrupt cache fails. Online refresh errors are reported rather than silently returning stale results.

Discovery metadata lives under XDG cache atmos/plugins/discovery, or <plugins.cache_dir>/discovery when overridden. Its scope includes source configuration, auth configuration, and realm; it contains no tokens. Source policy is checked even for cached results. Cached search metadata never replaces installation signature, policy, compatibility, or integrity checks.

Examples​

atmos plugin search oidc --capability=auth.provider
atmos plugin search oidc --format=json
atmos plugin search --registry=team --refresh
atmos plugin install team/acme/oidc --as=corporate --version="^1.0"