Compiler CLI

The Matador CLI is the primary tool for transforming human-readable .matador policies into machine-executable bytecode. It integrates seamlessly into your build pipeline and CI/CD workflows.

Installation

You can run the CLI on-demand using npx or install it as a dev dependency in your project.

npx matador-policy-cli --help

npm install -D matador-policy-cli

yarn add -D matador-policy-cli

pnpm add -D matador-policy-cli

Workflow

A typical policy development lifecycle involves formatting, validating, and compiling.

Format Source Code

Ensure your policies follow a consistent style. The format command automatically fixes indentation and spacing.

npx matador-policy-cli format ./policies/swap.matador

Compile to Bytecode

Transform the DSL into an interpreter-ready JSON payload. This step also performs semantic validation and type checking.

npx matador-policy-cli compile ./policies/swap.matador -d ./out

Verify Output

The compiler generates a JSON file (e.g., swap.json) in the destination directory. This file contains the hex-encoded bytecode required for on-chain deployment.

Command Reference

`compile`

Compiles a source file into a JSON artifact.

matador-policy-cli compile <file> [options]

Option	Alias	Description
`--destination <dir>`	`-d`	The output directory for the compiled JSON. Defaults to the source file's directory.

Output Artifact Schema

The generated JSON file contains the following fields:

Field	Type	Description
`hexData`	`string`	The primary bytecode payload. This is what you pass to the on-chain interpreter.
`metadata`	`object`	Key-value metadata defined in the policy source (e.g. author, description).
`requiredModules`	`string[]`	List of interpreter modules (e.g. `core`, `storage`) required to execute this policy.
`instructions`	`object[]`	A human-readable breakdown of the compiled opcodes for debugging/verification.

`format`

Formats a source file in-place.

matador-policy-cli format <file> [options]

Option	Description
`--check`	Checks if the file is formatted without modifying it. Returns exit code 1 if unformatted. Useful for CI/CD.

CI/CD Integration

You can enforce policy correctness in your CI pipelines using the CLI.

GitHub Actions Example

.github/workflows/policy-check.yml

name: Policy Check
on: [push]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      
      # Check formatting
      - run: npx matador-policy-cli format ./policies/*.matador --check
      
      # Verify compilation succeeds
      - run: npx matador-policy-cli compile ./policies/*.matador

Compiler CLI

On this page