CLI tasks on Mergeway

Create, inspect, update, and delete records

Mon, 01 Jan 0001 00:00:00 +0000

Create, inspect, update, and delete records

Work in a clean Git branch and confirm the target entity has a writable one-record-per-file include. This example uses User in examples/full; use a copy so the destructive final step cannot affect source data.

cp -R examples/full /tmp/mergeway-records
mergeway-cli --root /tmp/mergeway-records create --type User --id user-carol <<'YAML'
name: Carol Example
email: carol@example.com
roles: [author]
YAML

The command prints User user-carol created and writes data/users/user-carol.yaml. Inspect it:

Validate configuration or a repository

Mon, 01 Jan 0001 00:00:00 +0000

Validate configuration or a repository

Use configuration lint for fast feedback while editing mergeway.yaml or included entity files:

mergeway-cli config lint

It proves that configuration parses and normalizes, but it does not open record files. Before review or export, validate the full repository:

mergeway-cli validate

For machine-readable diagnostics and an early stop:

mergeway-cli --format json --fail-fast validate

To isolate a problem, repeat --phase as needed:

mergeway-cli validate --phase format
mergeway-cli validate --phase schema --phase references

Reference validation automatically includes schema validation. Any reported validation error exits 1, so CI can use the command directly. See the validation model and validate reference.

Split schemas and records across files

Mon, 01 Jan 0001 00:00:00 +0000

Split schemas and records across files

Create predictable directories from the repository root:

mkdir -p entities data/users

Move each entity into a v1 configuration fragment such as entities/User.yaml, and make the entry file include those fragments:

mergeway:
 version: 1
include:
 - entities/*.yaml

In the User fragment, point the entity at its record files:

mergeway:
 version: 1
entities:
 User:
 identifier: id
 include:
 - data/users/*.yaml
 fields:
 id: {type: string, required: true}
 name: {type: string, required: true}

Write one record per file, for example data/users/user-alice.yaml, then verify both layers:

Validate a repository in GitHub Actions

Mon, 01 Jan 0001 00:00:00 +0000

Validate a repository in GitHub Actions

Commit this workflow as .github/workflows/mergeway.yml. It pins v0.10.0 rather than following latest and verifies the downloaded archive before running validation.

name: Mergeway
on:
 pull_request:
 push:
 branches: [main]

jobs:
 validate:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Install Mergeway CLI v0.10.0
 shell: bash
 run: |
 curl -fsSLO https://github.com/mergewayhq/mergeway-cli/releases/download/v0.10.0/mergeway-cli_Linux_x86_64.tar.gz
 tar -xzf mergeway-cli_Linux_x86_64.tar.gz mergeway-cli
 sudo install -m 0755 mergeway-cli /usr/local/bin/mergeway-cli
 mergeway-cli version
 - name: Validate configuration and repository
 run: |
 mergeway-cli config lint
 mergeway-cli validate

For stronger supply-chain controls, add the release checksum published by your release process and verify it before extraction. Update the pinned version deliberately and review its release notes. Validation exits 1 for repository errors, so no output parsing is needed. Add fmt --lint when canonical formatting is also required.

Enforce canonical formatting with pre-commit

Mon, 01 Jan 0001 00:00:00 +0000

Enforce canonical formatting with pre-commit

Install mergeway-cli and pre-commit, then add .pre-commit-config.yaml:

repos:
 - repo: local
 hooks:
 - id: mergeway-fmt
 name: Canonicalize Mergeway records
 entry: mergeway-cli fmt
 language: system
 pass_filenames: false
 files: ^data/.*\.(ya?ml)$

pass_filenames: false lets Mergeway derive its complete configured data set instead of receiving an arbitrary staged subset. Install and test the hook:

pre-commit install
pre-commit run mergeway-fmt --all-files
git diff --check

The default formatter rewrites files; review and stage those changes. If a non-mutating local policy is preferred, set entry: mergeway-cli fmt --lint. See the fmt modes and CI formatting guide.

Export repository data

Mon, 01 Jan 0001 00:00:00 +0000

Export repository data

Validate first so the snapshot is not built from known-invalid records:

mergeway-cli validate
mergeway-cli --format json export --output repository.json

To limit the output, list entity names after export:

mergeway-cli --format json export User Post --output authors-and-posts.json

The document maps each entity to an ID-sorted record array. Entity ordering in JSON objects is not a semantic contract; consumers should address keys by name. --output replaces an existing destination, so use a temporary path when reviewing:

Generate an entity-relationship diagram

Mon, 01 Jan 0001 00:00:00 +0000

Generate an entity-relationship diagram

Install Graphviz so its dot executable is on PATH, then validate and render an SVG:

dot -V
mergeway-cli config lint
mergeway-cli gen-erd --path schema.svg

The extension controls Graphviz’s output format. SVG works well in documentation and code review; PNG is convenient for presentations. Regenerate the file whenever definitions change.

The diagram shows normalized entities, direct fields, configured data paths, reference edges, and inheritance. It does not show individual records or validate them. Consult gen-erd for errors and the entity specification for model semantics.

Format safely in CI

Mon, 01 Jan 0001 00:00:00 +0000

Format safely in CI

Use lint mode in automation; plain fmt rewrites files and can conceal the failure you meant to detect.

mergeway-cli fmt --lint

A clean repository exits 0 without output. When files differ, their paths are printed and the command exits 1 without modifying them. Contributors can fix the same failure locally:

mergeway-cli fmt
git diff --check
mergeway-cli fmt --lint

To inspect a single file without writing it, use --stdout and do not combine it with --lint or --in-place:

Troubleshoot the CLI

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshoot the CLI

The repository is not found

Run commands from the directory containing mergeway.yaml, or pass --root before the command. Use --config when the entry file has another path. The CLI does not use the LSP client’s workspace-folder negotiation.

Configuration does not load

Run mergeway-cli config lint before full validation. Check include paths relative to the file that declares them, entity names, inheritance cycles, and mutually exclusive fields/json_schema members.

Validation fails

Run mergeway-cli validate without --fail-fast to collect all errors, then isolate format, schema, or references with repeated --phase flags. The validation model explains why a later phase waits for earlier phases.