CLI Reference — All SysMARA Commands

Every command, flag, argument, and output format.

Global Flags

These flags are available on all commands:

sysmara init

Create a new SysMARA project with database, Docker, environment files, package.json, and README.

sysmara init [--db <provider>] [--orm <adapter>] [--no-implement]

Options

This creates the full project structure including:

• sysmara.config.yaml — Project configuration with database settings
• system/ — YAML spec directory
• app/ — Application code with database/migrations/
• docker-compose.yml — Local database container
• Dockerfile — Production multi-stage build
• .env.example / .env.local — Environment files
• package.json — npm scripts for build, dev, start, db commands
• README.md — Project-specific setup instructions
• .gitignore — Comprehensive ignore rules

Example:

$ npx sysmara init --db postgresql --orm sysmara-orm
  Database: postgresql
  ORM:      sysmara-orm
  ...
  created package.json
  created README.md
[OK] 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, scaffold, generate schema, and diagnose.

sysmara build [--no-implement]

Pass --no-implement to generate TODO stubs instead of working implementations in scaffold files.

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. Scaffold starter implementation files in app/ (skip existing).
5. Generate database schema (if database section is configured).
6. 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 scaffold

Generate starter TypeScript implementation files in app/ from your YAML specs.

sysmara scaffold

This command generates five types of files:

• app/entities/<name>.ts — Typed interface with field definitions and a runtime validation helper.
• app/capabilities/<name>.ts — Handler function with typed input/output imports and TODO comments for policies and invariants.
• app/policies/<name>.ts — Enforcement function with condition comments derived from the spec.
• app/invariants/<name>.ts — Validation function referencing the entity type with the rule as a TODO.
• app/services/<module>.ts — Service class with one method stub per capability in the module.

Key behavior: Scaffold files are written once. If a file already exists, it is skipped. This means re-running scaffold or build will never overwrite your edits.

Scaffold is also integrated into sysmara build as step 5 — it runs automatically after compilation.

Example:

$ npx sysmara scaffold

  ╔═══════════════════════════════╗
  ║     SysMARA Scaffold          ║
  ╚═══════════════════════════════╝

  Written 8 file(s):
    + entities/user.ts
    + entities/workspace.ts
    + capabilities/create_user.ts
    + capabilities/create_workspace.ts
    + policies/admin_policy.ts
    + invariants/email_unique.ts
    + services/auth.ts
    + services/workspaces.ts

  Skipped 0 — already exist:

[OK] Scaffold complete. 8 written, 0 skipped.

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 db generate

Generate database schema files from your entity specs using the configured adapter.

sysmara db generate

Reads the database section of sysmara.config.yaml to determine which adapter (Prisma, Drizzle, TypeORM, or SysMARA ORM) and provider (PostgreSQL, MySQL, SQLite) to use. Generates schema files in the configured output directory.

Example:

$ npx sysmara db generate
Using adapter: sysmara-orm (postgresql)
Generated schema for 4 entities
Output: generated/db/schema.sql

For Prisma, this generates prisma/schema.prisma. For Drizzle, drizzle/schema.ts. For TypeORM, individual entity files under typeorm/entities/. For SysMARA ORM, raw SQL in the configured output directory.

sysmara db migrate

Create a migration by diffing the current specs against the previous version.

sysmara db migrate

Compares the current entity specs to the previously generated schema and produces migration files. For SysMARA ORM, this includes impact analysis with risk classification and affected capability tracking.

Example:

$ npx sysmara db migrate
Diffing specs...
Migration plan:
  Step 1: Add column "phone" (string) to "user"
  Step 2: Create new table "notification_preference"

Risk: low | Affected capabilities: create_user, update_user | Review: no
Migration written to: generated/db/migrations/20260314120000_migration.sql

sysmara db status

Show the current migration status and pending changes.

sysmara db status

Displays which migrations have been applied, which are pending, and whether the current entity specs have drifted from the last generated schema.

Example:

$ npx sysmara db status
Adapter: sysmara-orm (postgresql)
Entities: 4
Last generated: 2026-03-14T10:00:00Z
Pending changes: 1 new field, 1 new entity
Status: out of sync — run "sysmara db generate" to update

sysmara flow list

List all flows defined in the project with their step counts, triggers, and descriptions.

sysmara flow list

Example:

$ npx sysmara flow list
Name                  Module      Trigger          Steps  Description
user_signup_flow      auth        user_signup      3      Full user signup process
billing_cycle         billing     generate_invoice 3      Recurring billing flow

sysmara flow validate

Validate a flow by checking that all step action capabilities exist in the system specs.

sysmara flow validate <name>

Arguments

Example:

$ npx sysmara flow validate user_signup_flow
[OK] Flow is valid.
Steps: 3
Capabilities required: create_user, create_profile, send_welcome_email

sysmara flow run

Execute a flow with the given JSON input. Uses a default logging capability handler that records invocations without performing real database operations.

sysmara flow run <name> --input <json>

Arguments

Example:

$ npx sysmara flow run user_signup_flow --input '{"email":"alice@example.com"}'
Status: completed
Duration: 12ms
Steps completed: 3/3

sysmara flow log

Show the execution log summary. The log is currently in-memory and resets per CLI invocation. Use the FlowExecutor API for persistent tracking.

sysmara flow log

sysmara start

Start the SysMARA server with auto-wired routes from specs.

sysmara start [--port <number>] [--host <address>] [--no-schema]

Options

This command does everything needed to go from specs to a running server:

1. Parses all YAML specs
2. Connects to the database (configured in sysmara.config.yaml, or SQLite by default)
3. Applies the database schema (creates tables from entity specs)
4. Auto-wires every capability to an HTTP route based on naming conventions
5. Starts the HTTP server

Route Inference

Capability names are automatically mapped to HTTP methods and URL paths:

Example:

$ npx sysmara start
SysMARA Server

  Parsing specs...
  Connecting to database...
  ✓ Connected to postgresql (sysmara-orm)
  Applying database schema...
  ✓ Schema applied

  Registering routes...
  ✓ POST   /users                    → create_user
  ✓ GET    /users/:id                → get_user
  ✓ GET    /users                    → list_users

  ✓ Server running at http://localhost:3000
  3 capability routes + health/routes endpoints

  Press Ctrl+C to stop.

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.