Scapius CLI Tool Reference

The Scapius CLI is distributed as an official Docker container image for cross-platform execution with zero host dependencies, as well as a native .NET CLI tool (scapius).

---

Running with Docker

Basic Usage

docker run --rm -v $(pwd):/workspace scapiusea/scapius <command> [options]

Creating a Permanent Alias

Add the following alias to your ~/.bashrc, ~/.zshrc, or PowerShell profile:

alias scapius='docker run --rm -v $(pwd):/workspace scapiusea/scapius'

---

Commands

validate

Parses .ea files and executes the complete static semantic analysis suite (syntax correctness, reference integrity, cycle detection, containment boundaries).

# Validate an entire directory of .ea files
scapius validate ./architecture

Common Options

Flag	Description
-v, --verbose	Output detailed AST generation steps and resolution logs
--strict	Treat warnings as fatal errors

---

compile

Compiles an architecture workspace into an intermediate representation or static JSON AST model.

scapius compile /workspace/architecture -o /workspace/dist/model.json

Common Options

Flag	Description
-o, --output <file>	Path for the compiled JSON output file
-v, --verbose	Display detailed informational compilation logs

---

lint

Lints a Scapius DSL workspace directory for formatting violations, style smells, missing governance metadata, and architectural quality issues.

# Basic linting with human-readable summary
scapius lint ./architecture

# Automatically fix formatting and style issues in-place
scapius lint ./architecture --fix

# Preview auto-fixes without modifying files on disk
scapius lint ./architecture --dry-run

# Run in CI with strict mode (exit with code 1 on any warning)
scapius lint ./architecture --strict

# Output SARIF format for GitHub Code Scanning
scapius lint ./architecture --format sarif > results.sarif

Options

Flag	Description
-f, --format <format>	Output format: text (default), json, or sarif (SARIF v2.1.0).
--fix	Automatically apply fixes for fixable formatting and style rules in-place.
--dry-run	Preview what fixes would be applied without modifying files.
--strict	Treat warnings as fatal errors (exits with code 1 if any warning is reported).
--max-warnings <N>	Fail if warning count exceeds N.
--rule <id>=<severity>	Override specific rule severity on the CLI (e.g. --rule naming-convention=error).

---

CI / GitHub Actions Pipeline Integration

You can integrate both validate and lint into your pull request checks:

name: Scapius Architecture Validation & Linting
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate .ea files with Scapius
        run: |
          docker run --rm -v ${{ github.workspace }}:/workspace scapiusea/scapius validate /workspace --strict

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint Scapius Architecture with SARIF report
        run: |
          docker run --rm -v ${{ github.workspace }}:/workspace scapiusea/scapius lint /workspace --format sarif > scapius.sarif
        continue-on-error: true

      - name: Upload SARIF to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: scapius.sarif