@uluops/cli 0.2.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.
Files changed (99) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +825 -0
  3. package/dist/cli.d.ts +3 -0
  4. package/dist/cli.d.ts.map +1 -0
  5. package/dist/cli.js +93 -0
  6. package/dist/cli.js.map +1 -0
  7. package/dist/commands/analytics.d.ts +6 -0
  8. package/dist/commands/analytics.d.ts.map +1 -0
  9. package/dist/commands/analytics.js +445 -0
  10. package/dist/commands/analytics.js.map +1 -0
  11. package/dist/commands/auth.d.ts +6 -0
  12. package/dist/commands/auth.d.ts.map +1 -0
  13. package/dist/commands/auth.js +496 -0
  14. package/dist/commands/auth.js.map +1 -0
  15. package/dist/commands/completion.d.ts +7 -0
  16. package/dist/commands/completion.d.ts.map +1 -0
  17. package/dist/commands/completion.js +188 -0
  18. package/dist/commands/completion.js.map +1 -0
  19. package/dist/commands/config.d.ts +6 -0
  20. package/dist/commands/config.d.ts.map +1 -0
  21. package/dist/commands/config.js +279 -0
  22. package/dist/commands/config.js.map +1 -0
  23. package/dist/commands/definitions.d.ts +6 -0
  24. package/dist/commands/definitions.d.ts.map +1 -0
  25. package/dist/commands/definitions.js +229 -0
  26. package/dist/commands/definitions.js.map +1 -0
  27. package/dist/commands/deps.d.ts +6 -0
  28. package/dist/commands/deps.d.ts.map +1 -0
  29. package/dist/commands/deps.js +87 -0
  30. package/dist/commands/deps.js.map +1 -0
  31. package/dist/commands/exec.d.ts +6 -0
  32. package/dist/commands/exec.d.ts.map +1 -0
  33. package/dist/commands/exec.js +334 -0
  34. package/dist/commands/exec.js.map +1 -0
  35. package/dist/commands/executions.d.ts +6 -0
  36. package/dist/commands/executions.d.ts.map +1 -0
  37. package/dist/commands/executions.js +63 -0
  38. package/dist/commands/executions.js.map +1 -0
  39. package/dist/commands/forks.d.ts +6 -0
  40. package/dist/commands/forks.d.ts.map +1 -0
  41. package/dist/commands/forks.js +145 -0
  42. package/dist/commands/forks.js.map +1 -0
  43. package/dist/commands/issues.d.ts +6 -0
  44. package/dist/commands/issues.d.ts.map +1 -0
  45. package/dist/commands/issues.js +458 -0
  46. package/dist/commands/issues.js.map +1 -0
  47. package/dist/commands/models.d.ts +6 -0
  48. package/dist/commands/models.d.ts.map +1 -0
  49. package/dist/commands/models.js +156 -0
  50. package/dist/commands/models.js.map +1 -0
  51. package/dist/commands/projects.d.ts +6 -0
  52. package/dist/commands/projects.d.ts.map +1 -0
  53. package/dist/commands/projects.js +262 -0
  54. package/dist/commands/projects.js.map +1 -0
  55. package/dist/commands/render.d.ts +6 -0
  56. package/dist/commands/render.d.ts.map +1 -0
  57. package/dist/commands/render.js +59 -0
  58. package/dist/commands/render.js.map +1 -0
  59. package/dist/commands/runs.d.ts +6 -0
  60. package/dist/commands/runs.d.ts.map +1 -0
  61. package/dist/commands/runs.js +442 -0
  62. package/dist/commands/runs.js.map +1 -0
  63. package/dist/commands/taxonomy.d.ts +6 -0
  64. package/dist/commands/taxonomy.d.ts.map +1 -0
  65. package/dist/commands/taxonomy.js +45 -0
  66. package/dist/commands/taxonomy.js.map +1 -0
  67. package/dist/commands/translation.d.ts +6 -0
  68. package/dist/commands/translation.d.ts.map +1 -0
  69. package/dist/commands/translation.js +85 -0
  70. package/dist/commands/translation.js.map +1 -0
  71. package/dist/commands/versions.d.ts +6 -0
  72. package/dist/commands/versions.d.ts.map +1 -0
  73. package/dist/commands/versions.js +61 -0
  74. package/dist/commands/versions.js.map +1 -0
  75. package/dist/context.d.ts +85 -0
  76. package/dist/context.d.ts.map +1 -0
  77. package/dist/context.js +386 -0
  78. package/dist/context.js.map +1 -0
  79. package/dist/formatters/core.d.ts +31 -0
  80. package/dist/formatters/core.d.ts.map +1 -0
  81. package/dist/formatters/core.js +176 -0
  82. package/dist/formatters/core.js.map +1 -0
  83. package/dist/formatters/ops.d.ts +43 -0
  84. package/dist/formatters/ops.d.ts.map +1 -0
  85. package/dist/formatters/ops.js +112 -0
  86. package/dist/formatters/ops.js.map +1 -0
  87. package/dist/formatters/registry.d.ts +41 -0
  88. package/dist/formatters/registry.d.ts.map +1 -0
  89. package/dist/formatters/registry.js +167 -0
  90. package/dist/formatters/registry.js.map +1 -0
  91. package/dist/formatters/table.d.ts +18 -0
  92. package/dist/formatters/table.d.ts.map +1 -0
  93. package/dist/formatters/table.js +76 -0
  94. package/dist/formatters/table.js.map +1 -0
  95. package/dist/utils.d.ts +99 -0
  96. package/dist/utils.d.ts.map +1 -0
  97. package/dist/utils.js +201 -0
  98. package/dist/utils.js.map +1 -0
  99. package/package.json +57 -0
package/README.md ADDED
@@ -0,0 +1,825 @@
1
+ **[UluOps](https://uluops.ai)** · Operating Intelligence as Infrastructure
2
+
3
+ ---
4
+
5
+ # @uluops/cli
6
+
7
+ [![npm version](https://img.shields.io/npm/v/@uluops/cli.svg)](https://www.npmjs.com/package/@uluops/cli)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
9
+ [![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
10
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
11
+
12
+ Unified CLI for UluOps — validation tracking and registry management from a single command. Wraps both the [ops-sdk](../ops-sdk) and [registry-sdk](../registry-sdk) into an ergonomic terminal interface.
13
+
14
+ **Current version: 0.2.0** | [Changelog](./CHANGELOG.md)
15
+
16
+ ## Quick Start
17
+
18
+ ```bash
19
+ # Install
20
+ npm install -g @uluops/cli
21
+
22
+ # Authenticate
23
+ export ULUOPS_API_KEY=ulr_your-api-key-here
24
+
25
+ # Create a project and save a validation run
26
+ ulu projects create my-project
27
+ ulu runs save --file results.json
28
+
29
+ # Browse issues
30
+ ulu issues list my-project --status open --priority critical
31
+
32
+ # Check analytics
33
+ ulu analytics burndown --project my-project --days 30
34
+
35
+ # Run a validator agent
36
+ ulu exec agent code-validator ./src --model sonnet --project my-project
37
+ ```
38
+
39
+ ## Table of Contents
40
+
41
+ - [Features](#features)
42
+ - [Installation](#installation)
43
+ - [Authentication](#authentication)
44
+ - [Configuration](#configuration)
45
+ - [Global Options](#global-options)
46
+ - [Command Reference](#command-reference)
47
+ - [Auth](#auth) — Authentication & credential management
48
+ - [Config](#config) — CLI configuration & profiles
49
+ - [Projects](#projects) — Project lifecycle management
50
+ - [Runs](#runs) — Validation run management
51
+ - [Issues](#issues) — Issue tracking & management
52
+ - [Analytics](#analytics) — Validation analytics & metrics
53
+ - [Taxonomy](#taxonomy) — Failure taxonomy schema
54
+
55
+ - [Definitions](#definitions) — Workflow definition management
56
+ - [Versions](#versions) — Definition version history
57
+ - [Render](#render) — Definition rendering
58
+ - [Deps](#deps) — Dependency graphs
59
+ - [Forks](#forks) — Definition forking
60
+ - [Models](#models) — AI model catalog
61
+ - [Exec](#exec) — Execute agents, commands, and workflows
62
+ - [Executions](#executions) — Execution tracking
63
+ - [Translation](#translation) — Definition translation & upgrades
64
+ - [Completion](#completion) — Shell completion scripts
65
+ - [Output Modes](#output-modes)
66
+ - [Environment Variables](#environment-variables)
67
+ - [Error Handling](#error-handling)
68
+ - [Troubleshooting](#troubleshooting)
69
+ - [Related Packages](#related-packages)
70
+ - [License](#license)
71
+
72
+ ## Features
73
+
74
+ - **Unified interface**: Single `ulu` command covers both the validation tracker (ops) and definition registry APIs
75
+ - **Profile-based configuration**: Multiple environments via named profiles with independent credentials
76
+ - **Flexible authentication**: API key, session token, or email/password — same credential chain as the SDKs
77
+ - **Machine-friendly output**: `--json` flag on every command for scripting and CI/CD integration
78
+ - **Shell completion**: Tab completion for bash, zsh, and fish
79
+ - **Contextual error hints**: Actionable suggestions on auth failures, 404s, rate limits, and network errors
80
+ - **Spinner feedback**: Progress indicators for long operations (suppress with `-q`)
81
+
82
+ ## Installation
83
+
84
+ ```bash
85
+ # npm (global)
86
+ npm install -g @uluops/cli
87
+
88
+ # npx (no install)
89
+ npx @uluops/cli --help
90
+
91
+ # From source (monorepo)
92
+ cd packages/-uluops-cli
93
+ npm run build
94
+ node dist/cli.js --help
95
+ ```
96
+
97
+ **Requirements:**
98
+ - Node.js 18.0.0 or higher
99
+
100
+ ## Authentication
101
+
102
+ The CLI supports three authentication methods, resolved in priority order:
103
+
104
+ ### 1. API Key (Recommended)
105
+
106
+ ```bash
107
+ # Via flag
108
+ ulu projects list --api-key ulr_your-key
109
+
110
+ # Via environment variable (preferred)
111
+ export ULUOPS_API_KEY=ulr_your-api-key-here
112
+ ulu projects list
113
+ ```
114
+
115
+ ### 2. Session Token (Login)
116
+
117
+ ```bash
118
+ ulu auth login
119
+ # Prompts for email and password, stores session in ~/.uluops/credentials.json
120
+
121
+ ulu auth whoami
122
+ # Shows current authenticated user
123
+ ```
124
+
125
+ ### 3. Email/Password (Environment)
126
+
127
+ ```bash
128
+ export ULUOPS_EMAIL=user@example.com
129
+ export ULUOPS_PASSWORD=your-password
130
+ ulu projects list
131
+ ```
132
+
133
+ ### Credential Priority Chain
134
+
135
+ The CLI resolves credentials in this order:
136
+
137
+ 1. `--api-key` flag
138
+ 2. `ULUOPS_API_KEY` environment variable
139
+ 3. `ULUOPS_EMAIL` + `ULUOPS_PASSWORD` environment variables
140
+ 4. Session token stored by `ulu auth login`
141
+ 5. Profile credentials in `~/.uluops/credentials.json`
142
+ 6. Local `.env` file in the current directory
143
+
144
+ ## Configuration
145
+
146
+ ### Config Files
147
+
148
+ | File | Purpose |
149
+ |------|---------|
150
+ | `~/.uluops/profiles.json` | Profile settings (base URLs, default project, output preferences) |
151
+ | `~/.uluops/credentials.json` | Credentials per profile (API keys, session tokens) |
152
+ | `./.env` | Project-level environment overrides |
153
+
154
+ ### Profiles
155
+
156
+ Profiles let you maintain separate configurations for different environments:
157
+
158
+ ```bash
159
+ # Set config values on the default profile
160
+ ulu config set opsBaseUrl https://api.uluops.com/api/v1
161
+ ulu config set defaultProject my-project
162
+
163
+ # Create and switch to a new profile
164
+ ulu config use staging
165
+ ulu config set opsBaseUrl https://staging-api.uluops.com/api/v1
166
+
167
+ # Switch back
168
+ ulu config use default
169
+
170
+ # Use a profile for a single command
171
+ ulu projects list --profile staging
172
+
173
+ # View current config
174
+ ulu config list
175
+
176
+ # List all profiles
177
+ ulu config profiles
178
+ ```
179
+
180
+ ### Config Keys
181
+
182
+ | Key | Description | Default |
183
+ |-----|-------------|---------|
184
+ | `opsBaseUrl` | Validation tracker API URL | `http://localhost:3100/api/v1` |
185
+ | `registryBaseUrl` | Registry API URL | `http://localhost:3001/api/v1` |
186
+ | `defaultProject` | Default project for commands that accept `<project>` | - |
187
+ | `json` | Always output JSON | `false` |
188
+ | `quiet` | Suppress spinners | `false` |
189
+ | `debug` | Enable debug output | `false` |
190
+
191
+ ## Global Options
192
+
193
+ Every command accepts these flags:
194
+
195
+ ```
196
+ --api-key <key> Override API key (env: ULUOPS_API_KEY)
197
+ --profile <name> Config profile to use (default: 'default')
198
+ --base-url <url> Override API base URL
199
+ --json Output raw JSON for scripting
200
+ --debug Enable debug output
201
+ -q, --quiet Suppress spinners and non-essential output
202
+ -V, --version Show CLI version
203
+ -h, --help Show help for any command
204
+ ```
205
+
206
+ ## Command Reference
207
+
208
+ ### Auth
209
+
210
+ Authentication and credential management.
211
+
212
+ ```bash
213
+ ulu auth login # Login with email/password
214
+ ulu auth logout # Revoke all sessions
215
+ ulu auth whoami # Show current user
216
+ ulu auth register # Register new account
217
+ ulu auth forgot-password # Request password reset email
218
+ ulu auth reset-password # Reset password with token
219
+ ulu auth change-password # Change current password
220
+ ulu auth profile # View user profile
221
+ ulu auth update-profile # Update profile (display name, bio, avatar)
222
+ ulu auth sessions list # List active sessions
223
+ ulu auth sessions revoke <id> # Revoke a session
224
+ ulu auth api-keys list # List API keys
225
+ ulu auth api-keys create # Create new API key
226
+ ulu auth api-keys revoke <id> # Revoke an API key
227
+ ```
228
+
229
+ **Examples:**
230
+
231
+ ```bash
232
+ # Register and create an API key
233
+ ulu auth register --email user@example.com --password mypassword
234
+ ulu auth api-keys create --name "CI Pipeline"
235
+ # Save this key: ulr_abc123... (shown once)
236
+
237
+ # Login interactively
238
+ ulu auth login --email user@example.com --password mypassword
239
+
240
+ # Check who you are
241
+ ulu auth whoami
242
+ ```
243
+
244
+ ---
245
+
246
+ ### Config
247
+
248
+ CLI configuration and profile management.
249
+
250
+ ```bash
251
+ ulu config list # Show resolved config for active profile
252
+ ulu config get <key> # Get a config value
253
+ ulu config set <key> <value> # Set a config value
254
+ ulu config unset <key> # Remove a config value
255
+ ulu config profiles # List all profiles
256
+ ulu config use <profile> # Switch active profile
257
+ ulu config path # Show config file locations
258
+ ```
259
+
260
+ ---
261
+
262
+ ### Projects
263
+
264
+ Project lifecycle management.
265
+
266
+ ```bash
267
+ ulu projects list # List all projects
268
+ ulu projects get <name> # Get project details
269
+ ulu projects create <name> # Create new project
270
+ ulu projects delete <name> # Soft delete (--force for hard delete)
271
+ ulu projects restore <name> # Restore soft-deleted project
272
+ ulu projects summary <name> # Project summary with issue counts
273
+ ulu projects trends <name> # Issue trends over time
274
+ ulu projects rename <name> # Rename project (--new-name required)
275
+ ulu projects bulk-update-issues <name> # Batch update issue statuses
276
+ ulu projects merge-issues <name> # Merge duplicate issues
277
+ ```
278
+
279
+ **Examples:**
280
+
281
+ ```bash
282
+ # Create a project and check its summary
283
+ ulu projects create my-app
284
+ ulu projects summary my-app
285
+
286
+ # View trends for the last 90 days
287
+ ulu projects trends my-app --days 90
288
+
289
+ # Rename a project
290
+ ulu projects rename old-name --new-name new-name
291
+
292
+ # Soft delete and restore
293
+ ulu projects delete my-app
294
+ ulu projects restore my-app
295
+ ```
296
+
297
+ ---
298
+
299
+ ### Runs
300
+
301
+ Validation run management — save, compare, and archive pipeline results.
302
+
303
+ ```bash
304
+ ulu runs list <project> # List runs (--workflow, --limit)
305
+ ulu runs get <runId> # Get run by UUID
306
+ ulu runs latest <project> # Get latest run (--workflow)
307
+ ulu runs details <project> # Detailed run with agents/recommendations
308
+ ulu runs save # Save run from JSON (--file or --stdin)
309
+ ulu runs validate # Dry run — preview without saving
310
+ ulu runs diff <project> # Compare two runs (--base, --compare)
311
+ ulu runs archive <project> # Archive old runs (--before-run, --keep-last)
312
+ ulu runs update <project> # Update run metadata (--number, --score, --file)
313
+ ulu runs delete <runId> # Delete a run
314
+ ```
315
+
316
+ **Examples:**
317
+
318
+ ```bash
319
+ # Save a validation run from a JSON file
320
+ ulu runs save --file validation-results.json
321
+
322
+ # Save from stdin (pipe from another tool)
323
+ cat results.json | ulu runs save --stdin
324
+
325
+ # Dry run to preview what would happen
326
+ ulu runs validate --file results.json
327
+
328
+ # Compare run 1 vs run 5
329
+ ulu runs diff my-project --base 1 --compare 5
330
+
331
+ # Get latest run details
332
+ ulu runs latest my-project --workflow post-implementation
333
+
334
+ # Archive all but the last 10 runs
335
+ ulu runs archive my-project --keep-last 10
336
+
337
+ # Update token counts on a run after the fact
338
+ ulu runs update my-project --number 5 --file token-update.json
339
+ ```
340
+
341
+ ### Run Input Format
342
+
343
+ The JSON file for `ulu runs save` follows this structure:
344
+
345
+ ```json
346
+ {
347
+ "project": "my-project",
348
+ "workflow_type": "post-implementation",
349
+ "agents": [
350
+ {
351
+ "name": "code-validator",
352
+ "score": 85,
353
+ "decision": "PASS",
354
+ "model": "sonnet",
355
+ "tokens": { "input_tokens": 1000, "output_tokens": 500 }
356
+ }
357
+ ],
358
+ "recommendations": [
359
+ {
360
+ "agent": "code-validator",
361
+ "title": "Missing error handling",
362
+ "priority": "suggested",
363
+ "severity": "medium",
364
+ "file_path": "src/api/client.ts",
365
+ "line_number": 42
366
+ }
367
+ ],
368
+ "summary": {
369
+ "average_score": 85,
370
+ "all_gates_passed": true
371
+ }
372
+ }
373
+ ```
374
+
375
+ ---
376
+
377
+ ### Issues
378
+
379
+ Issue tracking and management.
380
+
381
+ ```bash
382
+ ulu issues list <project> # List issues with filters
383
+ ulu issues get <id> # Get issue (--full for occurrences/notes)
384
+ ulu issues search # Search across projects (--query)
385
+ ulu issues create # Create user-submitted issue
386
+ ulu issues update <id> # Update status (--status, --reason)
387
+ ulu issues close <id> # Mark as completed (--reason)
388
+ ulu issues edit <id> # Edit metadata (--title, --severity, etc.)
389
+ ulu issues add-note <id> # Add note (--message, --type)
390
+ ulu issues history <id> # Status change history
391
+ ulu issues undo <id> # Undo last status change
392
+ ulu issues restore <id> # Restore soft-deleted issue
393
+ ulu issues bulk-update # Bulk update statuses (--ids, --status)
394
+ ulu issues by-fingerprint <fp> # Get issue by SHA-256 fingerprint
395
+ ulu issues update-by-fingerprint <fp> # Update by fingerprint
396
+ ```
397
+
398
+ **Examples:**
399
+
400
+ ```bash
401
+ # List open critical issues
402
+ ulu issues list my-project --status open --priority critical
403
+
404
+ # Search across all projects
405
+ ulu issues search --query "authentication" --status open
406
+
407
+ # Create an issue manually
408
+ ulu issues create --project my-project \
409
+ --title "SQL injection in login" \
410
+ --priority critical \
411
+ --severity critical \
412
+ --type security \
413
+ --file-path src/auth/login.ts \
414
+ --line-number 45
415
+
416
+ # Close an issue with a reason
417
+ ulu issues close abc123 --reason "Fixed in PR #42"
418
+
419
+ # Add a resolution note
420
+ ulu issues add-note abc123 --message "Root cause: race condition" --type resolution
421
+
422
+ # Undo an accidental status change
423
+ ulu issues undo abc123
424
+
425
+ # Bulk close multiple issues
426
+ ulu issues bulk-update --ids id1,id2,id3 --status completed --reason "Batch fix"
427
+ ```
428
+
429
+ **Filter options for `issues list`:**
430
+
431
+ | Flag | Values |
432
+ |------|--------|
433
+ | `--status` | `open`, `completed`, `deferred`, `wontfix`, `all` |
434
+ | `--priority` | `critical`, `suggested`, `backlog`, `all` |
435
+ | `--severity` | `critical`, `high`, `medium`, `low`, `info` |
436
+ | `--agent` | Any agent name (e.g., `code-validator`) |
437
+ | `--domain` | `STR`, `SEM`, `PRA`, `EPI` |
438
+ | `--limit` | Max results (default: 50) |
439
+
440
+ ---
441
+
442
+ ### Analytics
443
+
444
+ Validation analytics and trend metrics.
445
+
446
+ ```bash
447
+ ulu analytics agents # Agent performance (avg score, pass rate)
448
+ ulu analytics reliability # Agent reliability (false positive rate)
449
+ ulu analytics hotspots # Files with most issues
450
+ ulu analytics burndown # Taxonomy burndown time series
451
+ ulu analytics velocity # Rate of change per failure mode
452
+ ulu analytics discovery # New vs recurring issues timeline
453
+ ulu analytics matrix # Agent-taxonomy coverage matrix
454
+ ulu analytics resolution # Issue resolution rates by project
455
+ ulu analytics taxonomy # Taxonomy distribution
456
+ ulu analytics full-taxonomy # Full taxonomy analytics breakdown
457
+ ulu analytics trends # Trend summary metrics
458
+ ```
459
+
460
+ **Examples:**
461
+
462
+ ```bash
463
+ # Which agents are most effective?
464
+ ulu analytics agents --project my-project --days 30
465
+
466
+ # Which files keep generating issues?
467
+ ulu analytics hotspots --project my-project --limit 10
468
+
469
+ # Are we closing issues faster than opening them?
470
+ ulu analytics burndown --project my-project --days 90 --granularity weekly
471
+
472
+ # Which failure modes are growing fastest?
473
+ ulu analytics velocity --project my-project --threshold 50
474
+
475
+ # New issues vs recurring — is validation finding new problems?
476
+ ulu analytics discovery --project my-project --group-by week
477
+
478
+ # Coverage gaps — which domains lack agent coverage?
479
+ ulu analytics matrix --project my-project
480
+
481
+ # Reliability — which agents have high false positive rates?
482
+ ulu analytics reliability --days 90
483
+ ```
484
+
485
+ ---
486
+
487
+ ### Taxonomy
488
+
489
+ Inspect the failure taxonomy schema.
490
+
491
+ ```bash
492
+ ulu taxonomy get # Display domains, severity codes, statuses
493
+ ```
494
+
495
+ Displays the four failure domains (STR, SEM, PRA, EPI), their failure modes, severity levels, and priority tiers.
496
+
497
+ ---
498
+
499
+ ### Definitions
500
+
501
+ Workflow definition management (registry API). Alias: `def`.
502
+
503
+ ```bash
504
+ ulu definitions list # List definitions (--type, --status, --search)
505
+ ulu definitions get <type> <name> [version] # Get definition (--yaml)
506
+ ulu definitions create <type> <name> # Create draft (--file)
507
+ ulu definitions update <type> <name> <ver> # Update draft (--file)
508
+ ulu definitions publish <type> <name> <ver> # Publish definition
509
+ ulu definitions deprecate <type> <name> <ver> # Deprecate (--reason, --successor)
510
+ ulu definitions validate <type> # Validate YAML (--file)
511
+ ulu definitions delete <type> <name> <ver> # Delete draft (--yes)
512
+ ```
513
+
514
+ **Definition types:** `agent`, `command`, `workflow`, `pipeline`
515
+
516
+ **Examples:**
517
+
518
+ ```bash
519
+ # List all published agents
520
+ ulu definitions list --type agent --status published
521
+
522
+ # Get a definition (YAML output)
523
+ ulu def get agent code-validator 1.0.0 --yaml
524
+
525
+ # Create, validate, and publish a new agent
526
+ ulu def validate agent --file my-agent.yaml
527
+ ulu def create agent my-agent --file my-agent.yaml
528
+ ulu def publish agent my-agent 1.0.0
529
+
530
+ # Deprecate an old version
531
+ ulu def deprecate agent old-agent 1.0.0 \
532
+ --reason "Replaced by new-agent" \
533
+ --successor new-agent@2.0.0
534
+ ```
535
+
536
+ ---
537
+
538
+ ### Versions
539
+
540
+ Definition version history and comparison.
541
+
542
+ ```bash
543
+ ulu versions list <type> <name> # List version history
544
+ ulu versions diff <type> <name> <from> <to> # Compare two versions
545
+ ```
546
+
547
+ ---
548
+
549
+ ### Render
550
+
551
+ Render definitions to markdown.
552
+
553
+ ```bash
554
+ ulu render get <type> <name> <version> # Get rendered markdown
555
+ ulu render preview <type> # Preview YAML as markdown (--file)
556
+ ```
557
+
558
+ ---
559
+
560
+ ### Deps
561
+
562
+ Dependency graph inspection.
563
+
564
+ ```bash
565
+ ulu deps get <type> <name> <version> # Show dependency graph (--max-depth)
566
+ ulu deps dependents <type> <name> <version> # Show reverse dependencies
567
+ ```
568
+
569
+ ---
570
+
571
+ ### Forks
572
+
573
+ Definition forking and lineage.
574
+
575
+ ```bash
576
+ ulu forks list <type> <name> <version> # List forks
577
+ ulu forks create <type> <name> <version> # Fork definition (--fork-name)
578
+ ulu forks check <type> <name> <version> # Check if forkable
579
+ ulu forks lineage <type> <name> <version> # Show fork ancestry chain
580
+ ```
581
+
582
+ ---
583
+
584
+ ### Models
585
+
586
+ AI model catalog.
587
+
588
+ ```bash
589
+ ulu models list # List models (--provider, --tier, --capability)
590
+ ulu models get <provider> <id> # Get model details
591
+ ulu models providers # List providers
592
+ ulu models aliases # List model aliases
593
+ ulu models resolve <alias> # Resolve alias to concrete model
594
+ ulu models sync # Sync from providers (admin only)
595
+ ```
596
+
597
+ ---
598
+
599
+ ### Exec
600
+
601
+ Execute agents, commands, and workflows via the @uluops/core SDK.
602
+
603
+ ```bash
604
+ # Auto-detect definition type and execute
605
+ ulu exec run <name> <target>
606
+
607
+ # Execute an agent
608
+ ulu exec agent code-validator ./src --model sonnet
609
+
610
+ # Execute a saved command configuration
611
+ ulu exec command my-command ./src
612
+
613
+ # Execute a multi-phase workflow
614
+ ulu exec workflow post-implementation ./
615
+
616
+ # List available definitions
617
+ ulu exec list # All definitions
618
+ ulu exec list --type agent # Filter by type (agent, command, workflow, pipeline)
619
+ ulu exec list --domain security # Filter by domain
620
+
621
+ # Inspect a definition's metadata
622
+ ulu exec describe code-validator
623
+ ```
624
+
625
+ **Parent options** (apply to all subcommands):
626
+
627
+ | Option | Description |
628
+ |--------|-------------|
629
+ | `--local-definitions <dir>` | Local YAML definitions directory |
630
+ | `--registry-url <url>` | Override registry URL |
631
+ | `--project <name>` | Project name for result tracking |
632
+ | `--no-tracking` | Disable validation service submission |
633
+
634
+ **Shared options** (all `exec` subcommands):
635
+
636
+ | Option | Description |
637
+ |--------|-------------|
638
+ | `-p, --prompt <text>` | Operator directive or context for the agent |
639
+ | `-m, --model <model>` | Model override (alias, tier, or provider:modelId) |
640
+
641
+ **Agent-specific options** (`exec agent` only):
642
+
643
+ | Option | Description |
644
+ |--------|-------------|
645
+ | `--max-tokens <n>` | Maximum response tokens |
646
+ | `--max-steps <n>` | Maximum tool loop iterations (default: 50) |
647
+ | `--temperature <n>` | Generation temperature 0-1 (default: 0) |
648
+ | `--timeout <ms>` | Execution timeout in milliseconds |
649
+ | `--threshold-pass <n>` | Pass threshold score (agents) |
650
+ | `--threshold-warn <n>` | Warning threshold score (agents) |
651
+ | `--report <path>` | Write raw agent output report to file (single agent only) |
652
+ | `--features-list <path>` | Write structured features/recommendations to file (single agent only) |
653
+
654
+ **Examples:**
655
+
656
+ ```bash
657
+ # Run code-validator with a specific model
658
+ ulu exec agent code-validator . --model sonnet --project my-project
659
+
660
+ # Generator: tell the agent what to create
661
+ ulu exec agent aristotle-generator -t ./src \
662
+ -p "Create a health check endpoint for the Express API"
663
+
664
+ # Validator: provide focus context
665
+ ulu exec agent security-analyst -t ./src \
666
+ -p "Focus on the authentication middleware and JWT handling"
667
+
668
+ # Use local definitions instead of registry
669
+ ulu exec agent my-validator ./src \
670
+ --local-definitions ./agent-defs \
671
+ --project my-project
672
+
673
+ # Execute without tracking results
674
+ ulu exec workflow ship ./packages/api --no-tracking
675
+
676
+ # Inspect what a definition expects
677
+ ulu exec describe code-validator
678
+ ```
679
+
680
+ ---
681
+
682
+ ### Executions
683
+
684
+ Execution tracking for definitions.
685
+
686
+ ```bash
687
+ ulu executions record <type> <name> <version> # Record execution (--source)
688
+ ulu executions stats <type> <name> <version> # Get statistics (--window)
689
+ ```
690
+
691
+ ---
692
+
693
+ ### Translation
694
+
695
+ Definition translation and legacy upgrades.
696
+
697
+ ```bash
698
+ ulu translation version # Get translator version
699
+ ulu translation retranslate <type> <name> <ver> # Re-translate (--new-version)
700
+ ulu translation upgrade <type> <name> # Upgrade legacy YAML (--file)
701
+ ```
702
+
703
+ ---
704
+
705
+ ### Completion
706
+
707
+ Generate shell completion scripts.
708
+
709
+ ```bash
710
+ # Bash
711
+ ulu completion bash >> ~/.bashrc
712
+
713
+ # Zsh
714
+ ulu completion zsh >> ~/.zshrc
715
+
716
+ # Fish
717
+ ulu completion fish > ~/.config/fish/completions/ulu.fish
718
+ ```
719
+
720
+ ## Output Modes
721
+
722
+ | Mode | Flag | Description |
723
+ |------|------|-------------|
724
+ | **Human** | *(default)* | Pretty-printed tables and key-value output |
725
+ | **JSON** | `--json` | Raw JSON for scripting and piping |
726
+ | **Quiet** | `-q, --quiet` | Suppress spinners and non-essential output |
727
+ | **Debug** | `--debug` | Include request/response details |
728
+
729
+ ```bash
730
+ # Pipe JSON output to jq
731
+ ulu issues list my-project --json | jq '.[] | .title'
732
+
733
+ # Quiet mode for scripts
734
+ ulu runs save --file results.json -q
735
+
736
+ # Debug a failing command
737
+ ulu projects get my-project --debug
738
+ ```
739
+
740
+ ## Environment Variables
741
+
742
+ | Variable | Description | Default |
743
+ |----------|-------------|---------|
744
+ | `ULUOPS_API_KEY` | API key for authentication | - |
745
+ | `ULUOPS_EMAIL` | Email for session auth | - |
746
+ | `ULUOPS_PASSWORD` | Password for session auth | - |
747
+ | `ULUOPS_BASE_URL` | Ops API base URL | `http://localhost:3100/api/v1` |
748
+ | `ULUOPS_REGISTRY_URL` | Registry API base URL | `http://localhost:3001/api/v1` |
749
+ | `ULUOPS_AUTH_BASE_URL` | Auth endpoint base URL (for login/register) | Same as `ULUOPS_BASE_URL` |
750
+ | `ULUOPS_DEBUG` | Enable debug logging | `false` |
751
+
752
+ Create a `.env` file in your project directory:
753
+
754
+ ```env
755
+ ULUOPS_API_KEY=ulr_your-api-key-here
756
+ ULUOPS_BASE_URL=https://api.uluops.ai/api/v1/ops
757
+ ULUOPS_REGISTRY_URL=https://api.uluops.ai/api/v1/registry
758
+ ```
759
+
760
+ ## Error Handling
761
+
762
+ The CLI provides contextual error messages with actionable hints:
763
+
764
+ | Error | Hint |
765
+ |-------|------|
766
+ | **401 Unauthorized** | Check `ULUOPS_API_KEY` or run `ulu auth login` |
767
+ | **403 Forbidden** | Insufficient permissions — contact admin |
768
+ | **404 Not Found** | Verify the resource name or ID |
769
+ | **400 Validation** | Check command arguments — run with `--help` |
770
+ | **429 Rate Limited** | Wait and retry — the CLI shows the retry delay |
771
+ | **Network Error** | Check server status and base URL config |
772
+
773
+ All errors include the HTTP status code and server error code when available. Use `--debug` for full request/response details.
774
+
775
+ ## Troubleshooting
776
+
777
+ ### "Authentication required" on every command
778
+
779
+ ```bash
780
+ # Verify your credentials are set
781
+ echo $ULUOPS_API_KEY
782
+ ulu auth whoami
783
+
784
+ # Check which profile is active
785
+ ulu config list
786
+ ```
787
+
788
+ ### "Connection refused" errors
789
+
790
+ ```bash
791
+ # Check the configured base URL
792
+ ulu config get opsBaseUrl
793
+
794
+ # Test server connectivity
795
+ curl http://localhost:3100/api/v1/health
796
+ ```
797
+
798
+ ### Commands targeting the wrong environment
799
+
800
+ ```bash
801
+ # Check active profile
802
+ ulu config profiles
803
+
804
+ # Override for a single command
805
+ ulu projects list --profile production --base-url https://api.uluops.com/api/v1
806
+ ```
807
+
808
+ ### Shell completion not working
809
+
810
+ ```bash
811
+ # Regenerate and source the completion script
812
+ ulu completion bash >> ~/.bashrc
813
+ source ~/.bashrc
814
+ ```
815
+
816
+ ## Related Packages
817
+
818
+ | Package | Description |
819
+ |---------|-------------|
820
+ | [`@uluops/ops-sdk`](../ops-sdk) | TypeScript SDK for the validation tracker API |
821
+ | [`@uluops/registry-sdk`](../registry-sdk) | TypeScript SDK for the definition registry API |
822
+
823
+ ## License
824
+
825
+ MIT License - see [LICENSE](./LICENSE) for details.