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