Evolith CLI

Command-line interface for Evolith governance, standards validation, and AI agent integration.

Features

Governance: ADR management, standards tracking, agent installation
Validation: Repository compliance against Evolith standards
AI Integration: MCP server for AI agent tool calling
Observability: Structured logging, metrics, error reporting

Installation

The CLI is published to npm registry and compatible with all JavaScript package managers.

npm

npm install -g @evolith/smart-cli

pnpm

pnpm add -g @evolith/smart-cli

yarn

yarn global add @evolith/smart-cli

Manual Binary

Download the latest binary from GitHub Releases and add to your PATH.

Verify Installation

smart-cli --version
# smart-cli version 1.1.0

Troubleshooting

Permission errors on macOS/Linux:

# If you get EACCES errors, try:
sudo npm install -g @evolith/smart-cli --unsafe-perm

Using nvm (Node Version Manager):

# Ensure global bin path is in PATH
export PATH=$(npm config get prefix)/bin:$PATH

Quickstart

1. Initialize a Repository

cd your-project
smart-cli init

This creates an evolith.yaml file with default configuration.

2. Run First Validation

smart-cli validate

Output:

✓ Validating repository...
✓ Repository is compliant with Evolith standards

3. Install an Agent

smart-cli agents install
# Select "standard" template when prompted

Commands

validate

Validate repository compliance against Evolith standards.

smart-cli validate [options]

Options:
  --satellite <path>    Path to satellite repository (default: cwd)
  --core <path>         Path to Evolith Core
  --format <format>     Output format: json, table, yaml, markdown
  --output <file>       Write output to file
  --ruleset <id>        Validate specific ruleset (acl, open-core, inheritance)
  --engine <engine>     Policy evaluation engine: native or opa (default: native)

Dual-Engine Policy Evaluation: The CLI supports evaluating policies using either the built-in TypeScript engine (native) or Open Policy Agent WebAssembly modules (opa). See Core ADR-0041 for details.

Examples:

# Basic validation
smart-cli validate

# JSON output for automation
smart-cli validate --format json

# Table output for humans
smart-cli validate --format table

# Validate specific ruleset
smart-cli validate --ruleset acl

adr

Manage Architecture Decision Records.

smart-cli adr <command>

Commands:
  create     Create new ADR
  list       List all ADRs
  get        Show ADR details
  update     Update existing ADR
  matrix     Show ADR matrix

Examples:

# Create new ADR
smart-cli adr create

# List all ADRs
smart-cli adr list

# Get specific ADR
smart-cli adr get ADR-0002

standards

Manage governance standards.

smart-cli standards <command>

Commands:
  init       Initialize standards directory
  list       List all standards
  get        Show standard details
  validate   Validate against standards
  export     Export standard to markdown/json

Examples:

# Initialize standards
smart-cli standards init

# List standards
smart-cli standards list

agents

Install and manage Evolith agents.

smart-cli agents <command>

Commands:
  install    Install new agent
  list       List installed agents
  remove     Remove agent
  validate   Validate agent ruleset
  upgrade    Upgrade agent

Examples:

# Interactive install
smart-cli agents install

# List agents
smart-cli agents list

history

View and manage command history.

smart-cli history [options]

Options:
  --list              List recent commands
  --get <id>          Show command details
  --search <query>    Search commands
  --stats             Show statistics
  --clear             Clear history

Examples:

# Show last 20 commands
smart-cli history

# Show statistics
smart-cli history --stats

# Search commands
smart-cli history --search validate

completion

Generate shell completion scripts.

smart-cli completion --install <shell>

Supported shells: bash, zsh, fish

Examples:

# Install bash completion
smart-cli completion --install bash

# Install zsh completion
smart-cli completion --install zsh

MCP Server (AI Agent Integration)

The Evolith CLI includes an MCP server for AI agent integration.

Starting the MCP Server

smart-cli mcp serve

The server communicates via stdio JSON-RPC.

MCP Smoke Test

Use the smoke test before releases or MCP protocol changes:

npm run mcp:smoke

The smoke verifies initialize, tools/list, resources/list, prompts/list, and a real tools/call through the built CLI.

Available MCP Tools

Tool	Description
`evolith-validate`	Validate repository compliance
`evolith-agent-install`	Install new agent
`evolith-agent-list`	List installed agents
`evolith-agent-validate`	Validate agent ruleset
`evolith-agent-upgrade`	Upgrade an existing agent
`evolith-agent-remove`	Remove an agent
`evolith-architecture-validate`	Validate architecture (F1/F2/F3) with optional deep analysis
`evolith-sdlc-handoff`	Generate phase handoff artifact manifest
`evolith-sdlc-status`	Show SDLC phase gate status
`evolith-config-get`	Get configuration value from `evolith.yaml`
`evolith-config-set`	Set configuration value in `evolith.yaml`
`evolith-metrics`	Get MCP server metrics
`evolith-moscow-create`	Create a new MoSCoW prioritization analysis
`evolith-moscow-load`	Load an existing MoSCoW analysis
`evolith-moscow-update`	Update an item in a MoSCoW analysis
`evolith-moscow-remove`	Remove an item from a MoSCoW analysis
`evolith-moscow-list`	List all MoSCoW analyses for a repository
`evolith-moscow-validate`	Validate a MoSCoW analysis for correctness
`evolith-moscow-report`	Generate a markdown report from a MoSCoW analysis

Cursor AI Configuration

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "evolith": {
      "command": "smart-cli",
      "args": ["mcp", "serve"]
    }
  }
}

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "evolith": {
      "command": "smart-cli",
      "args": ["mcp", "serve"]
    }
  }
}

AI Agent Workflow Example

When integrated with an AI agent, you can have conversations like:

You: Validate my repository
Agent: Let me run the validation...

      await mcp.callTool('evolith-validate', {
        path: '/user/project',
        format: 'summary'
      })

Result: ✓ Repository is compliant with Evolith standards
        Rules checked: 12
        All gates passed

You: Show me the SDLC status
Agent: Let me check the phase gate status...

      await mcp.callTool('evolith-sdlc-status', {
        path: '/user/project'
      })

Result: Phase 1 — 3 gates passed, 0 failed
        All evidence artifacts present

Configuration

Evolith uses an evolith.yaml file in the repository root:

coreRef:
  version: "1.0.0"
  path: "../../evolith"

governance:
  version: "1.0"
  adrRegistry:
    - id: "ADR-0001"
      status: "accepted"

product:
  name: "my-project"
  type: "library"
  runtime: "typescript"

Output Formats

All commands support multiple output formats:

# JSON (default for automation)
smart-cli validate --format json

# Table (human-readable)
smart-cli validate --format table

# YAML (pipeline integration)
smart-cli validate --format yaml

# Markdown (documentation)
smart-cli validate --format markdown

Troubleshooting

Command not found

If evolith is not found after installation, ensure npm's global bin is in your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"

MCP server not responding

Ensure the MCP server is running:

smart-cli mcp serve &

Validation fails

Check your evolith.yaml exists and is valid:

cat evolith.yaml
smart-cli validate --verbose

Development

Building from Source

cd sdk/cli
npm install
npm run build
npm link  # Link globally for testing

Running Tests

# Run all tests
npm test

# Run with coverage report
npm run test:cov

Coverage (as of v0.0.3-beta): 88.7% statements · 89.8% lines · 77.0% branches · 83.6% functions · 1 369 tests

Project Structure

sdk/cli/
├── src/
│   ├── commands/      # CLI commands (adr, validate, agents, etc.)
│   ├── application/   # Use cases
│   ├── domain/        # Business logic (services, entities)
│   ├── infrastructure/# External integrations (catalog, CLI)
│   └── core/          # Shared (DI, observability, errors, MCP)
├── shell/             # Shell completion scripts
├── templates/         # Configuration templates
└── docs/              # Documentation

Documentation

SMART CLI Demo Guide - Comprehensive guide covering all commands, SDLC flow, product types, MCP integration, and architecture validation
Vision - CLI vision and roadmap
Data Models - Domain data models
MCP Integration - MCP server integration details

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Evolith CLI

Features

Installation

npm

pnpm

yarn

Manual Binary

Verify Installation

Troubleshooting

Quickstart

1. Initialize a Repository

2. Run First Validation

3. Install an Agent

Commands

validate

adr

standards

agents

history

completion

MCP Server (AI Agent Integration)

Starting the MCP Server

MCP Smoke Test

Available MCP Tools

Cursor AI Configuration

Claude Desktop Configuration

AI Agent Workflow Example

Configuration

Output Formats

Troubleshooting

Command not found

MCP server not responding

Validation fails

Development

Building from Source

Running Tests

Project Structure

Documentation

Contributing

License

Support