Federation CLI reference

View as Markdown

---

EventCatalog Enterprise Feature

Run Federation from the central catalog directory:

npx eventcatalog federate

The command loads federation.sources and federation.rules from eventcatalog.config.js.

Requirements

• A central EventCatalog project
• An EventCatalog Enterprise license key
• At least one configured source, unless you are cleaning previous output
• Git for GitHub sources that do not publish an index
• Network and repository access for GitHub sources

Options

Option	Description	Default
--no-cache	Disable content cache reads for this run and refresh fetched entries.	Reuse valid cached content
--verbose, -v	Show the attributes for warning diagnostics. Error attributes are always shown.	Concise warning summary
--help, -h	Show command help.

Examples

Run Federation:

npx eventcatalog federate

Show every warning:

npx eventcatalog federate --verbose

Refresh content without reading existing cache entries:

npx eventcatalog federate --no-cache

Pass options through an npm script:

npm run federate -- --verbose

Select local sources through a configuration environment variable:

EVENTCATALOG_FEDERATION_LOCAL=true npx eventcatalog federate

EVENTCATALOG_FEDERATION_LOCAL is not a built-in Federation variable. It is an example of using your own environment variable inside eventcatalog.config.js.

Environment variables

Variable	Description
EVENTCATALOG_SCALE_LICENSE_KEY	License key used to enable Federation.
EVENTCATALOG_GITHUB_TOKEN	Preferred GitHub token for private repositories and authenticated content requests.
GITHUB_TOKEN	GitHub token fallback when EVENTCATALOG_GITHUB_TOKEN is not set.

The command loads variables from .env in the central catalog before Federation starts.

Command stages

The command reports progress for:

1. Configured source discovery
2. Source fetching and indexing
3. Central catalog ownership indexing
4. Graph resolution and diagnostics
5. Content hydration and cache reuse
6. Public asset composition
7. Lockfile recording

Warning and error output

Without --verbose, warnings produce a summary and a hint to rerun with verbose output.

With --verbose, each diagnostic includes:

• Severity
• Human-readable message
• Stable federation/* rule ID
• Rule-specific attributes

Errors always include their details and stop before new generated output is installed.

No configured sources

When no sources are configured and no previous Federation state exists, the command reports that there is nothing to do.

When previous output exists, running with an empty source list removes the previous federated/ output, managed public files, and lockfile.

Generated files

A successful run can update:

• federated/
• public/ for managed remote public assets
• .eventcatalog-cache/federation/content/
• eventcatalog.lock

See Generated output reference.