CLI

Installation#

go install github.com/openinherit/inherit-cli@latest

Or build from source:

git clone https://github.com/openinherit/standard.git
cd standard/packages/cli
go build -o inherit .

Requires Go 1.21 or later. The binary is self-contained — schemas are compiled in, no runtime dependencies.

Quick start#

# Scaffold a new estate document (interactive — asks 5 questions)
inherit init

# Validate it
inherit validate estate.json

# Validate with JSON output (for CI pipelines)
inherit validate estate.json --json

# Check referential integrity (Level 2)
inherit validate estate.json --level 2

# Lint for best-practice issues
inherit lint estate.json

# Compare two versions of a document
inherit diff old-estate.json new-estate.json

Commands#

Disclaimer: Validation checks data structure, not legal accuracy. Do not rely on validation results as the sole basis for legal or financial decisions.

inherit validate <file>#

Validates an INHERIT document against the bundled v3 JSON Schema.

Auto-detects estate or catalogue mode from the document’s $schema field. Use --mode to override.

Flags:

Conformance levels:

• Level 1 (default) — JSON Schema validation. Checks required fields, types, enum values, format assertions, and rejects unknown properties.
• Level 2 — everything in Level 1, plus referential integrity. All UUID cross-references (e.g. testatorPersonId, beneficiaryId, personId) must resolve to entities present in the document.

Exit codes:

Example — human-readable output:

File:   estate.json
Mode:   estate
Level:  1
Result: VALID

Note: Validation results are informational only. They verify schema conformance
and data structure, not legal accuracy, completeness, or suitability for any
purpose. Always consult a qualified legal or financial professional.

Example — JSON output:

{
  "valid": true,
  "schemaMode": "estate",
  "conformanceLevel": 1,
  "file": "estate.json",
  "errors": [],
  "errorCount": 0,
  "disclaimer": "Validation results are informational only..."
}

inherit init#

Scaffolds a realistic INHERIT estate document. In v7.0.0, init is interactive by default — it asks five questions with sensible defaults, then writes a ready-to-edit document that passes both Level 1 and Level 2 validation out of the box.

Interactive mode (default):

The CLI prompts for:

1. Document type — estate or catalogue (default: estate)
2. Jurisdiction — one of the supported jurisdictions, or “none” (default: england-wales)
3. Testator name — given name and family name (default: Jane Smith)
4. Include example assets — yes/no (default: yes)
5. Output filename — where to write the document (default: estate.json)

Supported jurisdictions:

{{< jurisdiction-list >}}

Flags:

Example — interactive mode:

inherit init

After answering the prompts, the CLI writes the document and displays a banner:

Created estate.json (England and Wales, Level 1)

Next steps:
  inherit validate estate.json       Validate your document
  inherit init --full                 Generate a full Level 2 example
  inherit lint estate.json            Check for best-practice issues
  https://dev.openinherit.org/docs/   Full documentation

The generated document includes realistic content: three people (testator, executor, and beneficiary), a property with address, a bank account, a personal possession, and a bequest.

Example — non-interactive mode (for CI):

inherit init --non-interactive --jurisdiction scotland --testator "Angus McTavish" --output estate.json

Example — full Level 2 document:

inherit init --full

Generates a comprehensive document with a spouse, marriage relationship, trust, digital assets, insurance policy, residuary bequest, and multiple bequests — useful for exploring the full scope of the standard.

Example — catalogue document:

inherit init --catalogue > my-catalogue.json

Generates a simpler document with just the catalogue schema reference, asset and valuation arrays, and provenance metadata.

inherit lint <file>#

Checks a document for best-practice issues beyond schema compliance. A document can be schema-valid but still have quality problems — lint catches those.

Flags:

Rules checked:

Exit codes:

Example — human-readable output:

⚠ empty-description: /assets/0/description description field is present but empty
⚠ missing-valuation: /assets/0/estimatedValue asset "11111111-..." has estimatedValue
  but no entry in valuations for this id

2 warning(s) (2 rules triggered)

Example — JSON output:

{
  "warnings": [
    {
      "rule": "empty-description",
      "path": "/assets/0/description",
      "message": "description field is present but empty"
    },
    {
      "rule": "missing-valuation",
      "path": "/assets/0/estimatedValue",
      "message": "asset \"11111111-...\" has estimatedValue but no entry in valuations for this id"
    }
  ],
  "total": 2
}

inherit diff <old.json> <new.json>#

Compares two INHERIT documents and shows what has changed. Entities are matched by their id field, not by array position — so reordering arrays does not produce false diffs.

Metadata fields (exportedAt, generator, lastModifiedAt, applicationState, conformance) are ignored by default. Use --include-metadata to include them.

Flags:

Output levels:

• summary — one-line count of changes (e.g. 1 people modified)
• detail — per-entity listing with changed fields and old/new values
• patch — RFC 6902 JSON Patch array (machine-readable)

Exit codes:

Example — summary:

1 people modified

Example — detail:

~ people "Jane Davies" (id: dd3a097f-054e-40ee-8a7c-7b4017dbc5c2)
    familyName: "Surname" → "Davies"
    givenName: "Given" → "Jane"

Example — JSON patch:

[
  { "op": "replace", "path": "/familyName", "value": "Davies" },
  { "op": "replace", "path": "/givenName", "value": "Jane" }
]

inherit version#

Prints version and schema information:

inherit-cli v7.0.0
schema: INHERIT v3 (Draft 2020-12)

Examples#

CI/CD pipeline validation#

#!/bin/bash
set -e

for file in documents/*.json; do
  inherit validate "$file" --quiet --level 2
  echo "  $file — valid"
done

Validate all files with JSON output#

inherit validate estate.json --json | jq '.valid'

Scaffold, edit, validate workflow#

# Scaffold interactively — answers five questions, writes estate.json
inherit init

# Edit the document (add people, assets, bequests, etc.)
# ...

# Validate your changes
inherit validate estate.json --level 2

# Check for best-practice issues
inherit lint estate.json

Pre-commit hook#

#!/bin/bash
# .git/hooks/pre-commit
for file in $(git diff --cached --name-only --diff-filter=ACM -- '*.json'); do
  if inherit validate "$file" --quiet 2>/dev/null; then
    true  # valid or not an INHERIT doc
  else
    echo "INHERIT validation failed: $file"
    exit 1
  fi
done

Compare document versions#

# Quick summary
inherit diff v1.json v2.json

# Detailed field-level changes
inherit diff v1.json v2.json --level detail

# Machine-readable JSON Patch
inherit diff v1.json v2.json --level patch --json