@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.
- package/LICENSE +21 -0
- package/README.md +825 -0
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +93 -0
- package/dist/cli.js.map +1 -0
- package/dist/commands/analytics.d.ts +6 -0
- package/dist/commands/analytics.d.ts.map +1 -0
- package/dist/commands/analytics.js +445 -0
- package/dist/commands/analytics.js.map +1 -0
- package/dist/commands/auth.d.ts +6 -0
- package/dist/commands/auth.d.ts.map +1 -0
- package/dist/commands/auth.js +496 -0
- package/dist/commands/auth.js.map +1 -0
- package/dist/commands/completion.d.ts +7 -0
- package/dist/commands/completion.d.ts.map +1 -0
- package/dist/commands/completion.js +188 -0
- package/dist/commands/completion.js.map +1 -0
- package/dist/commands/config.d.ts +6 -0
- package/dist/commands/config.d.ts.map +1 -0
- package/dist/commands/config.js +279 -0
- package/dist/commands/config.js.map +1 -0
- package/dist/commands/definitions.d.ts +6 -0
- package/dist/commands/definitions.d.ts.map +1 -0
- package/dist/commands/definitions.js +229 -0
- package/dist/commands/definitions.js.map +1 -0
- package/dist/commands/deps.d.ts +6 -0
- package/dist/commands/deps.d.ts.map +1 -0
- package/dist/commands/deps.js +87 -0
- package/dist/commands/deps.js.map +1 -0
- package/dist/commands/exec.d.ts +6 -0
- package/dist/commands/exec.d.ts.map +1 -0
- package/dist/commands/exec.js +334 -0
- package/dist/commands/exec.js.map +1 -0
- package/dist/commands/executions.d.ts +6 -0
- package/dist/commands/executions.d.ts.map +1 -0
- package/dist/commands/executions.js +63 -0
- package/dist/commands/executions.js.map +1 -0
- package/dist/commands/forks.d.ts +6 -0
- package/dist/commands/forks.d.ts.map +1 -0
- package/dist/commands/forks.js +145 -0
- package/dist/commands/forks.js.map +1 -0
- package/dist/commands/issues.d.ts +6 -0
- package/dist/commands/issues.d.ts.map +1 -0
- package/dist/commands/issues.js +458 -0
- package/dist/commands/issues.js.map +1 -0
- package/dist/commands/models.d.ts +6 -0
- package/dist/commands/models.d.ts.map +1 -0
- package/dist/commands/models.js +156 -0
- package/dist/commands/models.js.map +1 -0
- package/dist/commands/projects.d.ts +6 -0
- package/dist/commands/projects.d.ts.map +1 -0
- package/dist/commands/projects.js +262 -0
- package/dist/commands/projects.js.map +1 -0
- package/dist/commands/render.d.ts +6 -0
- package/dist/commands/render.d.ts.map +1 -0
- package/dist/commands/render.js +59 -0
- package/dist/commands/render.js.map +1 -0
- package/dist/commands/runs.d.ts +6 -0
- package/dist/commands/runs.d.ts.map +1 -0
- package/dist/commands/runs.js +442 -0
- package/dist/commands/runs.js.map +1 -0
- package/dist/commands/taxonomy.d.ts +6 -0
- package/dist/commands/taxonomy.d.ts.map +1 -0
- package/dist/commands/taxonomy.js +45 -0
- package/dist/commands/taxonomy.js.map +1 -0
- package/dist/commands/translation.d.ts +6 -0
- package/dist/commands/translation.d.ts.map +1 -0
- package/dist/commands/translation.js +85 -0
- package/dist/commands/translation.js.map +1 -0
- package/dist/commands/versions.d.ts +6 -0
- package/dist/commands/versions.d.ts.map +1 -0
- package/dist/commands/versions.js +61 -0
- package/dist/commands/versions.js.map +1 -0
- package/dist/context.d.ts +85 -0
- package/dist/context.d.ts.map +1 -0
- package/dist/context.js +386 -0
- package/dist/context.js.map +1 -0
- package/dist/formatters/core.d.ts +31 -0
- package/dist/formatters/core.d.ts.map +1 -0
- package/dist/formatters/core.js +176 -0
- package/dist/formatters/core.js.map +1 -0
- package/dist/formatters/ops.d.ts +43 -0
- package/dist/formatters/ops.d.ts.map +1 -0
- package/dist/formatters/ops.js +112 -0
- package/dist/formatters/ops.js.map +1 -0
- package/dist/formatters/registry.d.ts +41 -0
- package/dist/formatters/registry.d.ts.map +1 -0
- package/dist/formatters/registry.js +167 -0
- package/dist/formatters/registry.js.map +1 -0
- package/dist/formatters/table.d.ts +18 -0
- package/dist/formatters/table.d.ts.map +1 -0
- package/dist/formatters/table.js +76 -0
- package/dist/formatters/table.js.map +1 -0
- package/dist/utils.d.ts +99 -0
- package/dist/utils.d.ts.map +1 -0
- package/dist/utils.js +201 -0
- package/dist/utils.js.map +1 -0
- 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
|
+
[](https://www.npmjs.com/package/@uluops/cli)
|
|
8
|
+
[](https://opensource.org/licenses/MIT)
|
|
9
|
+
[](https://nodejs.org/)
|
|
10
|
+
[](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.
|