CLI Reference

• 1: morphir ir verify
• 2: Management Commands
• 3: Troubleshooting

dotnet tool install -g Morphir.CLI

dotnet tool install Morphir.CLI

morphir --help
morphir ir --help
morphir ir verify --help

# Validate a single file with auto-detection
morphir ir verify path/to/morphir-ir.json

# Validate with explicit schema version
morphir ir verify --schema-version 3 path/to/morphir-ir.json

# Get JSON output for CI/CD
morphir ir verify --json path/to/morphir-ir.json

# Quiet mode (only errors)
morphir ir verify --quiet path/to/morphir-ir.json

1 - morphir ir verify

morphir ir verify

Validate Morphir IR JSON files against the official JSON schemas for format versions 1, 2, and 3.

Synopsis

morphir ir verify <file-path> [options]

Description

The morphir ir verify command validates a Morphir IR JSON file against the appropriate schema specification. The command automatically detects the schema version from the file content, or you can explicitly specify the version to use.

This command is useful for:

• Catching structural errors before IR files are used by other tools
• Validating generated IR from Morphir compilers
• CI/CD integration to ensure IR quality
• Debugging IR issues with detailed error messages

Arguments

<file-path>

Required. Path to the Morphir IR JSON file to validate.

• Supports absolute and relative paths
• File must exist and be readable
• File must contain valid JSON

Examples:

morphir ir verify morphir-ir.json
morphir ir verify ../output/morphir-ir.json
morphir ir verify /absolute/path/to/morphir-ir.json

Options

--schema-version <version>

Explicitly specify the schema version to validate against.

• Valid values: 1, 2, or 3
• Default: Auto-detected from file content
• Use when: Testing version-specific compatibility or overriding auto-detection

Examples:

# Validate against v3 schema regardless of file content
morphir ir verify --schema-version 3 morphir-ir.json

# Test if a v2 IR file is compatible with v3 schema
morphir ir verify --schema-version 3 morphir-ir-v2.json

--json

Output validation results in JSON format instead of human-readable text.

• Default: Human-readable output
• Use when: Parsing results in CI/CD, scripts, or other tools
• Output: Structured JSON with validation details

JSON Output Format:

{
  "IsValid": true,
  "SchemaVersion": "3",
  "DetectionMethod": "auto",
  "FilePath": "/path/to/morphir-ir.json",
  "Errors": [],
  "Timestamp": "2025-12-15T10:30:00Z"
}

For invalid IR:

{
  "IsValid": false,
  "SchemaVersion": "3",
  "DetectionMethod": "auto",
  "FilePath": "/path/to/morphir-ir.json",
  "Errors": [
    {
      "Path": "$.distribution[3]",
      "Message": "Required properties [\"formatVersion\"] are not present",
      "Expected": "required property",
      "Found": "undefined (missing)",
      "Line": null,
      "Column": null
    }
  ],
  "Timestamp": "2025-12-15T10:30:00Z"
}

Example:

# Get JSON output for parsing
morphir ir verify --json morphir-ir.json

# Use in scripts
RESULT=$(morphir ir verify --json morphir-ir.json)
echo $RESULT | jq '.IsValid'

--quiet

Suppress all output except for errors.

• Default: Show detailed output
• Use when: Running in CI/CD pipelines where you only care about failures
• Exit code: Still returns 0 (success) or 1 (failure)

Examples:

# Quiet mode - only shows output if validation fails
morphir ir verify --quiet morphir-ir.json

# Use in CI/CD
if morphir ir verify --quiet morphir-ir.json; then
  echo "IR is valid"
else
  echo "IR validation failed"
  exit 1
fi

Exit Codes

Output

Human-Readable Output (Default)

Valid IR:

Validation Result: ✓ VALID
File: /path/to/morphir-ir.json
Schema Version: v3 (auto)
Timestamp: 2025-12-15 10:30:00 UTC

No validation errors found.

Invalid IR:

Validation Result: ✗ INVALID
File: /path/to/morphir-ir.json
Schema Version: v3 (auto)
Timestamp: 2025-12-15 10:30:00 UTC

Found 2 validation error(s):

  Path: $.distribution[3]
  Message: Required properties ["formatVersion"] are not present
  Expected: required property
  Found: undefined (missing)

  Path: $.distribution[3].modules[0].name
  Message: Value is "string" but should be "array"
  Expected: array
  Found: string

JSON Output

See the --json option above for the JSON output format specification.

Schema Version Detection

The command automatically detects the schema version by analyzing the IR file structure:

• v1: Detected by presence of v1-specific structure
• v2: Detected by "formatVersion": 2 field
• v3: Detected by "formatVersion": 3 field

Detection Method in Output:

• auto: Version was automatically detected
• manual: Version was explicitly specified via --schema-version

Examples

Basic Validation

Validate a single IR file with auto-detection:

morphir ir verify morphir-ir.json

Explicit Version

Validate against a specific schema version:

morphir ir verify --schema-version 3 morphir-ir.json

CI/CD Integration

Validate IR in a GitHub Actions workflow:

- name: Validate Morphir IR
  run: |
    dotnet morphir ir verify --json morphir-ir.json > validation-result.json
    if [ $? -ne 0 ]; then
      cat validation-result.json
      exit 1
    fi

Script with Error Handling

#!/bin/bash
set -e

echo "Validating Morphir IR files..."

for file in output/*.json; do
  echo "Validating $file..."
  if morphir ir verify --quiet "$file"; then
    echo "✓ $file is valid"
  else
    echo "✗ $file is invalid"
    morphir ir verify "$file"  # Show detailed errors
    exit 1
  fi
done

echo "All IR files are valid!"

JSON Output Parsing

Parse JSON output with jq:

# Check if valid
morphir ir verify --json morphir-ir.json | jq '.IsValid'

# Get error count
morphir ir verify --json morphir-ir.json | jq '.Errors | length'

# Extract error messages
morphir ir verify --json morphir-ir.json | jq '.Errors[].Message'

# Get schema version used
morphir ir verify --json morphir-ir.json | jq '.SchemaVersion'

Common Error Messages

File Not Found

Error: File does not exist: path/to/file.json

Solution: Check the file path and ensure the file exists.

Malformed JSON

Validation Result: ✗ INVALID

Found 1 validation error(s):

  Path: $
  Message: Malformed JSON: 'i' is an invalid start of a value. LineNumber: 6 | BytePositionInLine: 4.
  Expected: Valid JSON
  Found: Invalid JSON syntax

Solution: Fix the JSON syntax error. The error message includes the line and byte position.

Missing Required Field

Path: $.distribution
Message: Required properties ["formatVersion"] are not present
Expected: required property
Found: undefined (missing)

Solution: Add the missing formatVersion field to your IR file.

Type Mismatch

Path: $.distribution[3].modules[0].name
Message: Value is "string" but should be "array"
Expected: array
Found: string

Solution: Change the field type to match the schema requirement (in this case, name should be an array, not a string).

Troubleshooting

Schema Version Not Detected

If auto-detection fails or detects the wrong version:

1. Check the formatVersion field in your JSON (for v2/v3)
2. Use --schema-version explicitly to override auto-detection
3. Verify JSON structure matches the expected schema version

Performance Issues

For large IR files (>1MB):

• Validation may take several seconds
• Consider using --quiet mode in CI/CD to reduce output overhead
• (Phase 2 will include performance optimizations for batch processing)

False Positives

If validation fails but you believe the IR is correct:

1. Check schema version - ensure you’re validating against the correct version
2. Review error messages - they include expected vs. found values
3. Consult schema documentation - see Schema Specifications
4. Report an issue - if you believe the schema or validator has a bug

Related Commands

• morphir ir detect-version (Phase 2) - Detect schema version without validation
• morphir ir migrate (Phase 3) - Migrate IR between schema versions

See Also

• Schema Specifications - Complete IR schema documentation
• Troubleshooting Guide - Solutions to common issues
• CI/CD Integration Guide (coming soon)

2 - Management Commands

Overview

The Morphir CLI provides commands to manage distributions, tools, and extensions with support for:

• Global-first installation (in OS config directory like ~/.config/morphir or ~/.morphir)
• Local overrides (per-project in .morphir/ directory)
• Platform-specific artifacts using .NET Runtime Identifiers (e.g., linux-x64, win-x64, osx-arm64)

Dist Commands

Manage core Morphir distributions.

dist list

List installed distributions.

morphir dist list [options]

Options:

• --platform <rid>: Platform Runtime Identifier (defaults to current platform)
• --local: List local (project) installations only

Example:

# List all distributions for current platform
morphir dist list

# List distributions for a specific platform
morphir dist list --platform linux-x64

# List project-local distributions
morphir dist list --local

dist install

Install a distribution from a URL.

morphir dist install <url> <version> [options]

Arguments:

• <url>: Source URL to download the distribution from
• <version>: Version string (e.g., 1.0.0, 2.1.3-beta)

Options:

• --platform <rid>: Platform Runtime Identifier (defaults to current platform)
• --local: Install locally (project-specific)

Example:

# Install globally
morphir dist install https://example.com/morphir-dist.tar.gz 1.0.0

# Install locally for project
morphir dist install https://example.com/morphir-dist.tar.gz 1.0.0 --local

# Install for specific platform
morphir dist install https://example.com/morphir-dist.tar.gz 1.0.0 --platform linux-x64

dist use

Set the active distribution version.

morphir dist use <version> [options]

Arguments:

• <version>: Version to activate

Options:

• --platform <rid>: Platform Runtime Identifier (defaults to current platform)
• --local: Set in local (project) scope

Example:

# Set global active version
morphir dist use 1.0.0

# Set local active version for current project
morphir dist use 2.0.0 --local

Resolution: Local selection takes precedence over global when both are set.

dist remove

Remove an installed distribution.

morphir dist remove <version> [options]

Arguments:

• <version>: Version to remove

Options:

• --platform <rid>: Platform Runtime Identifier (defaults to current platform)
• --local: Remove from local (project) scope

Example:

morphir dist remove 1.0.0
morphir dist remove 1.0.0 --local

dist which

Show the currently active distribution.

morphir dist which [options]

Options:

• --platform <rid>: Platform Runtime Identifier (defaults to current platform)

Example:

morphir dist which
# Output: Version 1.0.0 (global) at /home/user/.config/morphir/dist/linux-x64/1.0.0

Tool Commands

Manage auxiliary CLI tools and utilities.

tool list

List installed tools.

morphir tool list [options]

Options:

• --platform <rid>: Platform Runtime Identifier (defaults to current platform)
• --local: List local (project) installations only

tool install

Install a tool from a URL.

morphir tool install <name> <url> <version> [options]

Arguments:

• <name>: Tool name
• <url>: Source URL
• <version>: Version string

Options:

• --platform <rid>: Platform Runtime Identifier (defaults to current platform)
• --local: Install locally (project-specific)

Example:

morphir tool install morphir-elm-codegen https://example.com/tool.tar.gz 1.0.0
morphir tool install my-formatter https://example.com/formatter.tar.gz 2.1.0 --local

tool use

Set the active tool version.

morphir tool use <name> <version> [options]

Arguments:

• <name>: Tool name
• <version>: Version to activate

Options:

• --platform <rid>: Platform Runtime Identifier (defaults to current platform)
• --local: Set in local (project) scope

tool remove

Remove an installed tool.

morphir tool remove <name> <version> [options]

tool which

Show the currently active tool version.

morphir tool which <name> [options]

Options:

• --platform <rid>: Platform Runtime Identifier (defaults to current platform)

Extension Commands

Manage optional add-ons and plugins.

Extension commands follow the same pattern as tool commands:

morphir extension list [--platform <rid>] [--local]
morphir extension install <name> <url> <version> [--platform <rid>] [--local]
morphir extension use <name> <version> [--platform <rid>] [--local]
morphir extension remove <name> <version> [--platform <rid>] [--local]
morphir extension which <name> [--platform <rid>]

Platform Identifiers (RIDs)

Morphir uses .NET Runtime Identifiers to manage platform-specific artifacts:

The CLI automatically detects the current platform when --platform is not specified.

Resolution Rules

When looking for an active artifact, the CLI uses the following precedence:

1. Project-local selection (if .morphir/ exists and selection is set locally)
2. Global selection (in OS config directory)
3. Error if no selection is found

Each artifact category (dist, tool, extension) resolves independently.

Folder Layout

Global (preferred):
  ~/.config/morphir/           (Linux)
  ~/Library/Application Support/morphir/  (macOS)
  %APPDATA%\Morphir\           (Windows)
    dist/
      <platform>/
        <version>/
          bin/
          manifest.json
    tools/
      <platform>/
        <tool-name>/
          <version>/
            bin/
            manifest.json
    extensions/
      <platform>/
        <extension-name>/
          <version>/
            bin/
            manifest.json

Local (optional, per project):
  .morphir/
    dist/...
    tools/...
    extensions/...

Manifest Format

Each installed artifact includes a manifest.json file (JSONC format with comments supported):

{
  "name": "morphir-dist",
  "version": "1.0.0",
  "platform": "linux-x64",
  "sourceUrl": "https://example.com/artifact.tar.gz",
  "sha256": "abc123...",
  "description": "Core Morphir distribution",
  "installedAt": "2025-12-23T19:00:00Z",
  "metadata": {
    "key": "value"
  }
}

See Also

• Configuration Guide - Learn about layered configuration
• Troubleshooting - Common issues and solutions

3 - Troubleshooting

Troubleshooting Guide

This guide covers common issues you may encounter when using the Morphir .NET CLI and how to resolve them.

Installation Issues

Tool Not Found After Installation

Problem: After running dotnet tool install, the morphir command is not found.

Solution:

1. Check if tools are in PATH:

   echo $PATH | grep .dotnet/tools
   

2. Add to PATH if missing (Linux/macOS):

   export PATH="$PATH:$HOME/.dotnet/tools"
   

3. Add to PATH if missing (Windows):

   $env:PATH += ";$env:USERPROFILE\.dotnet\tools"
   

4. Restart your terminal after modifying PATH

Installation Fails with “Unable to find package”

Problem: dotnet tool install Morphir.CLI fails to find the package.

Solution:

1. Check NuGet sources:

   dotnet nuget list source
   

2. Add nuget.org if missing:

   dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org
   

3. Verify package name - ensure you’re using the correct package name

Validation Issues

“File does not exist” Error

Problem:

Error: File does not exist: morphir-ir.json

Solutions:

1. Check file path:

   ls -l morphir-ir.json
   

2. Use absolute path:

   morphir ir verify /full/path/to/morphir-ir.json
   

3. Check current directory:

   pwd
   cd /path/to/ir/files
   morphir ir verify morphir-ir.json
   

Malformed JSON Errors

Problem:

Message: Malformed JSON: 'i' is an invalid start of a value. LineNumber: 6

Solutions:

1. Validate JSON syntax with a JSON validator:

   cat morphir-ir.json | jq .
   

2. Check for common issues:

   • Missing commas between array/object elements
   • Trailing commas (not allowed in JSON)
   • Unquoted keys or values
   • Invalid escape sequences

3. Use a JSON formatter:

   cat morphir-ir.json | jq . > morphir-ir-formatted.json
   

Schema Version Detection Issues

Problem: Auto-detection selects the wrong schema version.

Solutions:

1. Explicitly specify version:

   morphir ir verify --schema-version 3 morphir-ir.json
   

2. Check formatVersion field (for v2/v3):

   cat morphir-ir.json | jq '.formatVersion'
   

3. Verify IR structure:

   • v1: No formatVersion field
   • v2: "formatVersion": 2
   • v3: "formatVersion": 3

Validation Fails but IR Appears Correct

Problem: Validation reports errors, but you believe the IR is valid.

Investigation Steps:

1. Review error messages carefully - they include Expected vs. Found values

2. Check schema documentation - Schema Specifications

3. Validate against different versions:

   morphir ir verify --schema-version 1 morphir-ir.json
   morphir ir verify --schema-version 2 morphir-ir.json
   morphir ir verify --schema-version 3 morphir-ir.json
   

4. Compare with known-good IR:

   # Validate a reference file
   morphir ir verify reference-morphir-ir.json
   

5. Check for common issues:

   • Incorrect tag capitalization (e.g., "Public" vs "public")
   • Missing required fields
   • Incorrect array structure
   • Type mismatches

Performance Issues

Validation Takes Too Long

Problem: Validation of large IR files (>1MB) takes several seconds.

Current Limitations:

• This is expected behavior for large files in Phase 1
• Schema validation is inherently slower for complex, deeply-nested JSON

Workarounds:

1. Use --quiet mode to reduce output overhead:

   morphir ir verify --quiet morphir-ir.json
   

2. Validate in parallel (for multiple files):

   find . -name "*.json" | xargs -P 4 -I {} morphir ir verify --quiet {}
   

3. Phase 2 improvements (coming soon):

   • Performance optimizations for batch processing
   • Caching and incremental validation

High Memory Usage

Problem: Validation consumes excessive memory for very large IR files.

Solutions:

1. Check file size:

   ls -lh morphir-ir.json
   

2. For files >10MB:

   • Consider splitting into smaller modules
   • Report the issue with file size details

3. Increase available memory (if using Docker):

   docker run --memory 2g morphir-cli ir verify morphir-ir.json
   

CI/CD Integration Issues

CI Pipeline Doesn’t Fail on Invalid IR

Problem: Pipeline continues even when validation fails.

Solution: Check exit codes explicitly:

# GitHub Actions
- name: Validate IR
  run: |
    morphir ir verify morphir-ir.json
    if [ $? -ne 0 ]; then
      echo "Validation failed"
      exit 1
    fi

Or use set -e in bash scripts:

#!/bin/bash
set -e  # Exit on any error

morphir ir verify morphir-ir.json
echo "Validation succeeded!"

JSON Output Not Parsed Correctly

Problem: CI tools can’t parse JSON output.

Solutions:

1. Verify JSON format:

   morphir ir verify --json morphir-ir.json | jq .
   

2. Save to file:

   morphir ir verify --json morphir-ir.json > validation-result.json
   

3. Check for extra output:

   • Use --quiet with --json to suppress non-JSON output
   • Some logging may appear on stderr

Permission Denied in Docker

Problem:

Permission denied: /app/morphir-ir.json

Solution: Fix file permissions or use volume mounts:

# In Dockerfile
RUN chmod +r /app/*.json

# Or when running
docker run -v $(pwd):/app:ro morphir-cli ir verify /app/morphir-ir.json

Error Message Reference

Common Validation Errors

Missing Required Field

Path: $.distribution
Message: Required properties ["formatVersion"] are not present
Expected: required property
Found: undefined (missing)

Fix: Add the missing field to your JSON:

{
  "formatVersion": 3,
  "distribution": [ ... ]
}

Type Mismatch

Path: $.modules[0].name
Message: Value is "string" but should be "array"
Expected: array
Found: string

Fix: Change the field type:

// Incorrect
"name": "MyModule"

// Correct
"name": ["my", "module"]

Invalid Tag Value

Path: $.modules[0].accessControl
Message: Value must be one of: ["Public", "Private"]
Expected: "Public" or "Private"
Found: "public"

Fix: Use correct capitalization:

// Incorrect
"accessControl": "public"

// Correct
"accessControl": "Public"

Array Structure Error

Path: $.distribution[2]
Message: Expected array to have exactly 4 elements
Expected: array of length 4
Found: array of length 3

Fix: Ensure array has the correct number of elements per schema.

Reporting Issues

If you encounter an issue not covered here:

1. Check existing issues: GitHub Issues

2. Gather information:

   • Morphir .NET CLI version: morphir --version
   • .NET SDK version: dotnet --version
   • Operating system and version
   • Complete error message
   • Minimal reproduction steps

3. Create a new issue with:

   • Clear title describing the problem
   • Steps to reproduce
   • Expected vs. actual behavior
   • Environment information
   • Sample IR file (if possible) or minimal example

Management Commands (dist/tool/extension)

No Active Version Set

Problem: Running morphir dist which or morphir tool which <name> shows “No active version set”.

Solution:

1. List installed versions:

   morphir dist list
   morphir tool list
   

2. Set an active version:

   # Global
   morphir dist use <version>
   morphir tool use <name> <version>
   
   # Local (project-specific)
   morphir dist use <version> --local
   morphir tool use <name> <version> --local
   

Platform Not Supported

Problem: Installation fails with “Platform not supported” or downloaded artifact doesn’t work.

Solution:

1. Check current platform:

   dotnet --info | grep RID
   

2. Manually specify platform:

   morphir dist install <url> <version> --platform linux-x64
   

3. Verify available platforms: Check the distribution documentation for supported platforms.

Local vs Global Confusion

Problem: Setting a version locally but it’s not being used.

Solution:

• Remember precedence: Local (.morphir/) overrides global (~/.config/morphir/)
• Check both scopes:

  morphir dist which          # Shows resolved version (local > global)
  morphir dist list           # Shows global installations
  morphir dist list --local   # Shows local installations
  

• Clear local selection: Remove the active selection file in .morphir/dist/active or .morphir/tools/active-<name>

Installation Directory Not Created

Problem: Installation fails because parent directories don’t exist.

Solution:

The CLI should create directories automatically. If this fails:

1. Manually create directories:

   # Global
   mkdir -p ~/.config/morphir/{dist,tools,extensions}
   
   # Local
   mkdir -p .morphir/{dist,tools,extensions}
   

2. Check permissions:

   ls -ld ~/.config/morphir
   

Downloaded Artifact Is Corrupted

Problem: Installation completes but artifacts don’t work or are corrupted.

Solution:

1. Check manifest for hash:

   cat ~/.config/morphir/dist/<platform>/<version>/manifest.json
   

2. Verify download integrity (if SHA256 is in manifest):

   sha256sum ~/.config/morphir/dist/<platform>/<version>/bin/artifact
   

3. Re-download:

   morphir dist remove <version>
   morphir dist install <url> <version>
   

Getting Help

• Documentation: Morphir .NET Docs
• GitHub Issues: finos/morphir-dotnet/issues
• Community: FINOS Morphir

See Also

• CLI Reference - Complete command documentation
• Management Commands - Dist, tool, and extension management
• morphir ir verify - Detailed verification command reference
• Schema Specifications - IR schema documentation