CALM CLI

CALM CLI is a comprehensive command-line interface for working with the Common Architecture Language Model (CALM). It provides tools for generating architecture shells from patterns, validating architectures against patterns with detailed error reporting, serving validation operations via HTTP API, generating documentation websites from CALM models, processing templates, and setting up AI-powered development assistance through VSCode chatmode integration.

Package Information

• Package Name: @finos/calm-cli
• Package Type: npm
• Language: TypeScript
• Installation: npm install -g @finos/calm-cli

Basic Usage

CLI Installation and Usage

# Install globally
npm install -g @finos/calm-cli

# View available commands
calm --help

# Generate architecture from pattern
calm generate -p pattern.json -o architecture.json

# Validate architecture against pattern
calm validate -a architecture.json -p pattern.json -f json

# Start validation server
calm server --port 3000 -s ./schemas

# Generate files from template
calm template -a architecture.json -b ./template-bundle -o ./output

# Generate documentation website
calm docify -a architecture.json -o ./docs

# Setup AI assistance
calm copilot-chatmode -d .

Architecture

CALM CLI is organized into several key modules:

• CLI Module (cli.ts): Main command setup using Commander.js, defining all CLI commands and options
• Configuration Module (cli-config.ts): User configuration file handling from ~/.calm.json
• Command Helpers: Modular implementations for each command (validate, template, generate-options, ai-tools)
• Server Module: Express-based HTTP server providing REST API for validation with rate limiting
• Server Routes: Health check and validation endpoints

The CLI depends heavily on @finos/calm-shared for core CALM functionality including schema validation, document loading, template processing, and documentation generation.

Capabilities

Generate Command

Generate an architecture shell from a CALM pattern file with interactive prompts for pattern options.

// CLI usage
calm generate [options]

// Options
interface GenerateCommandOptions {
  pattern: string;           // Path to pattern file or CalmHub URL (required)
  output?: string;           // Output path (default: "architecture.json")
  schemaDirectory?: string;  // Path to meta schemas directory
  calmHubUrl?: string;       // CALMHub instance URL
  verbose?: boolean;         // Enable verbose logging (default: false)
}

Generate Command Documentation

Validate Command

Validate that a CALM architecture conforms to a given pattern with detailed error and warning reporting.

// CLI usage
calm validate [options]

// Options
interface ValidateCommandOptions {
  pattern?: string;          // Path to pattern file or URL
  architecture?: string;     // Path to architecture file or URL
  schemaDirectory?: string;  // Path to meta schemas (default: CALM_META_SCHEMA_DIRECTORY)
  strict?: boolean;          // Fail on warnings (default: false)
  format?: 'json' | 'junit' | 'pretty'; // Output format (default: "json")
  output?: string;           // Output file path (stdout if not specified)
  verbose?: boolean;         // Enable verbose logging (default: false)
}

Validate Command Documentation

Server Command

Start an HTTP server to provide REST API access to CLI validation operations (experimental feature).

// CLI usage
calm server [options]

// Options
interface ServerCommandOptions {
  port?: string;             // Server port (default: "3000")
  schemaDirectory: string;   // Path to meta schemas directory (required)
  verbose?: boolean;         // Enable verbose logging (default: false)
}

Server Command Documentation

Template Command

Generate files from a CALM model using Handlebars template bundles, single templates, or template directories.

// CLI usage
calm template [options]

// Options
interface TemplateCommandOptions {
  architecture: string;              // Path to CALM architecture JSON file (required)
  output: string;                    // Output directory or file path (required)
  clearOutputDirectory?: boolean;    // Delete output directory contents first
  bundle?: string;                   // Path to template bundle directory
  template?: string;                 // Path to single .hbs or .md template file
  templateDir?: string;              // Path to directory of .hbs/.md templates
  urlToLocalFileMapping?: string;    // Path to URL mapping JSON file
  verbose?: boolean;                 // Enable verbose logging (default: false)
}

Template Command Documentation

Docify Command

Generate documentation websites from CALM models using templates or the built-in website generator.

// CLI usage
calm docify [options]

// Options
interface DocifyCommandOptions {
  architecture: string;              // Path to CALM architecture JSON file (required)
  output: string;                    // Output directory path (required)
  clearOutputDirectory?: boolean;    // Delete output directory contents first
  template?: string;                 // Path to single .hbs or .md template file
  templateDir?: string;              // Path to directory of .hbs/.md templates
  urlToLocalFileMapping?: string;    // Path to URL mapping JSON file
  verbose?: boolean;                 // Enable verbose logging (default: false)
}

Docify Command Documentation

Copilot Chatmode Command

Augment a git repository with CALM VSCode chatmode for AI-powered development assistance.

// CLI usage
calm copilot-chatmode [options]

// Options
interface CopilotChatmodeCommandOptions {
  directory?: string;        // Target directory (default: ".")
  verbose?: boolean;         // Enable verbose logging (default: false)
}

Copilot Chatmode Command Documentation

Configuration

User Configuration File

Location: ~/.calm.json

Format:

{
  "calmHubUrl": "https://your-calmhub-instance.com"
}

The configuration file is automatically loaded by the CLI when present. The calmHubUrl setting provides a default CALMHub URL for loading remote patterns and schemas, which can be overridden by the --calm-hub-url command-line option.

Verbose Logging

All commands support the -v, --verbose flag which enables detailed debug logging to help troubleshoot issues:

What verbose mode does:

• Logs document loading operations (files and URLs)
• Shows schema validation steps and warnings
• Displays file I/O operations and paths
• For template and docify commands, sets DEBUG=true environment variable
• Enables detailed error messages with stack traces

Usage examples:

# Debug architecture generation
calm generate -p pattern.json -o output.json -v

# Debug validation issues
calm validate -a architecture.json -p pattern.json -v

# Debug template processing
calm template -a architecture.json -b ./bundle -o ./output -v

# Debug server startup and requests
calm server --port 3000 -s ./schemas -v

Verbose mode is particularly useful when:

• Files or URLs fail to load
• Schema validation produces unexpected results
• Template processing doesn't generate expected output
• Troubleshooting configuration issues

URL-to-Local-File Mapping

For template and docify commands, you can provide a JSON file mapping external URLs to local file paths:

{
  "https://calm.finos.org/docuflow/flow/document-upload": "flows/flow-document-upload.json"
}

This is useful when working with CALM models that reference external files that are not yet published.

Error Handling

CLI Commands

• All commands use try-catch blocks with error logging
• Validation command exits with code 0 if no errors, 1 if errors present
• In strict mode, warnings also cause exit code 1
• Fatal errors in any command cause process exit with code 1

HTTP Server

• Rate limiting: 100 requests per 15 minutes per IP
• JSON parsing errors return 400 status
• Missing $schema field returns 400 status
• Schema loading errors return 500 status
• Validation errors return 500 status with error message
• All API endpoints return JSON responses

Common Errors

Validation Errors:

• Missing required options (pattern or architecture)
• Invalid JSON format in architecture
• Schema not found or unavailable
• Pattern/architecture file not found

Template/Docify Errors:

• Multiple conflicting options (bundle/template/templateDir)
• Missing required architecture or output options
• Invalid URL-to-local-file mapping format

Server Errors:

• Missing required schema directory
• Port already in use
• Rate limit exceeded (429 status)

AI Tools Errors:

• Target directory does not exist
• Missing bundled AI tool resources
• Failed to create chatmode directory

Dependencies

CALM CLI depends on @finos/calm-shared for core functionality:

• Document loading from files and URLs
• Schema validation and management
• Template processing with Handlebars
• Documentation generation
• Architecture generation from patterns
• Validation outcome formatting

External dependencies include:

• commander - CLI framework
• @inquirer/prompts - Interactive prompts
• express - HTTP server (for server command)
• express-rate-limit - Rate limiting (for server command)