Mergeway

https://mergewayhq.github.io/mergeway-cli
Admin
Mergeway is a metadata management tool that enables teams to define schemas and entities as code in...
Tokens:17,442
Snippets:270
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Clone the example repository

Source: https://mergewayhq.github.io/mergeway-cli/guides/example-repo.html

Initial setup to download the example repository and navigate to its root directory.

```bash
git clone git@github.com:mergewayhq/mergeway-example-repo.git
cd mergeway-example-repo
```

--------------------------------

### Install pre-commit

Source: https://mergewayhq.github.io/mergeway-cli/guides/setup-mergeway-pre-commit.html

Install the pre-commit framework using your preferred package manager.

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

--------------------------------

### Install binaries from release archives

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/installation.html

Use the install command to move extracted binaries to a system directory in your PATH.

```bash
install -m 0755 mergeway-cli /usr/local/bin/mergeway-cli
install -m 0755 mergeway-diff /usr/local/bin/mergeway-diff
install -m 0755 mergeway-lsp /usr/local/bin/mergeway-lsp
install -m 0755 mergeway-mcp /usr/local/bin/mergeway-mcp
```

--------------------------------

### Initialization output

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/init.html

Example output displayed upon successful initialization.

```text
Initialized repository at .
```

--------------------------------

### Check CLI version and usage

Source: https://mergewayhq.github.io/mergeway-cli/guides/example-repo.html

Verify the installation and view available commands.

```bash
mergeway-cli --help    # show usage information
mergeway-cli version   # print the CLI version
```

--------------------------------

### Install Mergeway tools via Go

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/installation.html

Use the Go toolchain to install the CLI and associated binaries directly from the repository.

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

```bash
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
```

--------------------------------

### Install and run Mergeway with Nix

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/installation.html

Manage the CLI installation using Nix profiles or execute it directly without permanent installation.

```bash
nix profile install github:mergewayhq/mergeway-cli
```

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

--------------------------------

### Verify Mergeway tool installation

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/installation.html

Check the installation by running the help or version commands for each binary.

```bash
mergeway-cli version
mergeway-diff --help
mergeway-lsp --log-stderr --log-level=debug
mergeway-mcp --help
```

--------------------------------

### Example YAML output

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/get.html

The expected YAML structure returned by the get command.

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

--------------------------------

### Install git hooks

Source: https://mergewayhq.github.io/mergeway-cli/guides/setup-mergeway-pre-commit.html

Register the pre-commit configuration into the local git hooks directory.

```bash
pre-commit install --hook-type pre-commit
```

```bash
pre-commit install --hook-type pre-push
```

--------------------------------

### Start Default Stdio Server

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/mcp.html

Launches the MCP server using stdio transport rooted at the current directory.

```bash
mergeway-mcp
```

--------------------------------

### Run Mergeway LSP

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/lsp.html

Basic command to start the Mergeway LSP server over stdio.

```bash
mergeway-lsp
```

--------------------------------

### Install pre-commit hooks

Source: https://mergewayhq.github.io/mergeway-cli/guides/example-repo.html

Register the pre-commit and optionally pre-push hooks into the local Git repository.

```bash
pre-commit install --hook-type pre-commit
# optionally also install a pre‑push hook
pre-commit install --hook-type pre-push
```

--------------------------------

### Generate Schema Images

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/gen-erd.html

Examples for generating schema diagrams in PNG and SVG formats.

```bash
mergeway-cli gen-erd --path schema.png
```

```bash
mergeway-cli gen-erd --path schema.svg
```

--------------------------------

### Example Customer data file

Source: https://mergewayhq.github.io/mergeway-cli/guides/json-schema.html

Create YAML data files that conform to the defined JSON Schema structure.

```yaml
# data/customers/customer-001.yaml
id: cust-001
name: Example Industries
tier: enterprise
contacts:
  - label: Primary
    email: ops@example.com
  - label: Billing
    email: finance@example.com
```

--------------------------------

### Basic get command syntax

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/get.html

The standard structure for retrieving an object using the Mergeway CLI.

```bash
mergeway-cli [global flags] get --type <type> <id>
```

--------------------------------

### JSON Schema Output Example

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/config-export.html

Sample JSON Schema output generated by the export command.

```json
{
  "$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"
}
```

--------------------------------

### Example YAML output

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/entity-show.html

An abridged representation of the YAML output generated by the entity show command.

```yaml
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
```

--------------------------------

### Run Mergeway LSP with File Logging

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/lsp.html

Starts the server with debug logging directed to a specific file path.

```bash
mergeway-lsp --log-file /tmp/mergeway-lsp.log --log-level=debug
```

--------------------------------

### mergeway-lsp

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/lsp.html

The mergeway-lsp command starts the Language Server Protocol server. It communicates via JSON-RPC over stdin/stdout.

```APIDOC
## mergeway-lsp

### Description
Starts the Mergeway Language Server Protocol server. The server listens for framed LSP messages on stdin and responds on stdout.

### Flags
- **--log-file** (string) - Optional - Write server logs to the specified file path.
- **--log-level** (string) - Optional - Set the log level: debug, info, warn, or error.
- **--log-stderr** (boolean) - Optional - Write server logs to stderr instead of discarding them.

### Environment Variables
- **MERGEWAY_LSP_LOG_FILE** (string) - Path to log file.
- **MERGEWAY_LSP_LOG_LEVEL** (string) - Log level (debug, info, warn, error).
- **MERGEWAY_LSP_LOG_STDERR** (string) - Set to 1 to write logs to stderr.

### Usage Example
```bash
mergeway-lsp --log-stderr --log-level=debug
```
```

--------------------------------

### Get by path-based identifier

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/get.html

Retrieves an object using its file path as the identifier.

```bash
mergeway-cli --format yaml get --type Note data/notes/alpha.yaml
```

--------------------------------

### Run Mergeway LSP with Debug Logging

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/lsp.html

Starts the server with debug logging enabled, outputting to stderr for manual client testing.

```bash
mergeway-lsp --log-stderr --log-level=debug
```

--------------------------------

### Create a user object from a YAML file

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/create.html

Example of creating a new user entity by piping a YAML payload and specifying an ID.

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

mergeway-cli create --type User --file user.yaml --id user-bob
```

--------------------------------

### Export Type as JSON Schema

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/config-export.html

Example command to export the 'Post' type from a specified workspace root.

```bash
mergeway-cli --root examples --format json config export --type Post
```

--------------------------------

### mergeway-cli get

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/get.html

Retrieves the fields of a specific object identified by type and ID.

```APIDOC
## mergeway-cli get

### Description
Prints the fields of one object. Run the command from the workspace root or use the --root flag to target a different workspace.

### Usage
`mergeway-cli [global flags] get --type <type> <id>`

### Parameters
#### Flags
- **--type** (string) - Required - Type identifier that owns the object.
- **--format** (string) - Optional - Output format (e.g., json, yaml).
- **--root** (string) - Optional - Target workspace root directory.

#### Positional Arguments
- **id** (string) - Required - The object identifier. For path-based entities, this is the relative file path ID.

### Examples
Fetch a record as YAML:
`mergeway-cli --format yaml get --type Post post-001`

Fetch using a file path identifier:
`mergeway-cli --format yaml get --type Note data/notes/alpha.yaml`
```

--------------------------------

### Source JSON Data Structure

Source: https://mergewayhq.github.io/mergeway-cli/guides/json-schema.html

An example JSON file containing an array of user objects to be processed.

```json
{
  "users": [
    { "id": "User-001", "name": "Ada" },
    { "id": "User-002", "name": "Grace" }
  ]
}
```

--------------------------------

### Validation Error Output

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/workspace-setup.html

Example of a validation error message when a reference is missing.

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

--------------------------------

### Delete by file path

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/delete.html

Example of deleting an object using its workspace-relative file path.

```bash
mergeway-cli --yes delete --type Note data/notes/alpha.yaml
```

--------------------------------

### Validation error output

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/validate.html

Example output showing a schema validation error for a missing field.

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

--------------------------------

### Get inherited entity

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/get.html

Retrieves an entity through a parent type using a specific workspace root.

```bash
mergeway-cli --root examples/inheritance --format yaml get --type Animal dog-1
```

--------------------------------

### Update a note using file path identifier

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/update.html

Example of updating an entity that uses a file path as its identifier.

```bash
mergeway-cli update --type Note --id data/notes/alpha.yaml --file note.yaml --merge
```

--------------------------------

### Define a Data File with Optional Type

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/schema-spec.html

Example of a YAML data file for a Post entity. The type field is optional and used for human readability.

```yaml
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.
```

--------------------------------

### Update a post by merging

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/update.html

Example of creating a YAML payload and using the update command with the --merge flag to modify a specific post.

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

mergeway-cli update --type Post --id post-001 --file post-update.yaml --merge
```

--------------------------------

### Define a Data File with Numeric Identifier

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/schema-spec.html

Example of a data file where the identifier is an integer, valid when the schema marks the id field as an integer.

```yaml
id: 42
name: Numeric Identifier
```

--------------------------------

### Delete a user without confirmation

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/delete.html

Example of deleting a user object using the --yes flag to bypass the confirmation prompt.

```bash
mergeway-cli --yes delete --type User user-bob
```

```text
User user-bob deleted
```

--------------------------------

### mergeway-mcp

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/mcp.html

The mergeway-mcp command starts a read-only MCP server for repository inspection. It supports various flags to configure the repository root, transport mode, and entity access.

```APIDOC
## mergeway-mcp

### Description
Starts the Mergeway MCP server. This is a standalone binary that provides read-only access to repository data.

### Flags
- **--root** (string) - Optional - Root folder of the Mergeway repository (defaults to ".").
- **--transport** (string) - Optional - MCP transport: "stdio" or "http" (defaults to "stdio").
- **--http-listen** (string) - Optional - Listen address for HTTP transport (defaults to "127.0.0.1:8080").
- **--http-base-path** (string) - Optional - Base path for HTTP transport (defaults to "/"). Only valid with --transport=http.
- **--entity** (string) - Optional - Allow only the named exact entity. Repeat the flag to build an allow-list.

### Usage Examples
Start default stdio server:
`mergeway-mcp`

Start with custom root:
`mergeway-mcp --root examples/full`

Start with specific entities:
`mergeway-mcp --root examples/full --entity User --entity Post`

Start HTTP server:
`mergeway-mcp --root examples/full --transport=http`
```

--------------------------------

### Identify Baseline Commit

Source: https://mergewayhq.github.io/mergeway-cli/guides/communicate-changes-with-diff.html

Find the most recent commit before a specific time window to establish a stable starting point for comparisons.

```bash
BASELINE="$(git log -1 --before="7 days ago" --format="%H")"
printf 'Baseline commit: %s\n' "$BASELINE"
git show --stat --oneline --no-patch "$BASELINE"
```

--------------------------------

### List entities for a specific workspace

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/entity-list.html

Demonstrates listing entities for the 'examples/full' workspace and the resulting output format.

```bash
mergeway-cli --root examples/full entity list
```

```text
Comment
Post
Tag
User
```

--------------------------------

### Configure generic LSP launcher settings

Source: https://mergewayhq.github.io/mergeway-cli/guides/setup-mergeway-lsp-editors.html

Set the server command, arguments, supported filetypes, and root patterns for generic LSP client extensions.

```json
{
  "mergeway.server.command": "mergeway-lsp",
  "mergeway.server.args": [
    "--log-file",
    "/tmp/mergeway-lsp.log"
  ],
  "mergeway.server.filetypes": [
    "yaml",
    "json"
  ],
  "mergeway.server.rootPatterns": [
    "mergeway.yaml",
    "mergeway.yml"
  ]
}
```

--------------------------------

### Run mergeway-lsp from PATH

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/language-server.html

Execute the language server when the binary is available in the system PATH.

```bash
__
mergeway-lsp
```

--------------------------------

### Run mergeway-lsp from local source

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/language-server.html

Execute the language server binary directly from the local build directory.

```bash
__
./bin/mergeway-lsp
```

--------------------------------

### Create and initialize a new directory

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/init.html

Workflow for creating a new directory and initializing it as a Mergeway workspace.

```bash
mkdir blog-metadata
cd blog-metadata
mergeway-cli init
```

--------------------------------

### Create Entities Directory

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/workspace-setup.html

Prepare a directory for modular schema definitions.

```bash
mkdir -p entities
```

--------------------------------

### Basic entity show command syntax

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/entity-show.html

The standard command structure for displaying an entity's schema.

```bash
mergeway-cli [global flags] entity show <entity>
```

--------------------------------

### Basic mergeway-mcp execution

Source: https://mergewayhq.github.io/mergeway-cli/guides/use-mergeway-mcp-with-claude-and-codex.html

Run the server with a specified repository root.

```bash
mergeway-mcp --root /abs/path/to/repo
```

--------------------------------

### Get external-root path record

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/get.html

Retrieves a record located outside the current workspace root.

```bash
mergeway-cli --format yaml get --type Product ../secondary/products/widget.yaml
```

--------------------------------

### Build Mergeway from source

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/installation.html

Clone the repository and use the Makefile to compile all binaries locally.

```bash
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
```

--------------------------------

### Initialize Mergeway workspace

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/init.html

Basic syntax for initializing a Mergeway workspace in the current or specified directory.

```bash
mergeway-cli [global flags] init
```

--------------------------------

### Export Configuration Command Syntax

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/config-export.html

Basic command structure for exporting a specific type configuration.

```bash
mergeway-cli [global flags] config export --type <type>
```

--------------------------------

### Basic entity list command usage

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/entity-list.html

The standard syntax for listing all discovered entities using global flags.

```bash
mergeway-cli [global flags] entity list
```

--------------------------------

### mergeway-cli gen-erd

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/gen-erd.html

Generates an Entity Relationship Diagram (ERD) of the data model. Requires Graphviz (dot command) to be installed.

```APIDOC
## Command: mergeway-cli gen-erd

### Description
Generates a visual Entity Relationship Diagram (ERD) of your data model. This command inspects your configuration and uses Graphviz to produce the output image.

### Arguments
- **--path** (string) - Required - The path where the generated image will be saved. The file extension determines the output format (e.g., .png, .svg).

### Usage Examples

Generate a PNG image:
`mergeway-cli gen-erd --path schema.png`

Generate an SVG image:
`mergeway-cli gen-erd --path schema.svg`

### Requirements
The `dot` executable from Graphviz must be installed and available in your system's PATH.
```

--------------------------------

### Display CLI version in JSON format

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/version.html

Retrieve version metadata in a machine-readable JSON format.

```bash
mergeway-cli --format json version
```

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

--------------------------------

### Create command success output

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/create.html

Expected console output upon successful creation of an object.

```text
User user-bob created
```

--------------------------------

### Display CLI version information

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/version.html

Standard usage to retrieve the current CLI build metadata.

```bash
mergeway-cli [global flags] version
```

--------------------------------

### Configure Claude Desktop for mergeway-mcp

Source: https://mergewayhq.github.io/mergeway-cli/guides/use-mergeway-mcp-with-claude-and-codex.html

Add the server configuration to the claude_desktop_config.json file.

```json
{
  "mcpServers": {
    "mergeway": {
      "type": "stdio",
      "command": "mergeway-mcp",
      "args": [
        "--root",
        "/abs/path/to/repo"
      ],
      "env": {}
    }
  }
}
```

--------------------------------

### Explore Workspace Entities

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/workspace-setup.html

Verify the workspace configuration and entity definitions.

```bash
mergeway-cli entity list
mergeway-cli entity show Product
mergeway-cli list --type Product
mergeway-cli validate
```

--------------------------------

### Mergeway CLI create command syntax

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/create.html

General usage pattern for the create command with global flags and required parameters.

```bash
mergeway-cli [global flags] create --type <type> [--file path] [--id value]
```

--------------------------------

### Show entity in YAML format

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/entity-show.html

Displays the Post entity schema in YAML format using the --root and --format flags.

```bash
mergeway-cli --root examples/full --format yaml entity show Post
```

--------------------------------

### Configure VS Code workspace settings

Source: https://mergewayhq.github.io/mergeway-cli/guides/setup-mergeway-lsp-editors.html

Define the path to the binary and control server tracing within the workspace settings file.

```json
{
  "mergeway.lsp.path": "${workspaceFolder}/bin/mergeway-lsp",
  "mergeway.lsp.trace.server": "off"
}
```

--------------------------------

### List all included YAML files

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/files.html

Default command to display all YAML-backed files matched by entity include globs.

```bash
mergeway-cli files
```

```yaml
- type: Post
  file: data/posts/posts.yaml
- type: Tag
  file: data/tags/tag-product.yaml
```

--------------------------------

### Serve via HTTP

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/mcp.html

Configures the server to listen for MCP requests over HTTP.

```bash
mergeway-mcp --root examples/full --transport=http
```

--------------------------------

### Execute Mergeway CLI Commands

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/workspace-setup.html

Run basic CLI commands to list entities, show details, and validate the workspace configuration.

```bash
mergeway-cli entity list
mergeway-cli entity show Category
mergeway-cli list --type Category
mergeway-cli validate
```

--------------------------------

### Create JSON Data File

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/workspace-setup.html

Generate the JSON file containing product records.

```json
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
```

--------------------------------

### Custom HTTP Configuration

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/mcp.html

Sets a custom listen address and base path for the HTTP transport.

```bash
mergeway-mcp --root examples/full --transport=http --http-listen 127.0.0.1:9090 --http-base-path /mcp
```

--------------------------------

### Register Mergeway LSP in Neovim

Source: https://mergewayhq.github.io/mergeway-cli/guides/setup-mergeway-lsp-editors.html

Use lspconfig to define the server configuration and register it for Neovim.

```lua
local lspconfig = require("lspconfig")
local util = require("lspconfig.util")

lspconfig.mergeway_lsp = {
  default_config = {
    cmd = { "mergeway-lsp", "--log-file", "/tmp/mergeway-lsp.log" },
    filetypes = { "yaml", "json" },
    root_dir = util.root_pattern("mergeway.yaml", "mergeway.yml"),
    single_file_support = false,
  },
}

lspconfig.mergeway_lsp.setup({})
```

--------------------------------

### List command syntax

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/list.html

The basic command structure for listing objects with required type and optional filter flags.

```bash
mergeway-cli [global flags] list --type <type> [--filter key=value]
```

--------------------------------

### Default configuration file content

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/init.html

The default structure of the mergeway.yaml file generated by the init command.

```yaml
# mergeway-cli configuration
mergeway:
  version: 1

entities: {}
```

--------------------------------

### Create a Weekly Report File

Source: https://mergewayhq.github.io/mergeway-cli/guides/communicate-changes-with-diff.html

Combine baseline and current commit information with the semantic diff into a single markdown report file.

```bash
CURRENT="$(git rev-parse HEAD)"

{
  echo "# GrainBox weekly data update"
  echo
  echo "Baseline: $BASELINE"
  echo "Current:  $CURRENT"
  echo
  mergeway-diff "$BASELINE" HEAD
} > weekly-data-update.md
```

--------------------------------

### Fetch record as YAML

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/get.html

Retrieves a specific record and formats the output as YAML.

```bash
mergeway-cli --format yaml get --type Post post-001
```

--------------------------------

### Run hook manually

Source: https://mergewayhq.github.io/mergeway-cli/guides/setup-mergeway-pre-commit.html

Execute the configured hook against all tracked files to verify formatting.

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

--------------------------------

### Define Product Entity with JSONPath

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/workspace-setup.html

Create a schema file that pulls data from a JSON file using a selector.

```yaml
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
```

--------------------------------

### Run config lint command

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/config-lint.html

Executes the linting process to validate configuration files.

```bash
mergeway-cli [global flags] config lint
```

```bash
mergeway-cli config lint
```

--------------------------------

### List all posts

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/list.html

Retrieve all identifiers for the Post type within the current workspace.

```bash
mergeway-cli list --type Post
```

```text
post-001
```

--------------------------------

### Verify External Data Integration

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/workspace-setup.html

Run commands to verify that the entity correctly reads from the external data files.

```bash
mergeway-cli list --type Category
mergeway-cli get --type Category beverages
mergeway-cli validate
```

--------------------------------

### Configure Codex MCP server

Source: https://mergewayhq.github.io/mergeway-cli/guides/use-mergeway-mcp-with-claude-and-codex.html

Define the server in the Codex configuration file.

```toml
[mcp_servers.mergeway]
command = "mergeway-mcp"
args = ["--root", "/abs/path/to/repo"]
```

--------------------------------

### Add mergeway-mcp to Codex

Source: https://mergewayhq.github.io/mergeway-cli/guides/use-mergeway-mcp-with-claude-and-codex.html

Register the server using the Codex CLI.

```bash
codex mcp add mergeway -- mergeway-mcp --root /abs/path/to/repo
```

--------------------------------

### Mergeway MCP Server Usage

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/mcp.html

Basic command structure for the mergeway-mcp binary.

```bash
mergeway-mcp [flags]
```

--------------------------------

### Inspect entities and validate data

Source: https://mergewayhq.github.io/mergeway-cli/guides/example-repo.html

Commands to list entities, inspect schemas, and perform data validation against the configuration.

```bash
mergeway-cli entity list          # list all entity types
mergeway-cli entity show User     # inspect the User schema
mergeway-cli list --type Post     # list all post records
mergeway-cli get --type User 1    # fetch a single user by id
mergeway-cli validate             # validate schemas, data and references
```

--------------------------------

### Specify Repository Root

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/mcp.html

Points the MCP server to a specific repository directory.

```bash
mergeway-mcp --root examples/full
```

--------------------------------

### Configure .pre-commit-config.yaml

Source: https://mergewayhq.github.io/mergeway-cli/guides/setup-mergeway-pre-commit.html

Define a local hook in your repository to execute mergeway-cli fmt on specific data files.

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

--------------------------------

### Configure Codex MCP with entity filters

Source: https://mergewayhq.github.io/mergeway-cli/guides/use-mergeway-mcp-with-claude-and-codex.html

Define the server in the Codex configuration file with specific entity filters.

```toml
[mcp_servers.mergeway]
command = "mergeway-mcp"
args = ["--root", "/abs/path/to/repo", "--entity", "User", "--entity", "Post"]
```

--------------------------------

### Define Inline Entities

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/workspace-setup.html

Configure the mergeway.yaml file with entity definitions and initial data records.

```yaml
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
```

--------------------------------

### mergeway-cli version

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/version.html

Displays the CLI build metadata including semantic version, commit, and build date.

```APIDOC
## mergeway-cli version

### Description
Displays the CLI build metadata (semantic version, commit, build date). This command does not modify workspace files and ignores global flags like --root.

### Usage
`mergeway-cli [global flags] version`

### Options
- `--format json` (Optional) - Returns the version information in JSON format.

### Response Example (JSON)
{
  "version": "0.8.0",
  "commit": "a713be5",
  "buildDate": "2025-10-22T18:25:03Z"
}
```

--------------------------------

### Export All Entities

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/export.html

Exports every entity defined in the workspace to the terminal in the default YAML format.

```bash
mergeway-cli export
```

--------------------------------

### Configure mergeway-lsp logging

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/language-server.html

Options for debugging the language server by directing logs to stderr or a specific file.

```bash
__
mergeway-lsp --log-stderr --log-level=debug
```

```bash
__
mergeway-lsp --log-file /tmp/mergeway-lsp.log --log-level=debug
```

--------------------------------

### mergeway-cli create

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/create.html

Creates a new object file that conforms to an entity definition.

```APIDOC
## mergeway-cli create

### Description
Creates a new object file that conforms to an entity definition. The command writes the object within the workspace root.

### Usage
`mergeway-cli [global flags] create --type <type> [--file path] [--id value]`

### Parameters
- **--type** (string) - Required - Type identifier to create.
- **--file** (string) - Optional - Path to a YAML/JSON payload. If omitted, data is read from STDIN.
- **--id** (string) - Optional - Identifier override for field-based identifiers. Required when the entity uses `identifier: $path`, in which case the value must be the workspace-relative file path to create.

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

mergeway-cli create --type User --file user.yaml --id user-bob
```
```

--------------------------------

### Define Workspace Entry Configuration

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/schema-spec.html

The primary entry file specifies the schema version and glob patterns for loading entity definitions.

```yaml
__
mergeway:
  version: 1

include:
  - entities/*.yaml
```

--------------------------------

### Export Workspace Snapshot

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/workspace-setup.html

Export the entire workspace dataset to a single JSON file.

```bash
mergeway-cli export --format json --output market-snapshot.json
cat market-snapshot.json
```

--------------------------------

### Add mergeway-mcp to Claude Code

Source: https://mergewayhq.github.io/mergeway-cli/guides/use-mergeway-mcp-with-claude-and-codex.html

Register the server using the Claude CLI.

```bash
claude mcp add --transport stdio mergeway -- mergeway-mcp --root /abs/path/to/repo
```

--------------------------------

### Request JSON output for files

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/files.html

Format the output of the files command as JSON for programmatic consumption.

```bash
mergeway-cli --format json files --type Tag
```

--------------------------------

### Run Mergeway CLI via Docker

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/installation.html

Execute the CLI in a containerized environment, optionally mounting the current directory for workspace access.

```bash
docker run --rm ghcr.io/mergewayhq/mergeway-cli version
```

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

--------------------------------

### Mergeway diff command syntax

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/diff.html

The basic usage patterns for the mergeway-diff binary.

```bash
mergeway-diff [flags]
mergeway-diff [flags] <left>
mergeway-diff [flags] <left> <right>
mergeway-diff --format json [<left>] [<right>]
```

--------------------------------

### Validate command syntax

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/validate.html

The base command structure for running validation with optional phases and flags.

```bash
mergeway-cli [global flags] validate [--phase format|schema|references]... [--fail-fast]
```

--------------------------------

### Compare revision against working tree

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/diff.html

Compares an earlier revision against the full current working tree.

```bash
mergeway-diff HEAD~1
```

--------------------------------

### Successful validation output

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/config-lint.html

The expected output when the configuration is valid.

```text
configuration valid
```

--------------------------------

### Group storage containers

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/files.html

Collapse directories containing multiple objects into their wildcard path representation.

```bash
mergeway-cli files --group
```

```yaml
- type: Post
  file: data/posts/posts.yaml
- type: User
  file: data/users/*.yaml
```

--------------------------------

### Mergeway CLI files command syntax

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/files.html

Basic usage pattern for the files command including global flags and optional parameters.

```bash
mergeway-cli [global flags] files [--type <type>] [--group]
```

--------------------------------

### Compare HEAD against local changes

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/diff.html

Compares the current HEAD data against unstaged local changes.

```bash
mergeway-diff
```

--------------------------------

### Configure Mergeway formatting workflow

Source: https://mergewayhq.github.io/mergeway-cli/guides/setup-mergeway-github.html

Create this GitHub Actions workflow to enforce consistent formatting on pull requests and pushes. Adjust the paths filter if your data resides in non-YAML files.

```yaml
name: Mergeway Formatting

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

jobs:
  mergeway-cli-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: mergeway-cli fmt --lint
```

--------------------------------

### Update command syntax

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/update.html

The basic command structure for updating an object using the Mergeway CLI.

```bash
mergeway-cli [global flags] update --type <type> --id <id> [--file path] [--merge]
```

--------------------------------

### Mergeway Entity Configuration with JSONPath

Source: https://mergewayhq.github.io/mergeway-cli/guides/json-schema.html

Configuration snippet showing how to define an entity that uses a JSONPath selector to extract items from a source file.

```yaml
mergeway:
  version: 1

entities:
  User:
    identifier: id
    fields:
      id: string
      name: string
    include:
      - path: data/users.json
        selector: "$.users[*]"
```

--------------------------------

### List inherited entities

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/list.html

Query a parent type to include objects from all descendant types, optionally specifying a root directory.

```bash
mergeway-cli --root examples/inheritance list --type Animal
```

```text
dog-1
```

--------------------------------

### Define a JSON Schema for a Customer entity

Source: https://mergewayhq.github.io/mergeway-cli/guides/json-schema.html

Create a schema file to define required fields, enumerations, and nested object structures for customer records.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "description": "Customer metadata defined with JSON Schema",
  "required": ["id", "name", "tier"],
  "properties": {
    "id": { "type": "string" },
    "name": { "type": "string" },
    "tier": {
      "oneOf": [
        { "const": "trial" },
        { "const": "starter" },
        { "const": "enterprise" }
      ]
    },
    "contacts": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["label", "email"],
        "properties": {
          "label": { "type": "string" },
          "email": { "type": "string", "format": "email" }
        }
      }
    }
  }
}
```

--------------------------------

### mergeway-cli entity list

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/entity-list.html

Lists all entities discovered from the configuration. Entities are returned in alphabetical order.

```APIDOC
## mergeway-cli entity list

### Description
Lists every entity discovered by Mergeway from your configuration. Entities are displayed in alphabetical order.

### Usage
`mergeway-cli [global flags] entity list`

### Parameters
- **--root** (string) - Optional - Specifies the workspace directory to inspect if different from the current directory.

### Example
`mergeway-cli --root examples/full entity list`

### Output
Returns a list of entity names, for example:
- Comment
- Post
- Tag
- User
```

--------------------------------

### Validate workspace

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/validate.html

Run validation on the current workspace from the root directory.

```bash
mergeway-cli validate
```

--------------------------------

### Generate ERD with Mergeway CLI

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/gen-erd.html

Basic syntax for generating an ERD file using the specified output path.

```bash
mergeway-cli gen-erd --path <output-file>
```

--------------------------------

### Include External Schemas in Main Config

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/workspace-setup.html

Update the main configuration to include all schema files in the entities directory.

```yaml
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
```

--------------------------------

### Delete command syntax

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/delete.html

The basic syntax for the delete command requiring a type and an identifier.

```bash
mergeway-cli [global flags] delete --type <type> <id>
```

--------------------------------

### Mergeway CLI Export Command Syntax

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/export.html

The base syntax for the export command, including global flags and optional entity filtering.

```bash
mergeway-cli [global flags] export [--output <path>] [entity...]
```

--------------------------------

### Implement Entity Inheritance

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/schema-spec.html

Use the extends keyword to inherit fields from a parent entity definition.

```yaml
__
mergeway:
  version: 1

entities:
  Content:
    identifier: id
    fields:
      id: string
      title:
        type: string
        required: true
  Post:
    extends: Content
    identifier: id
    include:
      - data/posts/*.yaml
    fields:
      body: string
```

--------------------------------

### mergeway-cli entity show

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/entity-show.html

Displays the normalized schema for a given entity. Supports output formatting and workspace root specification.

```APIDOC
## mergeway-cli entity show

### Description
Prints the normalized schema for a given entity. For inherited entities, the output shows the effective flattened schema, including inherited fields and the inheritance chain.

### Usage
`mergeway-cli [global flags] entity show <entity>`

### Parameters
- **entity** (string) - Required - The name of the entity to display.

### Global Flags
- **--format** (string) - Optional - Specifies the output format (e.g., json, yaml).
- **--root** (string) - Optional - Specifies the workspace root directory.

### Example
`mergeway-cli --root examples/full --format yaml entity show Post`
```

--------------------------------

### Move Data to External YAML Files

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/workspace-setup.html

Extract data records into a dedicated YAML file to support larger datasets.

```bash
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
```

--------------------------------

### Validate and Diff

Source: https://mergewayhq.github.io/mergeway-cli/guides/communicate-changes-with-diff.html

Ensure the workspace is valid before generating a report to avoid including repository errors in the output.

```bash
mergeway-cli validate
mergeway-diff "$BASELINE" HEAD
```

--------------------------------

### Update command output

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/update.html

The expected console output after a successful update operation.

```text
Post post-001 updated
```

--------------------------------

### Emit machine-readable diff output

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/diff.html

Generates JSON output for the comparison between two revisions for use in automation.

```bash
mergeway-diff --format json HEAD~1 HEAD
```

--------------------------------

### Filter Entities

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/mcp.html

Restricts the exposed entities to a specific allow-list.

```bash
mergeway-mcp --root examples/full --entity User --entity Post
```

--------------------------------

### Export Specific Entities to JSON File

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/export.html

Exports only the specified entities to a JSON file using the --format and --output flags.

```bash
mergeway-cli --format json export --output snapshot.json User Post
```

--------------------------------

### mergeway-cli files

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/files.html

Lists included YAML data files matched by entity include globs.

```APIDOC
## mergeway-cli files

### Description
Lists included YAML data files or grouped storage containers, together with their entity types. This command only lists YAML-backed files matched by entity include globs; inline records and JSON files are excluded.

### Usage
`mergeway-cli [global flags] files [--type <type>] [--group]`

### Flags
- **--type** (string) - Optional - Restrict output to one entity type.
- **--group** (boolean) - Optional - Collapse one-object-per-file directories to their wildcard path.

### Examples
List every included YAML data file:
`mergeway-cli files`

Request JSON output:
`mergeway-cli --format json files --type Tag`

Show storage containers instead of every concrete file:
`mergeway-cli files --group`
```

--------------------------------

### mergeway-cli validate

Source: https://mergewayhq.github.io/mergeway-cli/cli-reference/validate.html

Validates the current workspace by checking schemas, records, and references.

```APIDOC
## CLI Command: mergeway-cli validate

### Description
Check schemas, records, and references, emitting formatted errors when something is wrong. Run the command from the workspace root or use the --root flag.

### Usage
`mergeway-cli [global flags] validate [--phase format|schema|references]... [--fail-fast]`

### Flags
- **--phase** (string) - Optional - Repeat to run a subset of phases. By default all phases run (format, schema, then references). When requesting the references phase, the schema phase is automatically included.
- **--fail-fast** (boolean) - Optional - Stop after the first error. Defaults to the global --fail-fast flag.
- **--format** (string) - Optional - Set to 'json' for machine-readable output.

### Example
`mergeway-cli validate --format json`
```

--------------------------------

### Define entities with inline data

Source: https://mergewayhq.github.io/mergeway-cli/getting-started/schema-spec.html

Configure entities using both external file globs and inline data records. Inline records are read-only and overridden by file-based data if identifiers collide.

```yaml
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
```
Tokens:
Raw