mergeway-cli

README

Mergeway CLI

mergeway-cli is a command-line toolkit for keeping metadata in version control. It stores YAML and JSON objects on disk, validates their schemas, and verifies the integrity of relationships between those objects so your automation stays trustworthy. This repository also ships mergeway-diff for semantic repository snapshots, mergeway-lsp for editor integrations, and mergeway-mcp as a read-only MCP server for repository inspection workflows.

For full product and documentation coverage, visit:

• Mergeway website
• Mergeway CLI getting started guide
• Mergeway CLI reference documentation
• Mergeway CLI guides

What It Does

• Track metadata like code: Check structured data into Git and review changes with normal diffs.
• Enforce contracts: Schema and reference validation catch format drift and broken links between related records.
• Automate comfortably: Scriptable CRUD commands with YAML/JSON output slot into CI pipelines and other tooling.
• Spin up fast: Scaffold a new workspace in seconds with sensible defaults that scale with your dataset.

Key Features

• Workspace scaffolding: mergeway-cli init bootstraps mergeway.yaml in the working directory so you can start committing metadata immediately.
• Flexible schemas: Define entities inline in YAML or point json_schema at a JSON Schema (draft 2020-12) file; mix inline data, globbed includes, or JSONPath selectors to source records.
• Complete CRUD workflow: list, get, create, update, and delete commands operate on the same files Git tracks, supporting STDIN/STDOUT automation and partial updates.
• Deterministic formatting: mergeway-cli fmt rewrites YAML/JSON in place (add --stdout to preview) so reviews stay focused on substance.
• Layered validation: mergeway-cli validate runs format, schema, and reference phases, surfacing missing fields, enum mismatches, and cross-entity linkage issues before merge time.
• Schema introspection: mergeway-cli entity show and mergeway-cli config export emit normalized schemas or JSON Schema for tooling, keeping downstream integrations in sync.
• Visualization: mergeway-cli gen-erd generates an Entity Relationship Diagram (ERD) using Graphviz, visualizing your data model's entities and their relationships.

Install

Using Go

go install github.com/mergewayhq/mergeway-cli@latest

Ensure your GOBIN (or GOPATH/bin) is on PATH, then confirm with mergeway-cli version.

This installs mergeway-cli. Install the other binaries separately if needed:

go install github.com/mergewayhq/mergeway-cli/cmd/mergeway-diff@latest
go install github.com/mergewayhq/mergeway-cli/cmd/mergeway-lsp@latest
go install github.com/mergewayhq/mergeway-cli/cmd/mergeway-mcp@latest

Using Docker

docker run ghcr.io/mergewayhq/mergeway-cli version

Use the public GitHub Container Registry image to run the CLI without installing the binary locally.

To run the CLI against the workspace in your current directory, mount it into the container:

docker run --rm \
  -v "$PWD:/work" \
  ghcr.io/mergewayhq/mergeway-cli validate

Using Nix

You can install the CLI using Nix:

nix profile install github:mergewayhq/mergeway-cli

Or run it directly:

nix run github:mergewayhq/mergeway-cli -- help

Download a Release Binary

Each GitHub release publishes macOS, Linux, and Windows assets for amd64 and arm64, covering mergeway-cli, mergeway-diff, mergeway-lsp, and mergeway-mcp.

• Put mergeway-cli on PATH for CLI use.
• Put mergeway-diff on PATH for semantic diff workflows.
• Put mergeway-lsp on PATH for editor integration.
• Put mergeway-mcp on PATH for MCP client integrations.
• The published container image remains CLI-only.

Build from Source

git clone https://github.com/mergewayhq/mergeway-cli.git
cd mergeway-cli
make build
./bin/mergeway-cli version
./bin/mergeway-diff --help
./bin/mergeway-lsp --log-stderr --log-level=debug
./bin/mergeway-mcp --help

Semantic Diff

mergeway-diff compares Mergeway-managed records between logical repository snapshots.

• Build it locally with make build or extract it from a release archive.
• Use --format json for machine-readable semantic diff output.
• Snapshot modes and reporting workflow are documented here:
  • mergeway-diff reference
  • Communicate Repository Changes with mergeway-diff

Language Server

mergeway-lsp speaks the Language Server Protocol over stdio and is intended to be launched by your editor.

• Build it locally with make build or extract it from a release archive.
• Use --log-file, --log-stderr, or --log-level for debugging.
• Editor setup is documented here:
  • VS Code extension README
  • Run mergeway-lsp manually
  • Set up mergeway-lsp in VS Code and Neovim

Current limitations:

• The VS Code extension currently expects you to install or build mergeway-lsp yourself and point mergeway.lsp.path at it.
• The LSP currently uses full-document sync.
• The Docker image contains mergeway-cli only.

MCP Server

mergeway-mcp exposes a read-only Model Context Protocol server for inspecting a Mergeway repository.

• Build it locally with make build or make build-mcp, or extract it from a release archive.
• Use stdio by default for MCP clients that launch a subprocess.
• Use --transport=http when you need a streamable HTTP endpoint instead.
• Scope access with repeated --entity flags when a client should only see specific exact entity names.
• The server does not allow create, update, or delete operations.
• MCP startup and flags are documented here:
  • mergeway-mcp reference
  • setup for Claude and Codex

Quick Start

# 1. Scaffold a workspace
mkdir my-dataset
cd my-dataset
mergeway-cli init

# 2. Inspect the generated entities and schemas
mergeway-cli entity list
mergeway-cli entity show User --format json

# 3. Add or update metadata
mergeway-cli create --type User --file payloads/jane.yaml
mergeway-cli list --type User

# 4. Validate structure and relations before merging
mergeway-cli validate

# 5. Export your dataset as a single snapshot
mergeway-cli export --format json --output snapshot.json

Explore the Examples

A sample workspace lives under examples/full. Point mergeway-cli at it to see commands and responses in context:

mergeway-cli --root examples/full entity list
mergeway-cli --root examples/full list --type User
mergeway-cli --root examples/full get --type Post post-001 --format json
mergeway-cli --root examples/full validate

Curious about JSON Schema-backed entities? examples/json-schema demonstrates how an entity can derive its field definitions from an external JSON Schema file.

Want to see a reference union? examples/reference-union shows a minimal workspace where a field uses User | Team.

For a deeper command reference, check docs/src/cli-reference/README.md.

Hacking on the CLI

Contributor workflows, tooling, and release notes live in DEVELOPING.md.

License

Mergeway CLI is released under the MIT License.