@mmmnt/cli

Command-line interface for the Moment domain specification language and implementation toolchain.

Overview

@mmmnt/cli provides the moment command, which is the primary way most developers interact with the Moment toolchain. It wraps every package in the @mmmnt ecosystem behind a consistent, discoverable command-line interface with 20+ commands covering the full specification-to-implementation workflow.

From initializing a new project to parsing specifications, deriving test topologies, generating TypeScript code and BDD scenarios, running conformance tests, detecting implementation drift, and managing schema lifecycles -- every operation is available as a single CLI command. The CLI handles file I/O, output formatting, error reporting, and watch mode so that the underlying library packages remain focused on their core logic.

The CLI is designed for both interactive development and CI/CD pipeline integration. All commands produce structured output suitable for scripting, and exit codes follow standard conventions for use in automated workflows. Many commands support the --json flag for machine-readable output; see the Common Options table below for details.

Installation

# Install globally
npm install -g @mmmnt/cli

# Or run directly without installing
npx @mmmnt/cli

# Or install as a project dev dependency
npm install --save-dev @mmmnt/cli

Or with other package managers:

pnpm add -g @mmmnt/cli
yarn global add @mmmnt/cli

Quick Start

# Initialize a new Moment project
moment init --name my-service

# Parse and validate a .moment specification
moment parse specs/my-service.moment

# Derive test topologies and scenarios
moment derive specs/my-service.moment

# Generate TypeScript types and test scaffolds
moment emit-ts specs/my-service.moment

# Generate Gherkin BDD scenarios
moment generate specs/my-service.moment

# Run specification conformance tests
moment test specs/my-service.moment

# Watch for spec changes and regenerate automatically
moment watch specs/

Key Features

• Unified entry point -- a single moment binary that wraps all @mmmnt packages, so you do not need to import or configure individual libraries.
• 20+ commands -- covers the full lifecycle from project initialization through specification, derivation, generation, testing, synchronization, and governance.
• Watch mode -- monitors .moment files and automatically re-parses and regenerates artifacts on save.
• Structured output -- most commands support --json for machine-readable output in CI/CD pipelines.
• Standard exit codes -- non-zero exit on validation failures, drift detection, or test failures for pipeline gating.
• Subcommand structure -- complex operations like sync and schema use subcommands (sync status, sync propose, sync accept, schema status) for organized workflows.
• Authentication support -- moment auth subcommands manage credentials for Moment cloud services when applicable.
• Verbose mode -- moment status --verbose enables detailed logging for the unified status command.

Commands

Project Initialization

| Command | Description | |---------|-------------| | moment init --name <name> | Initialize a new Moment project with .manifest.yaml, .moment/contexts/, and .moment/flows/ directories. Optionally specify --dir <path> for the target directory (defaults to .). |

Specification

| Command | Description | |---------|-------------| | moment parse <file> | Parse and validate a .moment specification file. Reports syntax errors and semantic diagnostics with line numbers and column positions. | | moment watch <dir> | Watch a directory for .moment file changes and automatically re-parse and regenerate artifacts. Runs until interrupted. |

Derivation

| Command | Description | |---------|-------------| | moment derive <file> | Derive test topologies, simulation scenarios, event catalogs, impact analysis, and saga state machines from a specification. | | moment simulate <file> | Run simulation scenarios against the specification and report event flow traces. Supports --all to generate all branch combinations plus negative (precondition violation) scenarios, and --out-dir <path> to write per-flow topology files, individual scenario files, manifest.json, and ADR-029 artifacts (event-catalog.json, impact-analysis.json, saga-state-machines.json, asyncapi.yaml). |

Code Generation

| Command | Description | |---------|-------------| | moment cucumber-json <file> | Output Cucumber JSON to stdout for Xray import. Useful for integrating Moment-derived scenarios into Jira/Xray test management workflows. | | moment emit-ts <file> | Generate TypeScript interfaces, aggregate root classes, discriminated event union types, and test scaffold files from the specification. | | moment generate <file> | Generate Gherkin .feature files, a specification.md document with Mermaid diagrams, and an asyncapi.yaml specification. |

Testing

| Command | Description | |---------|-------------| | moment test <file> | Execute derived tests against your domain implementation and report conformance results. Non-zero exit code on failures. |

Visualization

| Command | Description | |---------|-------------| | moment viz <file> | Generate visualization data (context maps, flow timelines) as a JSON VizDataEnvelope. Output can be piped to files or visualization tools. |

Synchronization

| Command | Description | |---------|-------------| | moment sync status <file> | Detect drift between the specification and implementation by comparing generated and actual TypeScript files. Non-zero exit code on drift. | | moment sync propose <file> | Generate change proposals to reconcile detected drift between specification and implementation. | | moment sync accept <file> | Accept proposed changes and apply them to the implementation. | | moment reconcile <file> | Run cascade reconciliation to classify and resolve drift. Supports --mode local and --mode event for different reconciliation sources. | | moment status <file> | Display unified project status: parse validity, sync drift, schema lifecycle, and upstream fingerprint. |

Schema Governance

| Command | Description | |---------|-------------| | moment schema status <file> | Display schema lifecycle status for all events and commands in the specification, grouped by phase. | | moment lint <file> | Run codex governance rules against the specification and report policy violations. Supports --json for CI integration. |

Import

| Command | Description | |---------|-------------| | moment import --from-sift <dir> | Import Sift JSONL event streams from a .domain/ directory into .moment specification files. Writes upstream fingerprint for drift tracking. |

Authentication

| Command | Description | |---------|-------------| | moment auth login | Authenticate with Moment cloud services. Initiates an interactive login flow. | | moment auth status | Display current authentication status and account information. | | moment auth logout | Clear stored authentication credentials. |

Common Options

These are commonly used options available on the commands indicated, not globally on every command. Individual commands may support additional command-specific flags not listed here.

| Option | Available on | Description | |--------|-------------|-------------| | --json | derive, simulate, lint, schema status, sync status/propose/accept, reconcile, status, import | Machine-readable JSON output to stdout. | | --out <dir> | generate, emit-ts | Override the output directory for generated artifacts (defaults to the project root or cwd). | | --out-dir <dir> | simulate | Write topology, scenario, and artifact files to the specified directory. | | --output-dir <dir> | import --from-sift | Write imported .moment files to the specified directory. | | --all | simulate, serve | Generate all branch combinations and negative scenarios (simulate) or serve all scenarios including negatives (serve). | | --all | sync accept | Accept all pending proposals. | | --dry-run | emit-ts | List files that would be emitted without writing them. | | --verbose | status | Enable detailed output. | | --port <n> | serve | WebSocket port (default 4321). |

Examples

New Project Setup

# Scaffold a new project
moment init --name my-service --dir my-service
cd my-service

# Write your .moment specification, then generate everything
moment derive specs/my-service.moment
moment emit-ts specs/my-service.moment
moment generate specs/my-service.moment

Continuous Development

# Watch mode regenerates on every save
moment watch specs/

# After implementing domain logic, run conformance tests
moment test specs/my-service.moment

# Check for drift
moment status specs/my-service.moment

Upstream Specification Import

# Import from Sift event streams
moment import --from-sift .domain/

# Review the generated .moment files, then derive and generate
moment derive specs/my-service.moment
moment emit-ts specs/my-service.moment

CI/CD Pipeline

#!/bin/bash
set -e

# Validate specification
moment parse specs/my-service.moment

# Check for drift (non-zero exit code on drift)
moment sync status specs/my-service.moment

# Run conformance tests
moment test specs/my-service.moment

# Lint governance rules
moment lint specs/my-service.moment --json

# Generate documentation artifacts
moment generate specs/my-service.moment

Drift Detection and Reconciliation

# Check sync status
moment sync status specs/my-service.moment

# Generate proposals for detected drift
moment sync propose specs/my-service.moment

# Review proposals, then accept
moment sync accept specs/my-service.moment

# Or run full cascade reconciliation
moment reconcile specs/my-service.moment

Schema Governance Audit

# View schema lifecycle status
moment schema status specs/my-service.moment

# Run governance rules
moment lint specs/my-service.moment

# Machine-readable output for dashboards
moment schema status specs/my-service.moment --json
moment lint specs/my-service.moment --json

Integration

@mmmnt/cli is the consumer-facing interface to the entire Moment toolchain. It depends on all library packages:

@mmmnt/cli
  |
  +-- @mmmnt/core      (parsing and IR generation)
  +-- @mmmnt/derive    (test topology and scenario derivation)
  +-- @mmmnt/emit-ts   (TypeScript code generation)
  +-- @mmmnt/generate  (Gherkin, specification documents, AsyncAPI)
  +-- @mmmnt/harness   (test execution)
  +-- @mmmnt/schema    (schema lifecycle governance)
  +-- @mmmnt/sync      (drift detection and reconciliation)
  +-- @mmmnt/viz       (visualization data generation)

For programmatic integration or AI agent workflows, see @mmmnt/mcp which exposes the same capabilities over the Model Context Protocol.

Contributing

This package is part of the mmmnt monorepo. See the repository root for contribution guidelines, development setup, and the code of conduct.

git clone https://github.com/mmmnt/mmmnt.git
cd mmmnt
pnpm install
pnpm turbo build --filter=@mmmnt/cli
pnpm --filter @mmmnt/cli test

License

FSL-1.1-Apache-2.0