@idiomark/cli 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,441 @@
1
- # Temporary Holding Version
1
+ # @idiomark/cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Command-line interface for Idiomark (Personality Characterization Protocol).
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ # Global installation
9
+ npm install -g @idiomark/cli
10
+
11
+ # Or use with npx
12
+ npx idiomark --help
13
+ ```
14
+
15
+ ## Quick Start
16
+
17
+ ```bash
18
+ # Clone a personality from Twitter
19
+ idiomark clone @user -t -o user.idiomark
20
+
21
+ # Become a personality (interactive chat)
22
+ idiomark become user.idiomark
23
+
24
+ # Compare two personalities
25
+ idiomark diff me.idiomark you.idiomark
26
+
27
+ # Quick identity dump
28
+ idiomark whoami user.idiomark
29
+
30
+ # Health check a personality
31
+ idiomark doctor user.idiomark
32
+
33
+ # Merge personalities
34
+ idiomark merge me.idiomark you.idiomark -o hybrid.idiomark
35
+ ```
36
+
37
+ ## Commands
38
+
39
+ ### Personality Extraction
40
+
41
+ | Command | Alias | Description |
42
+ |---------|-------|-------------|
43
+ | `idiomark clone <source>` | - | Clone personality from various sources (`@user`, `github:user`, URL) |
44
+ | `idiomark extract` | `x` | Extract personality from connected platforms |
45
+ | `idiomark init` | `n` | Create a new Idiomark file interactively |
46
+
47
+ #### `idiomark clone <source>`
48
+
49
+ Clone personality from various sources.
50
+
51
+ ```bash
52
+ # From Twitter handle
53
+ idiomark clone @twitter_user -t -o user.idiomark
54
+
55
+ # From GitHub username
56
+ idiomark clone github:github_user -g -o user.idiomark
57
+
58
+ # From URL (auto-detect)
59
+ idiomark clone https://twitter.com/user -o user.idiomark
60
+
61
+ # Multiple sources
62
+ idiomark clone @user -g -t -o user.idiomark
63
+ ```
64
+
65
+ **Options:**
66
+ | Flag | Description |
67
+ |-------|-------------|
68
+ | `-g, --github` | Include GitHub data |
69
+ | `-t, --twitter` | Include Twitter data |
70
+ | `-o, --output <file>` | Output file path |
71
+ | `-s, --sample-size <n>` | Number of posts to analyze (default: 1000) |
72
+ | `-v, --verbose` | Verbose output |
73
+
74
+ #### `idiomark extract`
75
+
76
+ Extract personality from connected platforms (requires prior auth).
77
+
78
+ ```bash
79
+ # Extract from multiple platforms
80
+ idiomark extract -t -g -o my-personality.idiomark
81
+
82
+ # With custom sample size
83
+ idiomark extract -t -s 5000 -o my-personality.idiomark
84
+ ```
85
+
86
+ **Options:**
87
+ | Flag | Description |
88
+ |-------|-------------|
89
+ | `-t, --twitter` | Include Twitter data |
90
+ | `-g, --github` | Include GitHub data |
91
+ | `-r, --reddit` | Include Reddit data |
92
+ | `-o, --output <file>` | Output file path (default: `entity.idiomark`) |
93
+ | `-s, --sample-size <n>` | Number of posts to analyze (default: 1000) |
94
+ | `-v, --verbose` | Verbose output |
95
+
96
+ #### `idiomark init`
97
+
98
+ Create a new Idiomark file interactively.
99
+
100
+ ```bash
101
+ # Interactive mode
102
+ idiomark init
103
+
104
+ # Direct arguments
105
+ idiomark init -n "Name" -t human -o entity.idiomark
106
+ ```
107
+
108
+ **Options:**
109
+ | Flag | Description |
110
+ |-------|-------------|
111
+ | `-n, --name <name>` | Entity name |
112
+ | `-t, --type <type>` | Entity type (`human`, `ai`, `fictional`) |
113
+ | `-o, --output <file>` | Output filename |
114
+
115
+ ### Personality Interaction
116
+
117
+ | Command | Alias | Description |
118
+ |---------|-------|-------------|
119
+ | `idiomark become <file>` | `chat`, `c` | Interactive chat with a Idiomark personality |
120
+ | `idiomark whoami <file>` | - | Quick identity dump of a Idiomark personality |
121
+
122
+ #### `idiomark become <file>`
123
+
124
+ Become a Idiomark personality (alias for `chat`).
125
+
126
+ ```bash
127
+ # Start interactive chat
128
+ idiomark become user.idiomark
129
+
130
+ # With specific model
131
+ idiomark become user.idiomark -p anthropic -m claude-3-5-sonnet-20241022
132
+
133
+ # Verbose mode
134
+ idiomark become user.idiomark -v
135
+
136
+ # Disable streaming
137
+ idiomark become user.idiomark --no-stream
138
+
139
+ # Send single message instead of interactive
140
+ idiomark become user.idiomark --message "What's your favorite color?"
141
+ ```
142
+
143
+ **Options:**
144
+ | Flag | Description |
145
+ |-------|-------------|
146
+ | `-p, --provider <provider>` | LLM provider: `anthropic`, `openai` (default: `anthropic`) |
147
+ | `-m, --model <model>` | AI model to use |
148
+ | `-v, --verbose` | Verbose output (token usage, etc.) |
149
+ | `--no-stream` | Disable streaming responses |
150
+ | `--message <msg>` | Send single message instead of interactive mode |
151
+
152
+ **Interactive Commands:**
153
+ - `exit` or `quit` - End chat session
154
+ - `clear` - Clear conversation history
155
+
156
+ #### `idiomark whoami <file>`
157
+
158
+ Quick identity dump of a Idiomark personality.
159
+
160
+ ```bash
161
+ idiomark whoami user.idiomark
162
+ ```
163
+
164
+ **Output includes:**
165
+ - Entity name and type
166
+ - Primary voice traits
167
+ - Top expertise domains
168
+ - Core values
169
+
170
+ ### Personality Operations
171
+
172
+ | Command | Alias | Description |
173
+ |---------|-------|-------------|
174
+ | `idiomark diff <file1> <file2>` | - | Compare two Idiomark personalities side-by-side |
175
+ | `idiomark merge <files...>` | - | Merge multiple Idiomark personalities into one |
176
+ | `idiomark doctor <file>` | - | Run health checks on a Idiomark file |
177
+
178
+ #### `idiomark diff <file1> <file2>`
179
+
180
+ Compare two Idiomark personalities side-by-side.
181
+
182
+ ```bash
183
+ idiomark diff me.idiomark you.idiomark
184
+ ```
185
+
186
+ **Output includes:**
187
+ - Voice trait comparison (formality, humor, enthusiasm, etc.)
188
+ - Expertise domain overlap
189
+ - Value similarity
190
+ - Communication pattern differences
191
+
192
+ #### `idiomark merge <files...>`
193
+
194
+ Merge multiple Idiomark personalities into one.
195
+
196
+ ```bash
197
+ # Equal weight merge
198
+ idiomark merge me.idiomark you.idiomark -o hybrid.idiomark
199
+
200
+ # Weighted merge
201
+ idiomark merge dominant.idiomark secondary.idiomark -w 0.7 0.3 -o blended.idiomark
202
+
203
+ # Multiple personalities
204
+ idiomark merge a.idiomark b.idiomark c.idiomark -o trio.idiomark
205
+ ```
206
+
207
+ **Options:**
208
+ | Flag | Description |
209
+ |-------|-------------|
210
+ | `-w, --weights <numbers...>` | Weights for each personality (equal if not specified) |
211
+ | `-o, --output <file>` | Output file path (default: `merged.idiomark`) |
212
+
213
+ #### `idiomark doctor <file>`
214
+
215
+ Run health checks on a Idiomark file.
216
+
217
+ ```bash
218
+ idiomark doctor user.idiomark
219
+ ```
220
+
221
+ **Checks:**
222
+ - Schema validation
223
+ - Required fields presence
224
+ - Data quality (outliers, inconsistencies)
225
+ - Adapter compatibility
226
+ - Projection support
227
+
228
+ ### File Operations
229
+
230
+ | Command | Alias | Description |
231
+ |---------|-------|-------------|
232
+ | `idiomark info <file>` | `i` | Display detailed information about a Idiomark file |
233
+ | `idiomark validate <file>` | `v` | Validate a Idiomark file |
234
+
235
+ #### `idiomark info <file>`
236
+
237
+ Display detailed information about a Idiomark file.
238
+
239
+ ```bash
240
+ idiomark info my-personality.idiomark
241
+ ```
242
+
243
+ **Output includes:**
244
+ - File metadata (ID, version, sources)
245
+ - Entity information (name, type)
246
+ - Extraction details (sample size, timeframe)
247
+ - Personality summary (voice, patterns, domains, values)
248
+
249
+ #### `idiomark validate <file>`
250
+
251
+ Validate a Idiomark file against the schema.
252
+
253
+ ```bash
254
+ # Standard validation
255
+ idiomark validate my-personality.idiomark
256
+
257
+ # Strict validation
258
+ idiomark validate my-personality.idiomark --strict
259
+ ```
260
+
261
+ **Options:**
262
+ | Flag | Description |
263
+ |-------|-------------|
264
+ | `-s, --strict` | Enable strict validation mode |
265
+
266
+ ### Server & Apply
267
+
268
+ | Command | Alias | Description |
269
+ |---------|-------|-------------|
270
+ | `idiomark serve <file>` | `s` | Start a local inference server with a personality |
271
+ | `idiomark apply <file>` | - | Apply a Idiomark personality to external systems |
272
+
273
+ #### `idiomark serve <file>`
274
+
275
+ Start a local inference server with a Idiomark personality.
276
+
277
+ ```bash
278
+ # Start server on default port 3000
279
+ idiomark serve my-personality.idiomark
280
+
281
+ # Custom port
282
+ idiomark serve my-personality.idiomark -p 8080
283
+
284
+ # With specific model
285
+ idiomark serve my-personality.idiomark -m gpt-4o
286
+ ```
287
+
288
+ **Options:**
289
+ | Flag | Description |
290
+ |-------|-------------|
291
+ | `-p, --port <number>` | Port to listen on (default: 3000) |
292
+ | `-m, --model <model>` | AI model to use (default: `gpt-4`) |
293
+
294
+ **Server Endpoints:**
295
+ | Endpoint | Method | Description |
296
+ |----------|----------|-------------|
297
+ | `/health` | GET | Health check |
298
+ | `/personality` | GET | View loaded personality |
299
+ | `/system-prompt` | GET | View system prompt |
300
+ | `/generate` | POST | Generate response with personality |
301
+ | `/stream` | POST | Stream response (SSE) |
302
+
303
+ #### `idiomark apply <file>`
304
+
305
+ Apply a Idiomark personality to external systems (MCP, UCP, HTTP).
306
+
307
+ ```bash
308
+ # Start MCP server
309
+ idiomark apply user.idiomark -m my-mcp-server
310
+
311
+ # Generate UCP merchant profile
312
+ idiomark apply user.idiomark -u merchant-123 --ucp-business-name "My Business"
313
+
314
+ # Start HTTP server
315
+ idiomark apply user.idiomark -p 8080
316
+ ```
317
+
318
+ **Options:**
319
+ | Flag | Description |
320
+ |-------|-------------|
321
+ | `-m, --mcp-server <name>` | Start MCP server with personality |
322
+ | `--mcp-transport <stdio|http>` | MCP transport method (default: `stdio`) |
323
+ | `--mcp-port <number>` | Port for MCP HTTP transport |
324
+ | `-u, --ucp-merchant <id>` | Generate UCP profile for merchant |
325
+ | `--ucp-business-name <name>` | Business name for UCP profile |
326
+ | `-p, --http-port <number>` | Start HTTP server on port |
327
+ | `--provider <anthropic|openai|auto>` | LLM provider (default: `auto`) |
328
+ | `--llm-model <model>` | AI model to use |
329
+
330
+ ### Configuration
331
+
332
+ | Command | Description |
333
+ |---------|-------------|
334
+ | `idiomark config` | View and edit Idiomark CLI configuration |
335
+
336
+ #### `idiomark config`
337
+
338
+ ```bash
339
+ # List all config values
340
+ idiomark config --list
341
+
342
+ # Get specific value
343
+ idiomark config --get defaultModel
344
+
345
+ # Set value
346
+ idiomark config --set defaultModel claude-3-5-sonnet-20241022
347
+
348
+ # Delete value
349
+ idiomark config --delete defaultModel
350
+
351
+ # Reset to defaults
352
+ idiomark config --reset
353
+
354
+ # Show config file path
355
+ idiomark config --path
356
+ ```
357
+
358
+ **Options:**
359
+ | Flag | Description |
360
+ |-------|-------------|
361
+ | `-l, --list` | List all config values (non-interactive) |
362
+ | `-g, --get <key>` | Get a specific config value |
363
+ | `-s, --set <key> <value>` | Set a config value |
364
+ | `-d, --delete <key>` | Delete a config value |
365
+ | `--reset` | Reset configuration to defaults |
366
+ | `--path` | Show config file path |
367
+
368
+ ### Adapters & Projections
369
+
370
+ | Command | Description |
371
+ |---------|-------------|
372
+ | `idiomark adapter` | Manage platform adapters for personality extraction |
373
+ | `idiomark projection` | Manage projection adapters for personality formats |
374
+
375
+ See [ADAPTERS.md](../../docs/ADAPTERS.md) for adapter documentation.
376
+
377
+ ## Examples
378
+
379
+ ### Extract and Chat Workflow
380
+
381
+ ```bash
382
+ # 1. Clone personality from Twitter
383
+ idiomark clone @user -t -o user.idiomark
384
+
385
+ # 2. View the extracted profile
386
+ idiomark info user.idiomark
387
+
388
+ # 3. Quick identity check
389
+ idiomark whoami user.idiomark
390
+
391
+ # 4. Chat with the personality
392
+ idiomark become user.idiomark
393
+ ```
394
+
395
+ ### Compare Personalities
396
+
397
+ ```bash
398
+ # Extract two personalities
399
+ idiomark clone @alice -t -o alice.idiomark
400
+ idiomark clone @bob -t -o bob.idiomark
401
+
402
+ # Compare them
403
+ idiomark diff alice.idiomark bob.idiomark
404
+
405
+ # Create a blend
406
+ idiomark merge alice.idiomark bob.idiomark -w 0.6 0.4 -o alicebob.idiomark
407
+ ```
408
+
409
+ ### Health Check
410
+
411
+ ```bash
412
+ # Validate and check health
413
+ idiomark validate user.idiomark
414
+ idiomark doctor user.idiomark
415
+ ```
416
+
417
+ ## Environment Variables
418
+
419
+ | Variable | Description | Required For |
420
+ |-----------|---------------|--------------|
421
+ | `ANTHROPIC_API_KEY` | Anthropic Claude API key | Anthropic provider |
422
+ | `OPENAI_API_KEY` | OpenAI API key | OpenAI provider |
423
+
424
+ ## Exit Codes
425
+
426
+ | Code | Meaning |
427
+ |-------|---------|
428
+ | 0 | Success |
429
+ | 1 | Generic error |
430
+ | 2 | File not found |
431
+ | 3 | Validation failed |
432
+
433
+ ## Related Packages
434
+
435
+ - [@idiomark/core](../core) - Core library
436
+ - [@idiomark/sdk](../sdk) - SDK for programmatic access
437
+ - See [docs/](../../docs/) for complete documentation
438
+
439
+ ## License
440
+
441
+ MIT
@@ -0,0 +1 @@
1
+ #!/usr/bin/env node