Installation

Prerequisites

SysMARA requires Node.js version 20.0.0 or higher. Verify your version before proceeding:

node --version
# Must be >= v20.0.0

If you need to manage multiple Node versions, nvm or fnm are recommended.

Install SysMARA

Install the core package as a dev dependency in your project:

npm install --save-dev @sysmara/core

This gives you the sysmara CLI binary and the spec runtime. The package has only two dependencies: yaml for spec parsing and zod for schema validation. No hidden dependency trees.

You can also install it globally if you prefer:

npm install -g @sysmara/core

Initialize a Project

Create the SysMARA directory structure in your project root:

npx sysmara init

This creates the following structure:

your-project/
  sysmara.config.yaml        # Project-level SysMARA configuration
  system/                   # All YAML spec files live here
    entities/               # Entity definitions
    capabilities/           # Capability specs
    policies/               # Business policies and invariants
    modules/                # Module boundary definitions
    flows/                  # Cross-module flow specs
  app/                      # Your application source code

What Each Directory Contains

• system/entities/ — Domain objects with their fields, types, and relationships. These form the nodes of your system graph.
• system/capabilities/ — Operations your system can perform, declared with inputs, outputs, preconditions, and postconditions.
• system/policies/ — Business rules and invariants that must hold across the system, regardless of which capability triggers them.
• system/modules/ — Boundary definitions that control which entities and capabilities belong to which module, and what cross-module dependencies are allowed.
• system/flows/ — Multi-step operation sequences that cross module boundaries, with explicit ordering and error handling.
• sysmara.config.yaml — Project configuration including spec paths, output targets, and compiler options.

Verify the Installation

Run the spec validator to confirm everything is wired correctly:

npx sysmara validate

On a fresh project with no specs yet, you should see a clean pass with zero errors and zero warnings. If you see schema errors, check that your sysmara.config.yaml points to the correct directories.

Verify the CLI

Confirm the CLI is accessible and check the available commands:

npx sysmara --help

You should see the full command list: init, add, validate, build, graph, compile, doctor, explain, impact, plan, and check boundaries. Every command supports the --json flag for machine-readable output, which is how AI agents consume SysMARA's output programmatically.

Next Steps

Your project is ready. Head to the Quick Start to build your first spec-driven system in five minutes.