@eventcatalog/cli

Command-line interface for EventCatalog. Import and export catalogs using the EventCatalog DSL, run SDK functions directly from your terminal, and automate your EventCatalog workflows.

Installation

npm i @eventcatalog/cli

Running with npx (no installation required)

npx @eventcatalog/cli --dir <catalog-path> <command> [args...]

Running after installation

If you've installed the package, the eventcatalog command is available:

eventcatalog --dir <catalog-path> <command> [args...]

Global Options

| Option | Description | Default | | ------------------ | ------------------------------ | ----------------------- | | -d, --dir <path> | Path to your catalog directory | . (current directory) |

Commands

import — Import DSL files into your catalog

Parse .ec (EventCatalog DSL) files and write them as catalog resources (markdown + frontmatter).

eventcatalog import [files...] [options]

Options:

| Option | Description | | ----------- | ------------------------------------------------------------ | | --stdin | Read DSL from stdin instead of files | | --dry-run | Preview changes without writing to disk | | --flat | Write all resources at the top level (no nested directories) | | --no-init | Skip the interactive catalog scaffolding prompt |

Examples:

# Import a single DSL file
eventcatalog import architecture.ec

# Import multiple files
eventcatalog import services.ec events.ec domains.ec

# Pipe DSL from another tool
cat architecture.ec | eventcatalog import --stdin

# Preview what would change
eventcatalog import architecture.ec --dry-run

# Import without nesting services inside domains
eventcatalog import architecture.ec --flat

Behaviors:

• If no eventcatalog.config.js exists, you'll be prompted to scaffold a new catalog (skip with --no-init).
• Importing a newer version of an existing resource automatically versions the old one.
• Re-importing the same version overwrites the existing resource.
• Referenced resources that aren't defined in the DSL (e.g., sends event OrderCreated without an inline body) are created as stubs at version 0.0.1.
• Existing resource locations are preserved — updates go to where the resource already lives.

export — Export catalog resources to DSL

Convert catalog resources back into EventCatalog DSL (.ec) format.

eventcatalog export [options]

Options:

| Option | Description | | --------------------- | ----------------------------------------------------------------------------------------- | | --all | Export the entire catalog | | --resource <type> | Resource type to export (event, command, query, service, domain, channel) | | --id <id> | Export a specific resource by ID (requires --resource) | | --version <version> | Export a specific version (requires --resource and --id) | | --hydrate | Include referenced resources (e.g., messages referenced by a service) | | --stdout | Print to stdout instead of writing a file | | --playground | Open the exported DSL in the EventCatalog Playground | | --output <path> | Custom output file path |

Examples:

# Export a single event
eventcatalog export --resource event --id OrderCreated --stdout

# Export all services with their referenced messages
eventcatalog export --resource service --hydrate --stdout

# Export the entire catalog to a file
eventcatalog export --all --output catalog.ec

# Export and open in the playground
eventcatalog export --all --playground

list — List available SDK functions

Display all SDK functions organized by category (Events, Commands, Queries, Services, Domains, etc.).

eventcatalog list

<function> — Run any SDK function

Any unrecognized command is treated as an SDK function call. Output is JSON.

eventcatalog <function-name> [args...]

Examples:

# Get an event (latest version)
eventcatalog --dir ./my-catalog getEvent "OrderCreated"

# Get a specific version
eventcatalog --dir ./my-catalog getEvent "OrderCreated" "1.0.0"

# Get all events with options
eventcatalog --dir ./my-catalog getEvents '{"latestOnly":true}'

# Write an event
eventcatalog --dir ./my-catalog writeEvent '{"id":"OrderCreated","name":"Order Created","version":"1.0.0","markdown":"# Order Created"}'

# Get a service
eventcatalog --dir ./my-catalog getService "InventoryService"

# Add an event to a service
eventcatalog --dir ./my-catalog addEventToService "InventoryService" "sends" '{"id":"OrderCreated","version":"1.0.0"}'

Run eventcatalog list to see all available functions.

Piping and Composing

Output from SDK functions is JSON, making it easy to pipe to tools like jq:

# Filter events by version
eventcatalog --dir ./my-catalog getEvents | jq '.[] | select(.version == "1.0.0")'

# Count total events
eventcatalog --dir ./my-catalog getEvents | jq 'length'

# Extract event IDs
eventcatalog --dir ./my-catalog getEvents | jq '.[].id'

Arguments Format

Arguments are automatically parsed:

• JSON objects: '{"key":"value"}' — parsed as object
• JSON arrays: '["item1","item2"]' — parsed as array
• Booleans: true or false — parsed as boolean
• Numbers: 42 or 3.14 — parsed as number
• Strings: anything else — kept as string

Documentation

• EventCatalog DSL
• SDK reference
• CLI documentation

Enterprise support

Interested in collaborating with us? Our offerings include dedicated support, priority assistance, feature development, custom integrations, and more.

Find more details on our services page.