CLI Reference

Every command, flag, argument, and output format.

Global Flags

These flags are available on all commands:

sysmara init

Create a new SysMARA project in the current directory.

sysmara init

This creates:

• sysmara.config.yaml — Project configuration with sensible defaults.
• system/ — The spec directory with subdirectories for each spec type (entities, capabilities, policies, invariants, modules, flows).

Example:

$ mkdir my-project && cd my-project
$ npx sysmara init
Created sysmara.config.yaml
Created system/entities/
Created system/capabilities/
Created system/policies/
Created system/invariants/
Created system/modules/
Created system/flows/
Project initialized successfully.

sysmara add

Add a new spec file to your project.

sysmara add <type> <name>

Arguments

Examples:

# Add an entity
$ npx sysmara add entity User
Created system/entities/user.yaml

# Add a capability
$ npx sysmara add capability CreateOrder
Created system/capabilities/create-order.yaml

# Add a policy
$ npx sysmara add policy RequireAuthentication
Created system/policies/require-authentication.yaml

# Add an invariant
$ npx sysmara add invariant OrderTotalPositive
Created system/invariants/order-total-positive.yaml

# Add a module
$ npx sysmara add module billing
Created system/modules/billing.yaml

# Add a flow
$ npx sysmara add flow UserOnboarding
Created system/flows/user-onboarding.yaml

sysmara validate

Parse all spec files and run cross-validation checks.

sysmara validate

This command performs two steps:

1. Parsing: Reads all YAML files in the spec directory, validates each against its Zod schema.
2. Cross-validation: Checks that all references between specs resolve correctly. For example, if a capability references an entity named User, that entity must exist.

Example (passing):

$ npx sysmara validate
Parsed 12 spec files
Cross-validation passed
All specs are valid.

Example (failing):

$ npx sysmara validate
Parsed 12 spec files
Error: Capability "CreateOrder" references entity "Order" which does not exist.
Validation failed with 1 error.

JSON output:

$ npx sysmara validate --json
{
  "valid": false,
  "errors": [
    {
      "code": "AX201",
      "message": "Capability \"CreateOrder\" references entity \"Order\" which does not exist.",
      "spec": "CreateOrder",
      "severity": "error"
    }
  ]
}

sysmara build

Run the full build pipeline: validate, graph, compile, and diagnose.

sysmara build

This is the most comprehensive command. It runs all pipeline stages in order:

1. Parse and validate all specs.
2. Generate the system graph (system-graph.json) and system map (system-map.json).
3. Run the capability compiler.
4. Run all diagnostic rules and report findings.

Example:

$ npx sysmara build
Parsing specs... 12 files parsed
Validating... passed
Building graph... done
Compiling capabilities... 8 capabilities compiled
Running diagnostics... 2 warnings, 0 errors

Warnings:
  AX401: Entity "LegacyAccount" is defined but never referenced by any capability.
  AX402: Capability "ArchiveUser" is defined but not included in any module.

Build completed successfully.

sysmara graph

Generate the system graph and system map.

sysmara graph

Produces two files in the configured generatedDir:

• system-graph.json — Full relationship graph with all edges and nodes.
• system-map.json — Flat index of modules, capabilities, entities, and unresolved references.

This command includes the parse and validate steps — it will not generate a graph from invalid specs.

sysmara compile

Run the capability compiler.

sysmara compile

Processes capability specs and generates compiled output. Requires that specs are valid and the graph has been built.

sysmara doctor

Run a comprehensive health check of your project.

sysmara doctor

The doctor command checks nine areas of your project:

Example:

$ npx sysmara doctor
[✓] Config: valid
[✓] Spec directory: 12 files found
[✓] Parsing: all files parsed successfully
[✓] Cross-validation: all references resolved
[✓] Boundaries: no violations
[✓] Invariants: all valid
[!] Diagnostics: 1 warning
[!] Orphans: 1 orphaned entity
[✓] Cycles: no circular dependencies

8/9 checks passed, 1 warning

sysmara explain

Get a human-readable explanation of a spec and its relationships.

sysmara explain <type> <name>

Arguments

Example:

$ npx sysmara explain capability CreateOrder
Capability: CreateOrder
Description: Creates a new order for a customer.

Entity: Order
Policies: RequireAuthentication, RequireCustomerRole
Module: orders
Invariants: OrderTotalPositive

This capability creates an Order entity. It requires the
RequireAuthentication and RequireCustomerRole policies to be
satisfied. It belongs to the orders module and must maintain
the OrderTotalPositive invariant.

sysmara impact

Analyze the impact of changing a spec.

sysmara impact <type> <name>

Arguments

Uses BFS traversal with a maximum depth of 3 hops, following edges bidirectionally. Returns the full impact surface: affected modules, capabilities, entities, invariants, policies, routes, and flows.

See the Impact Analysis guide for detailed examples.

sysmara plan create

Generate a change plan document.

sysmara plan create <title>

Arguments

Example:

$ npx sysmara plan create "Add payment processing"
Created plan: plans/add-payment-processing.yaml

sysmara plan show

Display an existing change plan.

sysmara plan show <file>

Arguments

Example:

$ npx sysmara plan show plans/add-payment-processing.yaml

Add --json for machine-readable output.

sysmara check boundaries

Validate module boundary rules.

sysmara check boundaries

Checks all module definitions for boundary violations: forbidden dependencies, circular dependencies, undefined dependencies, and cross-module entity references. Produces diagnostic codes in the AX3xx and MOD_* ranges.

Example:

$ npx sysmara check boundaries
Checking module boundaries...

Error: Module "orders" depends on "inventory" which is in its forbidden_deps list.
  Code: AX301 (MOD_CONFLICTING_DEP)

1 boundary violation found.