0
# CALM CLI
1

2
> **NOTE**: @finos/calm-cli is a command-line tool only. It does not export functions for programmatic use in Node.js. All functionality is accessed exclusively through the `calm` command-line interface.
3

4
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.
5

6
## Package Information
7

8
- **Package Name**: @finos/calm-cli
9
- **Package Type**: npm
10
- **Language**: TypeScript
11
- **Installation**: `npm install -g @finos/calm-cli`
12

13
## Basic Usage
14

15
### CLI Installation and Usage
16

17
```bash
18
# Install globally
19
npm install -g @finos/calm-cli
20

21
# View available commands
22
calm --help
23

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

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

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

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

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

39
# Setup AI assistance
40
calm copilot-chatmode -d .
41
```
42

43
## Architecture
44

45
CALM CLI is organized into several key modules:
46

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

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

55
## Capabilities
56

57
### Generate Command
58

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

61
```typescript { .api }
62
// CLI usage
63
calm generate [options]
64

65
// Options
66
interface GenerateCommandOptions {
67
  pattern: string;           // Path to pattern file or CalmHub URL (required)
68
  output?: string;           // Output path (default: "architecture.json")
69
  schemaDirectory?: string;  // Path to meta schemas directory
70
  calmHubUrl?: string;       // CALMHub instance URL
71
  verbose?: boolean;         // Enable verbose logging (default: false)
72
}
73
```
74

75
[Generate Command Documentation](./generate-command.md)
76

77
### Validate Command
78

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

81
```typescript { .api }
82
// CLI usage
83
calm validate [options]
84

85
// Options
86
interface ValidateCommandOptions {
87
  pattern?: string;          // Path to pattern file or URL
88
  architecture?: string;     // Path to architecture file or URL
89
  schemaDirectory?: string;  // Path to meta schemas (default: CALM_META_SCHEMA_DIRECTORY)
90
  strict?: boolean;          // Fail on warnings (default: false)
91
  format?: 'json' | 'junit' | 'pretty'; // Output format (default: "json")
92
  output?: string;           // Output file path (stdout if not specified)
93
  verbose?: boolean;         // Enable verbose logging (default: false)
94
}
95
```
96

97
[Validate Command Documentation](./validate-command.md)
98

99
### Server Command
100

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

103
```typescript { .api }
104
// CLI usage
105
calm server [options]
106

107
// Options
108
interface ServerCommandOptions {
109
  port?: string;             // Server port (default: "3000")
110
  schemaDirectory: string;   // Path to meta schemas directory (required)
111
  verbose?: boolean;         // Enable verbose logging (default: false)
112
}
113
```
114

115
[Server Command Documentation](./server-command.md)
116

117
### Template Command
118

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

121
```typescript { .api }
122
// CLI usage
123
calm template [options]
124

125
// Options
126
interface TemplateCommandOptions {
127
  architecture: string;              // Path to CALM architecture JSON file (required)
128
  output: string;                    // Output directory or file path (required)
129
  clearOutputDirectory?: boolean;    // Delete output directory contents first
130
  bundle?: string;                   // Path to template bundle directory
131
  template?: string;                 // Path to single .hbs or .md template file
132
  templateDir?: string;              // Path to directory of .hbs/.md templates
133
  urlToLocalFileMapping?: string;    // Path to URL mapping JSON file
134
  verbose?: boolean;                 // Enable verbose logging (default: false)
135
}
136
```
137

138
[Template Command Documentation](./template-command.md)
139

140
### Docify Command
141

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

144
```typescript { .api }
145
// CLI usage
146
calm docify [options]
147

148
// Options
149
interface DocifyCommandOptions {
150
  architecture: string;              // Path to CALM architecture JSON file (required)
151
  output: string;                    // Output directory path (required)
152
  clearOutputDirectory?: boolean;    // Delete output directory contents first
153
  template?: string;                 // Path to single .hbs or .md template file
154
  templateDir?: string;              // Path to directory of .hbs/.md templates
155
  urlToLocalFileMapping?: string;    // Path to URL mapping JSON file
156
  verbose?: boolean;                 // Enable verbose logging (default: false)
157
}
158
```
159

160
[Docify Command Documentation](./docify-command.md)
161

162
### Copilot Chatmode Command
163

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

166
```typescript { .api }
167
// CLI usage
168
calm copilot-chatmode [options]
169

170
// Options
171
interface CopilotChatmodeCommandOptions {
172
  directory?: string;        // Target directory (default: ".")
173
  verbose?: boolean;         // Enable verbose logging (default: false)
174
}
175
```
176

177
[Copilot Chatmode Command Documentation](./copilot-chatmode-command.md)
178

179
## Configuration
180

181
### User Configuration File
182

183
Location: `~/.calm.json`
184

185
Format:
186

187
```json
188
{
189
  "calmHubUrl": "https://your-calmhub-instance.com"
190
}
191
```
192

193
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.
194

195
### Verbose Logging
196

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

199
**What verbose mode does:**
200
- Logs document loading operations (files and URLs)
201
- Shows schema validation steps and warnings
202
- Displays file I/O operations and paths
203
- For template and docify commands, sets `DEBUG=true` environment variable
204
- Enables detailed error messages with stack traces
205

206
**Usage examples:**
207

208
```bash
209
# Debug architecture generation
210
calm generate -p pattern.json -o output.json -v
211

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

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

218
# Debug server startup and requests
219
calm server --port 3000 -s ./schemas -v
220
```
221

222
Verbose mode is particularly useful when:
223
- Files or URLs fail to load
224
- Schema validation produces unexpected results
225
- Template processing doesn't generate expected output
226
- Troubleshooting configuration issues
227

228
### URL-to-Local-File Mapping
229

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

232
```json
233
{
234
  "https://calm.finos.org/docuflow/flow/document-upload": "flows/flow-document-upload.json"
235
}
236
```
237

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

240
## Error Handling
241

242
### CLI Commands
243

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

249
### HTTP Server
250

251
- Rate limiting: 100 requests per 15 minutes per IP
252
- JSON parsing errors return 400 status
253
- Missing `$schema` field returns 400 status
254
- Schema loading errors return 500 status
255
- Validation errors return 500 status with error message
256
- All API endpoints return JSON responses
257

258
### Common Errors
259

260
**Validation Errors:**
261
- Missing required options (pattern or architecture)
262
- Invalid JSON format in architecture
263
- Schema not found or unavailable
264
- Pattern/architecture file not found
265

266
**Template/Docify Errors:**
267
- Multiple conflicting options (bundle/template/templateDir)
268
- Missing required architecture or output options
269
- Invalid URL-to-local-file mapping format
270

271
**Server Errors:**
272
- Missing required schema directory
273
- Port already in use
274
- Rate limit exceeded (429 status)
275

276
**AI Tools Errors:**
277
- Target directory does not exist
278
- Missing bundled AI tool resources
279
- Failed to create chatmode directory
280

281
## Dependencies
282

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

285
- Document loading from files and URLs
286
- Schema validation and management
287
- Template processing with Handlebars
288
- Documentation generation
289
- Architecture generation from patterns
290
- Validation outcome formatting
291

292
External dependencies include:
293
- `commander` - CLI framework
294
- `@inquirer/prompts` - Interactive prompts
295
- `express` - HTTP server (for server command)
296
- `express-rate-limit` - Rate limiting (for server command)
297