MLang CLI

Policy compiler, PR governance, and AI-powered developer tools for the MDP Framework.

Installation

npm install -g @mdp-framework/mlang

Quick Start

# Initialize MLang in your project
mlang init

# Compile policies
mlang policy build --in policies/ --out .mlang/policies

# Evaluate a PR
mlang evaluate --file pr-data.json

# Run AI workflow
mlang workflow run --capsule feature-123 --agents pm,architect,engineer

# Check component similarity
mlang aoi check --component "Button" --framework github.com/your/framework

Commands

Core Commands

mlang init

Initialize MLang in your project.

mlang init [--force] [--verbose]

Options:

• --force: Reinitialize even if .mlang directory exists
• --verbose: Show detailed initialization steps

mlang doctor

Check MLang environment and dependencies.

mlang doctor [--ci] [--verbose]

Options:

• --ci: Run in CI mode (requires GITHUB_TOKEN)
• --verbose: Show detailed check information

Policy Commands

mlang policy init

Initialize a new policy file.

mlang policy init --id <id> --scope <scope> --out <file>

Options:

• --id <id>: Policy ID (e.g., eng.pr.review)
• --scope <scope>: Policy scope (e.g., pr/governance)
• --out <file>: Output file path

mlang policy build

Compile Markdown policies to unsigned PolicyCards.

mlang policy build --in <dir> --out <dir> [--version <version>] [--strict]

Options:

• --in <dir>: Input directory (policies/*.md)
• --out <dir>: Output directory for unsigned JSON
• --version <version>: Override version (default: YYYY.MM.DD)
• --strict: Fail on warnings

mlang policy sign

Sign compiled policies with ed25519.

mlang policy sign --in <dir> --out <dir> --key-file <file>

Options:

• --in <dir>: Input directory (unsigned JSON)
• --out <dir>: Output directory for signed JSON
• --key-file <file>: Private key file (ed25519)

mlang policy verify

Verify signed policy signatures.

mlang policy verify --in <path> [--key-file <file>]

Options:

• --in <path>: File or directory to verify
• --key-file <file>: Public key file (default: .mlang/keys/*.pub)

Evaluation Commands

mlang evaluate

Evaluate PR or local changes against policies.

mlang evaluate --file <file> [--policies <dir>] [--format <format>] [--execute] [--dry-run]

Options:

• --pr <number>: PR number (requires GitHub token)
• --file <file>: Load PR data from JSON file
• --policies <dir>: Policy directory (default: .mlang/policies)
• --format <format>: Output format: text or json (default: text)
• --execute: Execute ActionPlan (requires GitHub token)
• --dry-run: Execute ActionPlan in dry-run mode
• --github-token <token>: GitHub token for execution

Example:

mlang evaluate --file pr-123.json --format json

mlang pr review

Review PR against policies (CI entrypoint).

mlang pr review --pr <number> [--repo <repo>] [--check-name <name>] [--emit-envelope <file>] [--dry-run]

Options:

• --pr <number>: PR number to review
• --repo <repo>: Repository (owner/repo) - auto-inferred if not provided
• --check-name <name>: GitHub check name (default: mdp-governance)
• --emit-envelope <file>: Emit envelope JSON to file
• --dry-run: Skip action execution (evaluation only)

Workflow Commands (Stream 6)

Multi-agent workflow orchestration with PM, Architect, Engineer, and Designer agents.

mlang workflow run

Run a multi-agent workflow on a capsule.

mlang workflow run [--capsule <id>] [--workflow <name>] [--agents <agents>] [--json] [--verbose]

Options:

• --capsule <id>: Capsule ID to run workflow on
• --workflow <name>: Workflow definition name (from .mlang/workflows/)
• --agents <agents>: Comma-separated agent names (e.g., pm,architect,engineer)
• --json: Output as JSON
• --verbose: Show detailed reasoning and context

Examples:

# Run default workflow (PM → Architect → Engineer)
mlang workflow run --capsule feature-auth-123

# Run custom workflow from definition
mlang workflow run --capsule feature-auth-123 --workflow feature-analysis

# Run with custom agent sequence
mlang workflow run --capsule feature-auth-123 --agents pm,designer,engineer

# Output as JSON
mlang workflow run --capsule feature-auth-123 --json

Workflow Definition Format (.mlang/workflows/*.json):

{
  "name": "feature-analysis",
  "description": "Analyze feature requirements",
  "agents": [
    {
      "type": "pm",
      "config": {
        "focus": "requirements"
      }
    },
    {
      "type": "architect",
      "config": {
        "focus": "design"
      }
    }
  ],
  "metadata": {
    "author": "team-name",
    "created_at": "2025-01-12T00:00:00Z"
  }
}

mlang workflow status

Show workflow status for a capsule.

mlang workflow status --capsule <id> [--json] [--verbose]

Options:

• --capsule <id>: Capsule ID (required)
• --json: Output as JSON
• --verbose: Show detailed information

Example:

mlang workflow status --capsule feature-auth-123 --verbose

mlang workflow list

List available workflow definitions.

mlang workflow list [--json] [--verbose]

Options:

• --json: Output as JSON
• --verbose: Show detailed information

Example:

mlang workflow list

AOI Commands (Stream 6)

Architecture of Intent (AOI) operations for detecting missing framework components and generating specifications.

mlang aoi generate

Manually trigger AOI spec generation for a PR.

mlang aoi generate --pr <file> [--policy <id>] [--json] [--verbose]

Options:

• --pr <file>: PR data file (JSON) (required)
• --policy <id>: Policy ID (defaults to first AOI-enabled policy)
• --json: Output as JSON
• --verbose: Show detailed information

Example:

mlang aoi generate --pr pr-123.json --policy ios.swiftui.design-system

Output:

• AOI specification
• Similarity check results
• Generated actions (Jira issues, counter-PRs, notifications)

mlang aoi check

Check if a component exists via similarity search.

mlang aoi check --component <query> [--framework <repo>] [--threshold <number>] [--json] [--verbose]

Options:

• --component <query>: Component name or description (required)
• --framework <repo>: Framework repository
• --threshold <number>: Similarity threshold 0.0-1.0 (default: 0.8)
• --json: Output as JSON
• --verbose: Show detailed information

Examples:

# Check if authentication component exists
mlang aoi check --component "JWT authentication manager" --framework github.com/company/framework

# Lower threshold for broader matching
mlang aoi check --component "authentication" --threshold 0.7

# Output as JSON
mlang aoi check --component "Button" --framework github.com/company/design-system --json

Output:

• Component existence status
• Closest match with similarity score
• Recommendation (use existing or create new)

mlang aoi actions

List pending AOI actions.

mlang aoi actions [--pr <number>] [--status <status>] [--json] [--verbose]

Options:

• --pr <number>: Filter by PR number
• --status <status>: Filter by status (pending, completed, failed)
• --json: Output as JSON
• --verbose: Show detailed information

Examples:

# List all pending actions
mlang aoi actions --status pending

# List actions for specific PR
mlang aoi actions --pr 123

# List all actions
mlang aoi actions

Action Types:

• create_issue: Jira issue created for framework team
• create_counter_pr: Counter-PR created in framework repo
• create_followup_pr: Follow-up PR to migrate original code
• notify_owners: Slack notification sent to owners

mlang aoi config

Show AOI configuration.

mlang aoi config [--json] [--verbose]

Options:

• --json: Output as JSON
• --verbose: Show policy-specific settings

Example:

mlang aoi config --verbose

Configuration File (.mlang/aoi-config.json):

{
  "enabled": true,
  "similarity_threshold": 0.8,
  "auto_create_counter_pr": false,
  "auto_create_followup_pr": false,
  "include_tests": true,
  "frameworks": [
    "github.com/company/design-system"
  ],
  "policies": {
    "ios.swiftui.design-system": {
      "threshold": 0.85,
      "framework": "github.com/company/ios-framework"
    }
  }
}

Registry Commands

mlang registry head

Show latest version on channel.

mlang registry head <id> [--channel <channel>]

Options:

• --channel <channel>: Channel name (stable, preview, dev) (default: stable)

mlang registry get

Fetch policy by ID.

mlang registry get <id> [--version <version>] [--save <file>]

Options:

• --version <version>: Specific version (YYYY.MM.DD)
• --save <file>: Save policy to file

mlang registry verify

Verify policy signature.

mlang registry verify <file>

mlang registry list

List all policies in registry.

mlang registry list [prefix]

Capsule Commands

mlang capsule prune

Prune old capsules based on retention policy.

mlang capsule prune [--apply] [--keep-days <days>] [--yes]

Options:

• --apply: Actually delete capsules (default is dry-run)
• --keep-days <days>: Override retention days
• --yes: Skip confirmation prompts

mlang capsule export

Export capsules to NDJSON file.

mlang capsule export [--capsule <id>] [--kind <kind>] [--out <file>]

Options:

• --capsule <id>: Export specific capsule by ID
• --kind <kind>: Export all capsules of a kind (pr, feature, aoi)
• --out <file>: Output file (default: stdout)

mlang capsule import

Import capsules from NDJSON file.

mlang capsule import --file <file> [--overwrite]

Options:

• --file <file>: Input NDJSON file (required)
• --overwrite: Overwrite existing capsules

Gateway Commands

mlang gateway

Run gateway in MCP server mode.

mlang gateway [--mode <mode>] [--stdio] [--http] [--port <port>]

Options:

• --mode <mode>: Gateway mode (only mcp supported) (default: mcp)
• --stdio: Use stdio transport (default)
• --http: Use HTTP transport
• --port <port>: HTTP port (default: 8080)

Keys Commands

mlang keys generate

Generate ed25519 signing keypair.

mlang keys generate --out <path> [--name <name>]

Options:

• --out <path>: Output path (will create .ed25519 and .pub files)
• --name <name>: Key name/identifier (for documentation)

Environment Variables

Required (for AI operations)

• ANTHROPIC_API_KEY: Anthropic API key for Claude models
• OPENAI_API_KEY: OpenAI API key for GPT models

Optional

• GITHUB_TOKEN: GitHub token for PR operations
• MLANG_BASE_PATH: Override default .mlang directory
• MLANG_LOG_LEVEL: Log level (debug, info, warn, error)

Configuration

MLang uses a .mlang/ directory in your project root:

.mlang/
├── workflows/              # Workflow definitions
│   └── *.json
├── state/
│   └── capsules/          # State capsules
│       └── *.json
├── aoi/
│   ├── actions.json       # Pending AOI actions
│   └── specs/             # Generated AOI specs
│       └── *.json
├── aoi-config.json        # AOI configuration
├── packs/
│   ├── stable/            # Stable policies
│   ├── preview/           # Preview policies
│   └── dev/               # Development policies
├── keys/                  # Signing keys
│   ├── *.ed25519          # Private keys
│   └── *.pub              # Public keys
└── config.json            # MLang configuration

Examples

Example 1: Run Multi-Agent Workflow

# Create capsule for feature
echo '{
  "id": "feature-auth-123",
  "kind": "feature",
  "evidence": ["Implement JWT authentication"],
  "metadata": {"title": "Add authentication"}
}' > .mlang/state/capsules/feature-auth-123.json

# Run workflow
mlang workflow run --capsule feature-auth-123 --agents pm,architect,engineer --verbose

Example 2: Check Component Similarity

# Check if button component exists
mlang aoi check \
  --component "Primary action button with ripple effect" \
  --framework github.com/company/design-system \
  --threshold 0.8

Example 3: Generate AOI Spec

# Create PR data file
echo '{
  "number": 123,
  "title": "Add custom button",
  "files": [{"path": "Button.tsx", "status": "added"}]
}' > pr-123.json

# Generate AOI spec
mlang aoi generate --pr pr-123.json --policy ui.design-system

Example 4: CI Integration

# .github/workflows/pr-check.yml
name: PR Governance
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install -g @mdp-framework/mlang
      - run: mlang pr review --pr ${{ github.event.pull_request.number }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Troubleshooting

"Command not found: mlang"

Install the CLI globally:

npm install -g @mdp-framework/mlang

"No API key detected"

Set the API key:

export ANTHROPIC_API_KEY="your-key-here"

"Capsule not found"

Ensure capsule exists in .mlang/state/capsules/

"Policy not found"

Compile policies first:

mlang policy build --in policies/ --out .mlang/packs/stable

"Workflow failed: timeout"

Increase timeout in workflow config or use fewer agents

Development

# Clone repository
git clone https://github.com/mdp-labs/mdp-mlang.git
cd mdp-mlang

# Install dependencies
npm install

# Build CLI
cd packages/cli
npm run build

# Run tests
npm test

# Run in development mode
npm run dev

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT

Support

• GitHub Issues
• Documentation
• Contract Documents

Related

• Stream 6 Contract
• Stream 5 Multi-Agent
• Stream 4 AOI Coordinator
• Stream 2 AI Evaluators