Mergeway Overview

Mergeway is a lightweight CLI that keeps metadata honest by treating schemas as code. Instead of juggling spreadsheets or custom scripts, you describe entities in YAML/JSON, run a quick validation, and catch broken references before they reach production.

What the CLI Does

• Stores entity definitions and relationships in version-controlled files.
• Validates schemas and records so required fields and references stay consistent.
• Generates simple reports you can attach to pull requests or issues.

Key Features

• Workspace scaffolding: mw init writes a starter mergeway.yaml into your working directory so you can begin defining entities immediately.
• Dual schema sources: Author entity fields inline in YAML or reference existing JSON Schema documents (json_schema) so teams can reuse specs.
• Object lifecycle commands: list, get, create, update, and delete operate on local YAML/JSON files, respecting identifier fields defined in schemas and inline data.
• Deterministic formatting: mw fmt emits canonical structure and rewrites files in place (use --stdout to preview changes) to keep diffs clean.
• Layered validation: Format, schema, and reference phases catch structural, typing, and cross-entity errors before they land in main.
• Schema introspection: mw entity show and mw config export surface normalized schemas or derived JSON Schema for documentation and automation.

Why Teams Use Mergeway

• Fast feedback: One command surfaces missing fields, enum mismatches, or invalid references.
• Git-native: Changes live in branches and pull requests, making reviews trivial.
• Lightweight: No server component—just a binary that runs locally or in CI.

Where to Go Next

1. Install Mergeway (or build from source).
2. Follow the Workspace set-up.
3. Review the Basic Concepts and Schema Format when you define entities.
4. Browse through the CLI Reference for command syntax.

Updates land in the Changelog. File GitHub issues for questions, bugs, or requests.

This guide introduces the basic concepts and structure of a Mergeway workspace. It is intended for new users who want to understand how to set up and use Mergeway effectively.

A Mergeway workspace is just a folder with a few predictable parts. Knowing the vocabulary makes the CLI output easier to read.

Building Blocks

• Workspace: Folder tracked in Git that contains mergeway.yaml, schemas, and optional objects. All commands run from here.
• Schema: YAML/JSON that defines fields and references. Each file describes one entity.
• Object: Optional data instances stored under data/.
• Reference: A link from one schema or field to another (type: ref). Mergeway validates referential integrity.

Validation Flow

1. Mergeway loads mergeway.yaml to locate schemas and records.
2. Schemas are parsed and checked for required fields, types, and references.
3. Records (if present) are validated against their schemas.

For field syntax and configuration options, see the Schema Format.

Pick the method that fits your setup. Each installs a single binary named mw.

Option 1 – Download a Release (macOS, Linux)

curl -L https://github.com/mergewayhq/mergeway-cli/releases/download/v0.11.0/mw-
$(uname | tr '[:upper:]' '[:lower:]')-amd64.tar.gz \
  | tar -xz
sudo mv mw /usr/local/bin/

Check the published SHA-256 checksum before moving the binary if you operate in a locked-down environment.

Option 2 – Go Install (for contributors)

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

This drops the binary in $GOPATH/bin. Prefer tagged versions in production.

Verify

mw --version

You should see something similar to:

Mergeway CLI v0.11.0 (commit abc1234)

If the command is missing, confirm that the installation path is on your PATH.

Move on to the Getting Started guide once the binary is available.

Goal: scaffold a workspace, define an entity, evolve the layout as requirements grow, and learn the core Mergeway commands end-to-end.

All commands assume the mw binary is on your PATH.

1. Scaffold a Workspace with Inline Data

mkdir farmers-market
cd farmers-market
mw init

mw init creates a mergeway.yaml entry file. Replace its contents with an inline entity that also carries a few inline records:

mergeway:
  version: 1

entities:
  Category:
    description: Simple lookup table for product groupings
    identifier: slug
    fields:
      slug:
        type: string
        required: true
      label:
        type: string
        required: true
    data:
      - slug: produce
        label: Fresh Produce
      - slug: pantry
        label: Pantry Staples

Try a few commands:

mw entity list
mw entity show Category
mw list --type Category
mw validate

At this stage everything lives in a single file—perfect for tiny datasets.

2. Move Records into External YAML Files

As the table grows, shift the data into dedicated files. Create a folder for category data and move the records there:

mkdir -p data/categories
cat <<'YAML' > data/categories/categories.yaml
items:
  - slug: produce
    label: Fresh Produce
  - slug: pantry
    label: Pantry Staples
  - slug: beverages
    label: Beverages
YAML

Update mergeway.yaml so Category reads from the new file:

mergeway:
  version: 1

entities:
  Category:
    description: Simple lookup table for product groupings
    identifier: slug
    include:
      - data/categories/*.yaml
    fields:
      slug:
        type: string
        required: true
      label:
        type: string
        required: true

Re-run the commands to see the effect:

mw list --type Category
mw get --type Category beverages
mw validate

3. Split Schema Definitions and Add JSON Data

Larger workspaces benefit from keeping schemas in their own files. Create an entities/ folder for additional definitions:

mkdir -p entities

Add a new Product entity that pulls from a JSON file using a JSONPath selector:

cat <<'YAML' > entities/Product.yaml
mergeway:
  version: 1

entities:
  Product:
    description: Market products with category references
    identifier: sku
    include:
      - path: data/products.json
        selector: "$.items[*]"
    fields:
      sku:
        type: string
        required: true
      name:
        type: string
        required: true
      category:
        type: Category
        required: true
      price:
        type: number
        required: true
YAML

Create the JSON data file the schema expects. Notice that one product references a household category that we haven't defined yet:

cat <<'JSON' > data/products.json
{
  "items": [
    {"sku": "apple-001", "name": "Honeycrisp Apple", "category": "produce", "price": 1.25},
    {"sku": "oat-500", "name": "Rolled Oats", "category": "pantry", "price": 4.99},
    {"sku": "soap-010", "name": "Castile Soap", "category": "household", "price": 6.75}
  ]
}
JSON

Finally, have mergeway.yaml pull in any external schemas:

mergeway:
  version: 1

include:
  - entities/*.yaml

entities:
  Category:
    description: Simple lookup table for product groupings
    identifier: slug
    include:
      - data/categories/*.yaml
    fields:
      slug:
        type: string
        required: true
      label:
        type: string
        required: true

Explore the richer workspace:

mw entity list
mw entity show Product
mw list --type Product
mw validate

mw validate now reports a broken reference because the household category doesn't exist yet:

phase: references
type: Product
id: soap-010
file: data/products.json
message: referenced Category "household" not found

Add the missing category to the YAML file and validate again:

cat <<'YAML' >> data/categories/categories.yaml
- slug: household
  label: Household Goods
YAML

mw validate

With the additional category in place, validation succeeds and both entities are in sync.

4. Export Everything as JSON

Collect the full dataset into a single snapshot:

mw export --format json --output market-snapshot.json
cat market-snapshot.json

Keep the Workflow Running Smoothly

Once the basics feel comfortable, automate formatting and reviews so the workspace stays healthy:

• Set Up Mergeway with GitHub to enforce mw fmt --lint in Actions and route reviews through CODEOWNERS.
• Enforce Mergeway Formatting with pre-commit so contributors run mw fmt locally before every commit.

You're Done!

Nice work—you’ve defined entities inline, moved data to YAML, added JSON-backed entities, and exercised the key Mergeway commands. You're ready to scale the workspace to your team’s needs.

Schemas can live entirely inside mergeway.yaml or be split across additional include files (for example under an entities/ folder) for readability. Likewise, object data may be defined inline or stored under data/. Pick the mix that matches your editing workflow—comments below highlight conventions for modular repositories without requiring them.

Configuration Entry (mergeway.yaml)

The workspace entry file declares the schema version and the files to load:

mergeway:
  version: 1

include:
  - entities/*.yaml

• mergeway.version tracks breaking changes in the configuration format (keep it at 1).
• include is a list of glob patterns. Each matching file is merged into the configuration. Patterns need to resolve to at least one file; otherwise Mergeway reports an error.

Schema Files (optional includes)

A schema file declares one or more entity definitions. Store them in whichever folder makes sense for your workflow (many teams use entities/); the location has no semantic impact. The example below defines a Post entity:

mergeway:
  version: 1

entities:
  Post:
    description: Blog posts surfaced on the marketing site
    identifier: id
    include:
      - data/posts/*.yaml
    fields:
      id: string
      title:
        type: string
        required: true
        description: Human readable title
      body: string
      author:
        type: User
        required: true
    data:
      - id: post-inline
        title: Inline Example
        author: user-alice
        body: Inline data lives in the schema file.

For advanced scenarios you can expand identifier into a mapping:

mergeway:
  version: 1

entities:
  Post:
    description: Blog posts surfaced on the marketing site
    identifier:
      field: id
      generated: true
    include:
      - data/posts/*.yaml
    fields:
      # ...

generated: true is an advisory hint for downstream automation (code generators, UI scaffolding). The CLI still expects inline identifiers or an explicit --id flag when creating objects.

When several objects live in one file, provide a JSONPath selector to extract them:

mergeway:
  version: 1

entities:
  User:
    description: Directory of account holders sourced from JSON
    identifier: id
    include:
      - path: data/users.json
        selector: "$.users[*]"
    fields:
      # ...

Strings remain a shorthand for path with no selector; Mergeway then reads the entire file as a single object (or uses the items: array if present).

Required Sections

Add description anywhere you need extra context. Entities accept it alongside identifier, and each field definition supports its own description value.

Inline Data

Inline data is helpful for tiny lookup tables or bootstrapping a demo without creating additional files. Define records directly inside the entity specification:

mergeway:
  version: 1

entities:
  Person:
    description: Lightweight profile objects
    identifier: id
    include:
      - data/people/*.yaml
    fields:
      id: string
      name:
        type: string
        required: true
        description: Preferred display name
      age: integer
    data:
      - id: person-1
        name: Alice
        age: 30
      - id: person-2
        name: Bob
        age: 42

Inline records are loaded alongside file-based data. If a record with the same identifier exists both inline and on disk, the file wins. Inline records are read-only at runtime—mw data update and mw data delete target files only.

Field Shorthand

When a field only needs a type, map entries can use the compact field: type syntax. These fields default to required: false and behave identically to the expanded form otherwise. Switch to the full mapping whenever you need attributes like required, repeated, or format.

Field Attributes

JSON Schema Entities

For larger teams it can be convenient to author schemas once and consume them in multiple places. Entities now support a json_schema property that points to an on-disk JSON Schema document (draft 2020-12). The path is resolved relative to the file that declares the entity and needs to live inside the repository—external $ref documents and network lookups are rejected.

When json_schema is present, omit the fields map. Mergeway parses the JSON Schema and converts to its native field definitions:

• type: object becomes nested field groups, preserving required entries for each level.
• type: array sets repeated: true and uses the items schema to determine the element type.
• enum, const, or oneOf blocks translate into Mergeway enums (string values only).
• $ref segments are resolved within the same JSON Schema file (e.g., #/$defs/...).
• Custom references to other entities use the same x-reference-type property emitted by mw config export.

See examples/json-schema for a runnable workspace that demonstrates this flow end-to-end.

Keep schema files small and focused—one entity per file is the easiest to maintain.

Data Files

Each data file provides the fields required by its entity definition. Declaring a type at the top is optional—the CLI infers it from the entity that referenced the file (through include/selector) and only errors when a conflicting type value is present. Keeping it in the file can still be helpful for humans who open an arbitrary YAML document.

type: Post # optional; falls back to the entity that included this file
id: post-001
title: Launch Day
author: user-alice
body: |
  We are excited to announce the product launch.

You can store one object per file (as above) or provide an items: array to keep several objects together. Mergeway removes any top-level type key before validating the record, so referencing the same file from multiple entities requires the selector approach described below.

JSONPath selectors let you extract objects from nested structures—handy when you need to read a subset of a larger document. For example, selector: "$.users[*]" walks through the users array in a JSON file and emits one record per element. Mergeway validates that the selector returns objects; any other shape triggers a format error.

Identifier fields accept numeric payloads as well. For example, the following record is valid when the schema marks id as an integer:

id: 42
name: Numeric Identifier

Good Practices

• Prefer references (type: User) over duplicating identifiers.
• Group files in predictable folders (data/posts/, data/users/, etc.).
• Run mw validate after every change to catch problems immediately.

Need more context? Return to the Basic Concepts page for the bigger picture.

The how-to guides capture focused, task-oriented recipes for Mergeway users. Each guide assumes you already understand the core concepts and need a concrete sequence of steps to accomplish a specific outcome, such as enforcing formatting in CI or wiring Mergeway into deployment automation.

Goal: wire Mergeway into GitHub so formatting stays consistent and ownership of datasets is clearly distributed across teams.

Throughout this guide we will reference GrainBox Market, a fictional marketplace that stores product data in data/products/ and category lookups in data/categories/. The Data Platform team maintains mergeway.yaml, while Inventory Operations and Category Management own their respective folders.

Prerequisites

• A repository that already contains a valid mergeway.yaml and the files it references.
• GitHub Actions enabled for the repository.
• Permission to configure GitHub teams (or at least invite individual maintainers) so CODEOWNERS can route reviews correctly.

1. Add a Mergeway Workflow

Create .github/workflows/mergeway-fmt.yml to ensure every pull request keeps GrainBox data formatted:

name: Mergeway Formatting

on:
  pull_request:
    branches: [main]
    paths:
      - "**/*.yaml"
      - "**/*.yml"
      - mergeway.yaml
  push:
    branches: [main]

jobs:
  mw-fmt:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Install Go toolchain
        uses: actions/setup-go@v5
        with:
          go-version-file: go.mod

      - name: Install Mergeway CLI
        run: go install github.com/mergewayhq/mergeway-cli@latest

      - name: Lint Mergeway formatting
        run: mw fmt --lint

This job fails fast whenever a record under data/products/ or data/categories/ is out of format, ensuring reviewers only see clean diffs. Adjust the paths filters if your workspace stores data outside YAML.

2. Explain the Failure Mode to Contributors

mw fmt --lint prints each offending file, so GrainBox developers fix CI failures locally with mw fmt --in-place. Capture that reminder in your pull-request template or CONTRIBUTING guide so the workflow feels helpful rather than mysterious.

3. Assign Ownership with CODEOWNERS

Formatting alone is not enough—you also want the right people reviewing Mergeway changes. GitHub’s CODEOWNERS file routes pull requests to specific teams or individuals based on path globs.

Create .github/CODEOWNERS with entries for both GrainBox teams and any shared files:

# Mergeway schema is owned by Data Platform
mergeway.yaml @grainbox/data-platform

# Data files are split by operational team
data/products/ @grainbox/inventory-ops
data/categories/ @grainbox/category-mgmt

Key considerations:

• Teams need to exist inside your GitHub organization (for example @org/team-slug). If you don't have teams yet, either create them under Settings → Teams or list specific people such as @alice and @bob.
• You can mix teams and individuals to cover overlapping areas—for instance, keep mergeway.yaml owned by @grainbox/data-platform and also list @lead-architect for extra oversight.
• CODEOWNERS applies to all pull requests, so combining it with the workflow guarantees every Mergeway change is reviewed by someone who understands that slice of the dataset.

4. Keep Versions Predictable

GrainBox pins versions for long-lived branches by replacing @latest with a tag (e.g., @v0.11.0) or by caching the binary. Matching versions between local machines and CI prevents "works on my laptop" formatting diffs.

Once the workflow and CODEOWNERS file land in the default branch, any pull request that touches Mergeway files will:

1. Trigger the formatting check so contributors fix issues before merging.
2. Automatically request reviewers from the right team, ensuring accountability for each dataset.

That combination keeps Mergeway-managed data healthy as your GitHub organization grows.

Goal: run mw fmt automatically before every commit so contributors push consistently formatted GrainBox Market data.

We will keep using the fictional GrainBox Market repository from the GitHub how-to: schemas live in mergeway.yaml, product data sits under data/products/, and category lookups live in data/categories/.

Prerequisites

• The Mergeway CLI (mw) is already installed on developer machines and in your PATH.
• Python 3.8+ is available (pre-commit ships via pipx, pip, or Homebrew).
• Your repo includes the Mergeway workspace you want to protect.

1. Install pre-commit Locally

Pick the method that matches your tooling:

pipx install pre-commit      # recommended
# or
pip install pre-commit       # inside a virtualenv
# or
brew install pre-commit      # macOS

Developers only need to do this once per workstation.

2. Configure the Hook

Add a .pre-commit-config.yaml file in the repo root (or extend your existing config) with a local hook that invokes mw fmt:

repos:
  - repo: local
    hooks:
      - id: mergeway-fmt
        name: mergeway fmt
        entry: mw fmt
        language: system
        pass_filenames: false
        files: ^data/(products|categories)/.*\.(ya?ml|json)$

Why these settings?

• entry: mw fmt rewrites any out-of-format records before the commit proceeds (it defaults to in-place mode).
• pass_filenames: false lets Mergeway discover files from mergeway.yaml rather than only the files staged by Git—useful when your workspace spans multiple folders.
• files narrows execution to the GrainBox data directories so unrelated commits (docs, code) skip the hook. Adjust the regex for your layout or remove the key to run on everything.

If you prefer CI-style failures, swap --in-place for --lint. The hook will then block the commit and print offending files without mutating them.

3. Install the Git Hook

Tell pre-commit to write the hook into .git/hooks/pre-commit:

pre-commit install --hook-type pre-commit

To cover pushes from automation as well, you may also install it as a pre-push hook:

pre-commit install --hook-type pre-push

Each contributor only needs to run these commands once per clone.

4. Test the Setup

Run the hook against every tracked file to confirm it formats data as expected:

pre-commit run mergeway-fmt --all-files

• If the repo already follows Mergeway’s canonical layout, the command prints mergeway-fmt..................................Passed.
• If output shows Failed, inspect the listed files, rerun mw fmt <file> manually if needed, then stage the changes.

Developers now get immediate feedback before commits ever leave their machines, and CI stays clean because repositories reach GitHub with consistent Mergeway formatting.

Every command shares a set of global flags (use --long-name; single-dash long flags like -root are not supported). Global flags can appear before or after the command name.

Repository setup

• init
• validate
• version

Schema utilities

• entity list
• entity show
• fmt
• config lint
• config export
• gen-erd

For more information on the schema, please consult the Schema Format

Object operations

• list
• get
• create
• update
• delete
• export

Need a refresher on terminology? See the Basic Concepts page.

Synopsis: Scaffold the directory layout and default configuration for a Mergeway workspace.

Usage

mw [global flags] init

mw init targets the directory referenced by --root (default .) and does not accept positional arguments. Use mkdir/cd before running the command if you want to initialize a new folder.

Need a walkthrough after initialization? Continue with the Getting Started guide.

Example

mkdir blog-metadata
cd blog-metadata
mw init

Output resembles:

Initialized repository at .

mw init ensures a starter mergeway.yaml exists in the target directory. Add folders such as entities/ or data/ yourself once the project grows; keeping everything in a single file is perfectly valid. Re-run the command safely—it won't overwrite existing files.

The default configuration contains:

# mw configuration
mergeway:
  version: 1

entities: {}

Related Commands

• mw validate — run after adding schema and data files.
• mw config lint — verify configuration changes once you edit mergeway.yaml.

Synopsis: Check schemas, records, and references, emitting formatted errors when something is wrong.

Usage

mw [global flags] validate [--phase format|schema|references]... [--fail-fast]

When you request the references phase, Mergeway automatically includes the schema phase so reference checks have the information they need.

Examples

Run the command from the workspace root (or add --root to point elsewhere).

Validate the current workspace:

mw validate

Add --format json when you need machine-readable output.

Output:

validation succeeded

Run validation after introducing a breaking schema change:

mw validate

Output when the Post schema requires an author but the record is missing it:

- phase: schema
  type: Post
  id: post-001
  file: data/posts/launch.yaml
  message: missing required field "author"

The command writes errors to standard output and still exits with status 0, so automation can check whether any errors were returned.

Related Commands

• mw config lint — validate configuration without loading data.
• mw list — locate the objects mentioned in validation errors.

Synopsis: Show every entity Mergeway discovered from your configuration.

Usage

mw [global flags] entity list

No command-specific flags. Add the global --root flag if you need to inspect another workspace.

Example

List entities for the examples/ workspace bundled with the repository:

mw --root examples/full entity list

Output:

Comment
Post
Tag
User

Entities are listed alphabetically.

Related Commands

• mw entity show — inspect an individual schema definition.
• mw config lint — verify the configuration if an entity is missing.

Synopsis: Print the normalized schema for a given entity.

Usage

mw [global flags] entity show <entity>

No additional flags. Use --format json if you prefer JSON output, and add the global --root flag when working outside the workspace root.

Example

Show the Post entity in YAML form:

mw --root examples/full --format yaml entity show Post

Output (abridged):

name: Post
source: .../examples/full/entities/Post.yaml
identifier:
  field: id
filepatterns:
  - data/posts/*.yaml
fields:
  title:
    type: string
    required: true
  author:
    type: User
    required: true
  body:
    type: string

Related Commands

• mw entity list — find available entities.
• mw config export — generate a JSON Schema from an entity definition.

Synopsis: Validate configuration files (including includes) without touching data.

Usage

mw [global flags] config lint

No additional flags.

Example

Run the command from the workspace root (or pass --root):

mw config lint

Output:

configuration valid

If the command encounters a problem (for example, an include pattern that matches no files), it prints the error and exits with status 1.

Run this command whenever you edit mergeway.yaml or add new entity definitions to catch syntax mistakes early.

Related Commands

• mw config export — derive a JSON Schema for a type.
• mw validate — validate both schemas and data.

Synopsis: Emit a JSON Schema for one of your types.

Usage

mw [global flags] config export --type <type>

Example

Run the command from the workspace root (or pass --root). Export the Post type as JSON Schema:

mw --root examples --format json config export --type Post

Output (abridged):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "author": {
      "type": "string",
      "x-reference-type": "User"
    },
    "title": {
      "type": "string"
    }
  },
  "required": ["id", "title", "author"],
  "type": "object"
}

Fields that reference other types include the x-reference-type hint.

Validate your workspace (mw config lint or mw validate) after editing type files to ensure the exported schema stays in sync.

Related Commands

• mw entity show — view the full Mergeway representation of an entity.
• mw validate — ensure data conforms to the schema you just exported.

Synopsis: List object identifiers for a given type, optionally filtered by a field.

Usage

mw [global flags] list --type <type> [--filter key=value]

Example

Run the command from the workspace root. If you need to operate on another directory, add the global --root flag.

List all posts in the quickstart workspace:

mw list --type Post

Output:

post-001

Filter by author:

mw list --type Post --filter author=user-alice

Output:

post-001

Related Commands

• mw get — inspect a specific object.
• mw create — add a new object when an ID is missing.

Synopsis: Print the fields of one object.

Usage

mw [global flags] get --type <type> <id>

Use --format json if you prefer JSON output.

Example

Run the command from the workspace root. Use --root if you need to target another workspace.

Fetch the post-001 record as YAML:

mw --format yaml get --type Post post-001

Output:

author: user-alice
body: |
  We are excited to announce the product launch.
id: post-001
title: Launch Day

Related Commands

• mw list — discover identifiers before calling get.
• mw update — change object fields.

Synopsis: Create a new object file that conforms to an entity definition.

Usage

mw [global flags] create --type <type> [--file path] [--id value]

Example

Run the command from the workspace root (or pass --root if you are elsewhere). Create a user by piping a YAML document and letting Mergeway write the file under data/users/:

cat <<'PAYLOAD' > user.yaml
name: Bob Example
PAYLOAD

mw create --type User --file user.yaml --id user-bob

Output:

User user-bob created

The command writes data/users/user-bob.yaml with the provided fields. Remove the temporary user.yaml file afterward and run mw validate to confirm the new object passes checks.

Related Commands

• mw update — modify an existing object.
• mw delete — remove an object.

Synopsis: Modify an existing object. You can replace the object entirely or merge in a subset of fields.

Usage

bash
mw [global flags] update --type <type> --id <id> [--file path] [--merge]
```| Flag | Description |
| --- | --- |
| `--file` | Optional path to a YAML/JSON payload (defaults to STDIN). |
| `--merge` | Merge fields into the existing object instead of replacing it. |
type` | Required. Type identifier. |
| `--id` | Required. Object identifier to update. |
| `--
```bash
## Example

Run the command from the workspace root (or add `--root` to target another workspace). Update a post title by merging in a tiny payload:

cat <<'PAYLOAD' > post-update.yaml
title: Launch Day (Updated)
PAYLOAD

mw update --type Post --id post-001 --file post-update.yaml --merge

Output:

Post post-001 updated

Run mw validate after significant updates to confirm references still resolve. Without --merge, the payload replaces the entire object.

Delete the temporary payload file once you are done with the update.

Related Commands

• mw create — add new objects.
• mw delete — remove objects that are no longer needed.

Synopsis: Remove an object file from the workspace.

Usage

mw [global flags] delete --type <type> <id>

The command prompts for confirmation unless you pass the global --yes flag.

Global flags (like --yes or --root) can appear before or after the command name.

Example

Run the command from the workspace root (or add --root to target another workspace). Delete a user without prompting:

mw --yes delete --type User user-bob

Output:

User user-bob deleted

Related Commands

• mw list — confirm an object’s identifier before deleting.
• mw create — recreate an object if you delete the wrong one.

Generates an Entity Relationship Diagram (ERD) of your data model.

mw gen-erd --path <output-file>

This command inspects your configuration and generates a visual representation of your entities and their relationships. It relies on Graphviz (specifically the dot command) to produce the output image.

Arguments

Examples

Generate a PNG image of your schema:

mw gen-erd --path schema.png

Generate an SVG:

mw gen-erd --path schema.svg

Example output, based on the full example:

Requirements

The dot executable from Graphviz needs to be installed and available in your system's PATH.

Synopsis: Export repository objects into a single JSON or YAML document.

Usage

mw [global flags] export [--output <path>] [entity...]

The export format matches the global --format flag (yaml by default).

Examples

Export every entity in the repository as YAML to the terminal:

mw export

Export only the User and Post entities as JSON into a file:

mw --format json export --output snapshot.json User Post

Each top-level key in the output map is the entity name; the value is an array of records sorted by ID.

Related Commands

• mw list — inspect available identifiers before exporting.
• mw get — fetch a single object instead of the full dataset.

Synopsis: Display the CLI build metadata (semantic version, commit, build date).

Usage

mw [global flags] version

No additional flags.

This command does not touch workspace files; global flags like --root are ignored.

Example

mw --format json version

Output:

{
  "version": "0.1.0",
  "commit": "a713be5",
  "buildDate": "2025-10-22T18:25:03Z"
}

Values change with each build; use the command to confirm which binary produced a validation report or data change.

Related Commands

• mw validate — include the CLI version in validation artifacts for traceability.