@kitelev/exocortex-cli 16.83.2 → 16.84.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 +197 -302
- package/dist/index.js +208 -281
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -22,15 +22,15 @@ Since v16.0 (RFC 8e83442b) the CLI follows a Unix-style surface built around **f
|
|
|
22
22
|
|
|
23
23
|
The following v15 verbs were **removed**: `batch`, `batch-repair`, `command`, `dyncommand`, `exoql`, `convert`, `sparql` (deprecated alias).
|
|
24
24
|
|
|
25
|
-
| Removed verb
|
|
26
|
-
|
|
|
27
|
-
| `sparql query` / `exoql` | `query` (top-level)
|
|
28
|
-
| `sparql index`
|
|
29
|
-
| `command <name> <path>`
|
|
30
|
-
| `dyncommand list`
|
|
31
|
-
| `dyncommand exec`
|
|
32
|
-
| `batch` / `batch-repair` | pipe `find` output into `apply` (multi-target stdin)
|
|
33
|
-
| `convert`
|
|
25
|
+
| Removed verb | v16 replacement |
|
|
26
|
+
| ------------------------ | ------------------------------------------------------------------------------- |
|
|
27
|
+
| `sparql query` / `exoql` | `query` (top-level) |
|
|
28
|
+
| `sparql index` | `index` (top-level) |
|
|
29
|
+
| `command <name> <path>` | `apply <cmd> [path]` — semantics live in vault-defined `exocmd__Command` assets |
|
|
30
|
+
| `dyncommand list` | `find --class exocmd__Command` |
|
|
31
|
+
| `dyncommand exec` | `apply` with `--dry-run` / `--yes` / `--input` |
|
|
32
|
+
| `batch` / `batch-repair` | pipe `find` output into `apply` (multi-target stdin) |
|
|
33
|
+
| `convert` | `query` with a CONSTRUCT query and `--format ntriples` |
|
|
34
34
|
|
|
35
35
|
**Documentation:**
|
|
36
36
|
|
|
@@ -42,30 +42,26 @@ The following v15 verbs were **removed**: `batch`, `batch-repair`, `command`, `d
|
|
|
42
42
|
|
|
43
43
|
## Command Overview
|
|
44
44
|
|
|
45
|
-
| Command
|
|
46
|
-
|
|
|
47
|
-
| [`find`](#find)
|
|
48
|
-
| [`apply`](#apply)
|
|
49
|
-
| [`query`](#query)
|
|
50
|
-
| [`index`](#index)
|
|
51
|
-
| [`validate`](#validate)
|
|
52
|
-
| [`ask`](#ask)
|
|
53
|
-
| [`classes`](#classes)
|
|
54
|
-
| [`create`](#create)
|
|
55
|
-
| [`resolve`](#resolve)
|
|
56
|
-
| [`watch`](#watch)
|
|
57
|
-
| [`workflow`](#workflow)
|
|
58
|
-
| [`
|
|
59
|
-
| [`
|
|
60
|
-
| [`
|
|
61
|
-
| [`
|
|
62
|
-
| [`
|
|
63
|
-
| [`
|
|
64
|
-
| [`
|
|
65
|
-
| [`apply-profile`](#apply-profile) | Apply an `exo__Profile` (mount-state filesystem mutation) |
|
|
66
|
-
| [`bootstrap`](#bootstrap) | Bootstrap a vault with the SDK floor AssetSpace |
|
|
67
|
-
| [`assetspace-add`](#assetspace-add) | Add a single AssetSpace to a vault by GitHub URL |
|
|
68
|
-
| [`experimental`](#experimental) | Opt-in experimental features (`rest-push`) |
|
|
45
|
+
| Command | Purpose |
|
|
46
|
+
| ----------------------------------- | ------------------------------------------------------------------------------ |
|
|
47
|
+
| [`find`](#find) | Select vault assets via SPARQL or class filter; prints file paths one per line |
|
|
48
|
+
| [`apply`](#apply) | Apply a vault-defined `exocmd__Command` to one or more assets |
|
|
49
|
+
| [`query`](#query) | Execute a SPARQL query against the vault |
|
|
50
|
+
| [`index`](#index) | Build or refresh the persistent triple cache |
|
|
51
|
+
| [`validate`](#validate) | Validate vault files: `iri`, `schema`, `frontmatter` |
|
|
52
|
+
| [`ask`](#ask) | Natural-language question (Russian or English) → SPARQL |
|
|
53
|
+
| [`classes`](#classes) | List vault classes or describe one class |
|
|
54
|
+
| [`create`](#create) | Create a new vault asset with auto-generated UUID and frontmatter |
|
|
55
|
+
| [`resolve`](#resolve) | Resolve a UUID (full or partial) to a file path |
|
|
56
|
+
| [`watch`](#watch) | Watch the vault for file changes; emit NDJSON events |
|
|
57
|
+
| [`workflow`](#workflow) | List / show / validate workflow definitions |
|
|
58
|
+
| [`recover`](#recover) | Detect and recover orphaned claude-child tmux sessions |
|
|
59
|
+
| [`daemon`](#daemon) | Manage the ValidatorDaemon background process |
|
|
60
|
+
| [`audit`](#audit) | Regression-pattern audits (`co-location`, `ontology-imports`) |
|
|
61
|
+
| [`apply-profile`](#apply-profile) | Apply an `exo__Profile` (mount-state filesystem mutation) |
|
|
62
|
+
| [`bootstrap`](#bootstrap) | Bootstrap a vault with the SDK floor AssetSpace |
|
|
63
|
+
| [`assetspace-add`](#assetspace-add) | Add a single AssetSpace to a vault by GitHub URL |
|
|
64
|
+
| [`experimental`](#experimental) | Opt-in experimental features (`rest-push`) |
|
|
69
65
|
|
|
70
66
|
---
|
|
71
67
|
|
|
@@ -81,12 +77,12 @@ npx @kitelev/exocortex-cli find --class ems__Task --vault ~/vault
|
|
|
81
77
|
|
|
82
78
|
**Options:**
|
|
83
79
|
|
|
84
|
-
| Option
|
|
85
|
-
|
|
|
86
|
-
| `--vault <path>`
|
|
87
|
-
| `--also <path>`
|
|
88
|
-
| `--sparql <query>` | —
|
|
89
|
-
| `--class <value>`
|
|
80
|
+
| Option | Default | Description |
|
|
81
|
+
| ------------------ | ------- | --------------------------------------------------------------------------------------------- |
|
|
82
|
+
| `--vault <path>` | cwd | Path to Obsidian vault |
|
|
83
|
+
| `--also <path>` | — | Additional vault to include (repeatable) |
|
|
84
|
+
| `--sparql <query>` | — | SPARQL SELECT query (must bind `?path`) |
|
|
85
|
+
| `--class <value>` | — | Filter by class label via the vault's `find__Alias` asset labelled `class` (e.g. `ems__Task`) |
|
|
90
86
|
|
|
91
87
|
Exactly one of `--sparql` or `--class` is required; they are mutually exclusive. `--class` requires a `find__Alias` asset with `exo__Asset_label: class` in the vault.
|
|
92
88
|
|
|
@@ -115,21 +111,21 @@ npx @kitelev/exocortex-cli apply <cmd> [path] [options]
|
|
|
115
111
|
|
|
116
112
|
**Arguments:**
|
|
117
113
|
|
|
118
|
-
| Argument | Description
|
|
119
|
-
|
|
|
120
|
-
| `<cmd>`
|
|
114
|
+
| Argument | Description |
|
|
115
|
+
| -------- | ------------------------------------------------------------------------------------- |
|
|
116
|
+
| `<cmd>` | UUID of an `exocmd__Command` asset, or its `exocmd__Command_cliName` slug |
|
|
121
117
|
| `[path]` | Vault-relative path to the target asset; omit to read paths from stdin (one per line) |
|
|
122
118
|
|
|
123
119
|
**Options:**
|
|
124
120
|
|
|
125
|
-
| Option
|
|
126
|
-
|
|
|
127
|
-
| `--vault <path>`
|
|
128
|
-
| `--dry-run`
|
|
129
|
-
| `--yes`
|
|
130
|
-
| `--input <json>`
|
|
131
|
-
| `--seed <uuid>`
|
|
132
|
-
| `--frozen-clock <iso>` | —
|
|
121
|
+
| Option | Default | Description |
|
|
122
|
+
| ---------------------- | ------- | ----------------------------------------------------------------- |
|
|
123
|
+
| `--vault <path>` | cwd | Path to Obsidian vault |
|
|
124
|
+
| `--dry-run` | off | Evaluate precondition and preview; do not write |
|
|
125
|
+
| `--yes` | off | Skip destructive-command confirmation |
|
|
126
|
+
| `--input <json>` | — | JSON object forwarded to `service_call` groundings as `userInput` |
|
|
127
|
+
| `--seed <uuid>` | — | Deterministic UID seed for test/replay |
|
|
128
|
+
| `--frozen-clock <iso>` | — | Freeze clock to an ISO timestamp for test/replay |
|
|
133
129
|
|
|
134
130
|
**Behavior:**
|
|
135
131
|
|
|
@@ -166,29 +162,29 @@ npx @kitelev/exocortex-cli query "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10" -
|
|
|
166
162
|
|
|
167
163
|
**Arguments:**
|
|
168
164
|
|
|
169
|
-
| Argument
|
|
170
|
-
|
|
|
165
|
+
| Argument | Description |
|
|
166
|
+
| --------- | ---------------------------------------------------------------------------------- |
|
|
171
167
|
| `[query]` | SPARQL query string or path to a `.sparql` file (optional if `--template` is used) |
|
|
172
168
|
|
|
173
169
|
**Options:**
|
|
174
170
|
|
|
175
|
-
| Option
|
|
176
|
-
|
|
|
177
|
-
| `--vault <path>`
|
|
178
|
-
| `--also <path>`
|
|
179
|
-
| `--format <type>`
|
|
180
|
-
| `--output <type>`
|
|
181
|
-
| `--timeout <duration>`
|
|
182
|
-
| `--dry-run`
|
|
183
|
-
| `--explain`
|
|
184
|
-
| `--stats`
|
|
185
|
-
| `--no-optimize`
|
|
186
|
-
| `--use-cache`
|
|
187
|
-
| `--cache-ttl <seconds>` | `300`
|
|
188
|
-
| `--no-cache`
|
|
189
|
-
| `--template <name>`
|
|
190
|
-
| `--param <params>`
|
|
191
|
-
| `--strict`
|
|
171
|
+
| Option | Default | Description |
|
|
172
|
+
| ----------------------- | ------- | -------------------------------------------------------------------------------------------- |
|
|
173
|
+
| `--vault <path>` | cwd | Path to Obsidian vault |
|
|
174
|
+
| `--also <path>` | — | Additional vault to include in the query (repeatable) |
|
|
175
|
+
| `--format <type>` | `table` | Output format: `table`, `json`, `csv`, `ntriples` |
|
|
176
|
+
| `--output <type>` | `text` | Response format: `text` or `json` (for MCP tools) |
|
|
177
|
+
| `--timeout <duration>` | `30s` | Query timeout (e.g. `30s`, `5000ms`); env fallback `EXOCORTEX_SPARQL_TIMEOUT` |
|
|
178
|
+
| `--dry-run` | off | Validate query syntax without executing (no vault loading) |
|
|
179
|
+
| `--explain` | off | Show the optimized query plan |
|
|
180
|
+
| `--stats` | off | Show execution statistics |
|
|
181
|
+
| `--no-optimize` | — | Disable query optimization |
|
|
182
|
+
| `--use-cache` | off | Use the persistent triple cache (faster vault loading) |
|
|
183
|
+
| `--cache-ttl <seconds>` | `300` | Query result cache TTL in seconds |
|
|
184
|
+
| `--no-cache` | — | Bypass the query result cache |
|
|
185
|
+
| `--template <name>` | — | Use a predefined query template |
|
|
186
|
+
| `--param <params>` | — | Template parameters (`key=value,key2=value2`) |
|
|
187
|
+
| `--strict` | off | Fail on unresolved label-form wikilinks in property paths (sets `EXOCORTEX_SPARQL_STRICT=1`) |
|
|
192
188
|
|
|
193
189
|
**Built-in templates:** `tasks-by-date`, `tasks-by-status`, `projects-active`, `concepts-by-domain`, `sleep-analysis`.
|
|
194
190
|
|
|
@@ -226,15 +222,15 @@ npx @kitelev/exocortex-cli index --vault ~/vault --stats
|
|
|
226
222
|
|
|
227
223
|
**Options:**
|
|
228
224
|
|
|
229
|
-
| Option
|
|
230
|
-
|
|
|
231
|
-
| `--vault <path>`
|
|
232
|
-
| `--also <path>`
|
|
233
|
-
| `--output <type>` | `text`
|
|
234
|
-
| `--stats`
|
|
235
|
-
| `--force`
|
|
236
|
-
| `--strict`
|
|
237
|
-
| `--no-inference`
|
|
225
|
+
| Option | Default | Description |
|
|
226
|
+
| ----------------- | ------- | -------------------------------------------------------------- |
|
|
227
|
+
| `--vault <path>` | cwd | Path to Obsidian vault |
|
|
228
|
+
| `--also <path>` | — | Additional vault to include in the combined index (repeatable) |
|
|
229
|
+
| `--output <type>` | `text` | Response format: `text` or `json` |
|
|
230
|
+
| `--stats` | off | Show cache statistics after building |
|
|
231
|
+
| `--force` | off | Force rebuild even if the cache is valid |
|
|
232
|
+
| `--strict` | off | Fail on the first invalid IRI instead of skipping |
|
|
233
|
+
| `--no-inference` | — | Disable RDFS `subClassOf` inference materialization |
|
|
238
234
|
|
|
239
235
|
### validate
|
|
240
236
|
|
|
@@ -248,25 +244,25 @@ npx @kitelev/exocortex-cli validate <iri|schema|frontmatter> [options]
|
|
|
248
244
|
|
|
249
245
|
Check vault files for IRI issues (spaces, special characters) without building the cache. Exits `1` if issues are found.
|
|
250
246
|
|
|
251
|
-
| Option
|
|
252
|
-
|
|
|
253
|
-
| `--vault <path>`
|
|
254
|
-
| `--output <type>` | `text`
|
|
247
|
+
| Option | Default | Description |
|
|
248
|
+
| ----------------- | ------- | --------------------------------- |
|
|
249
|
+
| `--vault <path>` | cwd | Path to Obsidian vault |
|
|
250
|
+
| `--output <type>` | `text` | Response format: `text` or `json` |
|
|
255
251
|
|
|
256
252
|
#### validate schema
|
|
257
253
|
|
|
258
254
|
Check frontmatter properties against the ontology (schema linting), or run SHACL-lite shapes validation with `--shapes-mode`. Exits `1` if violations are found.
|
|
259
255
|
|
|
260
|
-
| Option
|
|
261
|
-
|
|
|
262
|
-
| `--vault <path>`
|
|
263
|
-
| `--also <path>`
|
|
264
|
-
| `--output <type>` | `text`
|
|
265
|
-
| `--staged`
|
|
266
|
-
| `--use-cache`
|
|
267
|
-
| `--shapes-mode`
|
|
268
|
-
| `--format <type>` | `text`
|
|
269
|
-
| `--class <iri>`
|
|
256
|
+
| Option | Default | Description |
|
|
257
|
+
| ----------------- | ------- | -------------------------------------------------------------------------------------- |
|
|
258
|
+
| `--vault <path>` | cwd | Path to Obsidian vault |
|
|
259
|
+
| `--also <path>` | — | Additional vault merged into the validation graph (repeatable; disables `--use-cache`) |
|
|
260
|
+
| `--output <type>` | `text` | Response format: `text` or `json` |
|
|
261
|
+
| `--staged` | off | Only validate git-staged `.md` files (for pre-commit hooks) |
|
|
262
|
+
| `--use-cache` | off | Use the persistent triple cache (ignored when `--also` is set) |
|
|
263
|
+
| `--shapes-mode` | off | Run SHACL-lite shapes validation instead of schema linting |
|
|
264
|
+
| `--format <type>` | `text` | Shapes-mode output format: `text`, `json`, `earl` |
|
|
265
|
+
| `--class <iri>` | — | Only validate assets whose `exo__Instance_class` matches this IRI/slug |
|
|
270
266
|
|
|
271
267
|
```bash
|
|
272
268
|
# Strict SHACL-lite validation of the whole vault
|
|
@@ -280,11 +276,11 @@ npx @kitelev/exocortex-cli validate schema --staged --vault ~/vault
|
|
|
280
276
|
|
|
281
277
|
Check vault frontmatter for missing/empty properties and malformed IRIs.
|
|
282
278
|
|
|
283
|
-
| Option
|
|
284
|
-
|
|
|
285
|
-
| `--vault <path>`
|
|
286
|
-
| `--output <type>` | `text`
|
|
287
|
-
| `--staged`
|
|
279
|
+
| Option | Default | Description |
|
|
280
|
+
| ----------------- | ------- | ------------------------------------ |
|
|
281
|
+
| `--vault <path>` | cwd | Path to Obsidian vault |
|
|
282
|
+
| `--output <type>` | `text` | Response format: `text` or `json` |
|
|
283
|
+
| `--staged` | off | Only validate git-staged `.md` files |
|
|
288
284
|
|
|
289
285
|
---
|
|
290
286
|
|
|
@@ -299,13 +295,13 @@ npx @kitelev/exocortex-cli ask "активные проекты" --vault ~/vault
|
|
|
299
295
|
npx @kitelev/exocortex-cli ask "what tasks are due today" --show-query --vault ~/vault
|
|
300
296
|
```
|
|
301
297
|
|
|
302
|
-
| Option
|
|
303
|
-
|
|
|
304
|
-
| `--vault <path>`
|
|
305
|
-
| `--format <type>` | `table` | Output format: `table` or `json`
|
|
306
|
-
| `--output <type>` | `text`
|
|
307
|
-
| `--show-query`
|
|
308
|
-
| `--explain`
|
|
298
|
+
| Option | Default | Description |
|
|
299
|
+
| ----------------- | ------- | ------------------------------------------------- |
|
|
300
|
+
| `--vault <path>` | cwd | Path to Obsidian vault |
|
|
301
|
+
| `--format <type>` | `table` | Output format: `table` or `json` |
|
|
302
|
+
| `--output <type>` | `text` | Response format: `text` or `json` (for MCP tools) |
|
|
303
|
+
| `--show-query` | off | Show the generated SPARQL query |
|
|
304
|
+
| `--explain` | off | Show an explanation of the query conversion |
|
|
309
305
|
|
|
310
306
|
### classes
|
|
311
307
|
|
|
@@ -316,13 +312,13 @@ npx @kitelev/exocortex-cli classes --vault ~/vault
|
|
|
316
312
|
npx @kitelev/exocortex-cli classes ems__Task --vault ~/vault
|
|
317
313
|
```
|
|
318
314
|
|
|
319
|
-
| Argument / Option | Default | Description
|
|
320
|
-
|
|
|
321
|
-
| `[class-name]`
|
|
322
|
-
| `--vault <path>`
|
|
323
|
-
| `--format <type>` | `table` | Output format: `table` or `json`
|
|
324
|
-
| `--output <type>` | `text`
|
|
325
|
-
| `--use-cache`
|
|
315
|
+
| Argument / Option | Default | Description |
|
|
316
|
+
| ----------------- | ------- | ------------------------------------------------------ |
|
|
317
|
+
| `[class-name]` | — | Optional class name to show details (e.g. `ems__Task`) |
|
|
318
|
+
| `--vault <path>` | cwd | Path to Obsidian vault |
|
|
319
|
+
| `--format <type>` | `table` | Output format: `table` or `json` |
|
|
320
|
+
| `--output <type>` | `text` | Response format: `text` or `json` (for MCP tools) |
|
|
321
|
+
| `--use-cache` | off | Use the persistent cache (faster for repeated queries) |
|
|
326
322
|
|
|
327
323
|
### create
|
|
328
324
|
|
|
@@ -332,19 +328,19 @@ Create a new vault asset with auto-generated UUID, timestamps, and frontmatter.
|
|
|
332
328
|
npx @kitelev/exocortex-cli create --class ztlk__PermanentNote --label "My Note" --vault ~/vault
|
|
333
329
|
```
|
|
334
330
|
|
|
335
|
-
| Option
|
|
336
|
-
|
|
|
337
|
-
| `--class <name>`
|
|
338
|
-
| `--label <text>`
|
|
339
|
-
| `--vault <path>`
|
|
340
|
-
| `--aliases <names...>`
|
|
341
|
-
| `--property <key=value...>`
|
|
342
|
-
| `--body <text>`
|
|
343
|
-
| `--body-file <path>`
|
|
344
|
-
| `--dry-run`
|
|
345
|
-
| `--created-by <uuid>`
|
|
346
|
-
| `--timezone <tz>`
|
|
347
|
-
| `--skip-wikilink-validation` | off
|
|
331
|
+
| Option | Default | Description |
|
|
332
|
+
| ---------------------------- | ------------- | ------------------------------------------------------- |
|
|
333
|
+
| `--class <name>` | **required** | Class short name (e.g. `ztlk__PermanentNote`) or UUID |
|
|
334
|
+
| `--label <text>` | **required** | Human-readable label for the asset |
|
|
335
|
+
| `--vault <path>` | cwd | Path to Obsidian vault |
|
|
336
|
+
| `--aliases <names...>` | — | Additional aliases for the asset |
|
|
337
|
+
| `--property <key=value...>` | — | Property key-value pairs (repeatable) |
|
|
338
|
+
| `--body <text>` | — | Markdown body content (use `-` to read from stdin) |
|
|
339
|
+
| `--body-file <path>` | — | Read body content from a file |
|
|
340
|
+
| `--dry-run` | off | Preview the exact file content (stderr) without writing |
|
|
341
|
+
| `--created-by <uuid>` | — | Creator UUID |
|
|
342
|
+
| `--timezone <tz>` | `Asia/Almaty` | Timezone for timestamps |
|
|
343
|
+
| `--skip-wikilink-validation` | off | Skip wikilink existence validation |
|
|
348
344
|
|
|
349
345
|
```bash
|
|
350
346
|
# With custom properties and body from stdin
|
|
@@ -365,13 +361,13 @@ npx @kitelev/exocortex-cli resolve a1b2c3d4-e5f6-7890-abcd-ef1234567890 --vault
|
|
|
365
361
|
npx @kitelev/exocortex-cli resolve a1b2 --partial --format path --vault ~/vault
|
|
366
362
|
```
|
|
367
363
|
|
|
368
|
-
| Argument / Option | Default
|
|
369
|
-
|
|
|
370
|
-
| `<uuid>`
|
|
371
|
-
| `--vault <path>`
|
|
372
|
-
| `--format <type>` | `uri`
|
|
373
|
-
| `--output <type>` | `text`
|
|
374
|
-
| `--partial`
|
|
364
|
+
| Argument / Option | Default | Description |
|
|
365
|
+
| ----------------- | ------------ | ------------------------------------------------- |
|
|
366
|
+
| `<uuid>` | **required** | Full or partial UUID to resolve |
|
|
367
|
+
| `--vault <path>` | cwd | Path to Obsidian vault |
|
|
368
|
+
| `--format <type>` | `uri` | Output format: `uri`, `path`, or `json` |
|
|
369
|
+
| `--output <type>` | `text` | Response format: `text` or `json` (for MCP tools) |
|
|
370
|
+
| `--partial` | off | Match partial UUIDs (returns all matches) |
|
|
375
371
|
|
|
376
372
|
### watch
|
|
377
373
|
|
|
@@ -381,12 +377,12 @@ Watch the vault for file changes and emit NDJSON events on stdout (one JSON obje
|
|
|
381
377
|
npx @kitelev/exocortex-cli watch --vault ~/vault --asset-type ems__Task | jq -c 'select(.type == "modify")'
|
|
382
378
|
```
|
|
383
379
|
|
|
384
|
-
| Option
|
|
385
|
-
|
|
|
386
|
-
| `--vault <path>`
|
|
387
|
-
| `--pattern <glob>`
|
|
388
|
-
| `--asset-type <type>` | —
|
|
389
|
-
| `--debounce <ms>`
|
|
380
|
+
| Option | Default | Description |
|
|
381
|
+
| --------------------- | ------- | -------------------------------------------------------- |
|
|
382
|
+
| `--vault <path>` | cwd | Path to Obsidian vault |
|
|
383
|
+
| `--pattern <glob>` | — | Glob pattern to filter files (e.g. `*.md`, `tasks/**`) |
|
|
384
|
+
| `--asset-type <type>` | — | Filter by asset type from frontmatter (e.g. `ems__Task`) |
|
|
385
|
+
| `--debounce <ms>` | `100` | Per-file debounce interval in milliseconds |
|
|
390
386
|
|
|
391
387
|
Event shape: `{type: "create"|"modify"|"delete", path, relativePath, timestamp, assetType?}`. Watcher errors are emitted to stdout as structured JSON error events.
|
|
392
388
|
|
|
@@ -400,91 +396,14 @@ npx @kitelev/exocortex-cli workflow show <uid> --vault ~/vault
|
|
|
400
396
|
npx @kitelev/exocortex-cli workflow validate <uid> --vault ~/vault
|
|
401
397
|
```
|
|
402
398
|
|
|
403
|
-
| Subcommand
|
|
404
|
-
|
|
|
405
|
-
| `list`
|
|
406
|
-
| `show <uid>`
|
|
407
|
-
| `validate <uid>` | Validate a workflow definition
|
|
399
|
+
| Subcommand | Description |
|
|
400
|
+
| ---------------- | ------------------------------------------ |
|
|
401
|
+
| `list` | List all workflow definitions in the vault |
|
|
402
|
+
| `show <uid>` | Show details of a workflow definition |
|
|
403
|
+
| `validate <uid>` | Validate a workflow definition |
|
|
408
404
|
|
|
409
405
|
All subcommands accept `--vault <path>` (default: cwd) and `--output text|json` (default: `text`).
|
|
410
406
|
|
|
411
|
-
### archive
|
|
412
|
-
|
|
413
|
-
Archive assets from the active vault to a separate archive vault. Checks cross-references before moving so no links break. Four modes: default archival (requires `--class` and `--year`), `--verify`, `--cascade`, `--stats`. Result JSON is printed to stdout.
|
|
414
|
-
|
|
415
|
-
```bash
|
|
416
|
-
npx @kitelev/exocortex-cli archive \
|
|
417
|
-
--vault ~/vault --archive-vault ~/vault-archive \
|
|
418
|
-
--class ems__Task,ems__Meeting --year 2025
|
|
419
|
-
```
|
|
420
|
-
|
|
421
|
-
| Option | Default | Description |
|
|
422
|
-
| --- | --- | --- |
|
|
423
|
-
| `--vault <path>` | **required** | Path to the active vault |
|
|
424
|
-
| `--archive-vault <path>` | **required** | Path to the archive vault |
|
|
425
|
-
| `--class <names>` | — | Comma-separated class short names or UUIDs (required for archival mode) |
|
|
426
|
-
| `--year <year>` | — | Filter by resolution/end timestamp year (required for archival mode) |
|
|
427
|
-
| `--dry-run` | off | Preview without writing files |
|
|
428
|
-
| `--no-referenced` | — | Negation flag for the reference check (assets referenced by active files are skipped by default) |
|
|
429
|
-
| `--verify` | off | Verify archive integrity instead of archiving (read-only; exits `1` on issues) |
|
|
430
|
-
| `--cascade` | off | Iteratively resolve archived-to-archived chains (no `--class`/`--year` needed) |
|
|
431
|
-
| `--stats` | off | Print archive vault statistics by class and year (read-only) |
|
|
432
|
-
|
|
433
|
-
```bash
|
|
434
|
-
# Verify integrity (read-only)
|
|
435
|
-
npx @kitelev/exocortex-cli archive --verify --vault ~/vault --archive-vault ~/vault-archive
|
|
436
|
-
|
|
437
|
-
# Resolve archived-to-archived dependency chains after a bulk run
|
|
438
|
-
npx @kitelev/exocortex-cli archive --cascade --vault ~/vault --archive-vault ~/vault-archive
|
|
439
|
-
|
|
440
|
-
# Archive vault statistics
|
|
441
|
-
npx @kitelev/exocortex-cli archive --stats --vault ~/vault --archive-vault ~/vault-archive
|
|
442
|
-
```
|
|
443
|
-
|
|
444
|
-
### unarchive
|
|
445
|
-
|
|
446
|
-
Restore a single asset from the archive vault back to the active vault (reverse of `archive`). The restored file lands in `<active-vault>/03 Knowledge/inbox/`.
|
|
447
|
-
|
|
448
|
-
```bash
|
|
449
|
-
npx @kitelev/exocortex-cli unarchive \
|
|
450
|
-
--uuid ca0d0001-1111-2222-3333-444455556666 \
|
|
451
|
-
--vault ~/vault --archive-vault ~/vault-archive
|
|
452
|
-
```
|
|
453
|
-
|
|
454
|
-
| Option | Default | Description |
|
|
455
|
-
| --- | --- | --- |
|
|
456
|
-
| `--uuid <uuid>` | **required** | UUID of the asset to restore |
|
|
457
|
-
| `--vault <path>` | **required** | Path to the active vault |
|
|
458
|
-
| `--archive-vault <path>` | **required** | Path to the archive vault |
|
|
459
|
-
| `--dry-run` | off | Preview without writing files |
|
|
460
|
-
|
|
461
|
-
### backfill
|
|
462
|
-
|
|
463
|
-
Concept backfill tools for aiKnow assets. Parent command with two subcommands.
|
|
464
|
-
|
|
465
|
-
#### backfill suggest
|
|
466
|
-
|
|
467
|
-
Suggest concept backfill candidates for aiKnow assets, written as JSONL.
|
|
468
|
-
|
|
469
|
-
| Option | Default | Description |
|
|
470
|
-
| --- | --- | --- |
|
|
471
|
-
| `--aiKnow-dir <path>` | **required** | Path to the aiKnow assets directory |
|
|
472
|
-
| `--vault <path>` | — | Path to Obsidian vault (for finding concepts) |
|
|
473
|
-
| `--output <path>` | `~/.cache/exocortex/backfill-candidates.jsonl` | Output JSONL path |
|
|
474
|
-
| `--auto-threshold <number>` | `0.8` | Auto-approve confidence threshold |
|
|
475
|
-
| `--frequency-cap <number>` | `100` | Skip concepts with ≥N existing stamps in the aiKnow dir |
|
|
476
|
-
| `--dry-run` | on | Output JSONL but do not write to the vault (default mode) |
|
|
477
|
-
|
|
478
|
-
#### backfill orphan-terms
|
|
479
|
-
|
|
480
|
-
Extract high-frequency terms from aiKnow assets that have no matching `ims__Concept`.
|
|
481
|
-
|
|
482
|
-
| Option | Default | Description |
|
|
483
|
-
| --- | --- | --- |
|
|
484
|
-
| `--aiKnow-dir <path>` | **required** | Path to the aiKnow assets directory |
|
|
485
|
-
| `--vault <path>` | — | Path to Obsidian vault (for finding concepts) |
|
|
486
|
-
| `--top <number>` | `20` | Number of top orphan terms to return |
|
|
487
|
-
|
|
488
407
|
### recover
|
|
489
408
|
|
|
490
409
|
Detect and recover orphaned `claude-child` tmux sessions. A session is orphaned when its corresponding vault task is not in Doing status. Default mode is dry-run.
|
|
@@ -494,11 +413,11 @@ npx @kitelev/exocortex-cli recover --vault ~/vault-2025
|
|
|
494
413
|
npx @kitelev/exocortex-cli recover --apply --vault ~/vault-2025
|
|
495
414
|
```
|
|
496
415
|
|
|
497
|
-
| Option
|
|
498
|
-
|
|
|
499
|
-
| `--vault <path>` | `$EXOCORTEX_VAULT` or `~/vault-2025` | Path to Obsidian vault
|
|
500
|
-
| `--dry-run`
|
|
501
|
-
| `--apply`
|
|
416
|
+
| Option | Default | Description |
|
|
417
|
+
| ---------------- | ------------------------------------ | -------------------------------------------------------- |
|
|
418
|
+
| `--vault <path>` | `$EXOCORTEX_VAULT` or `~/vault-2025` | Path to Obsidian vault |
|
|
419
|
+
| `--dry-run` | — | List orphans without applying changes (default behavior) |
|
|
420
|
+
| `--apply` | off | Apply recovery: set Failed + kill the tmux session |
|
|
502
421
|
|
|
503
422
|
### daemon
|
|
504
423
|
|
|
@@ -508,26 +427,10 @@ Manage the ValidatorDaemon background process (long-running, Unix socket).
|
|
|
508
427
|
npx @kitelev/exocortex-cli daemon start
|
|
509
428
|
```
|
|
510
429
|
|
|
511
|
-
| Subcommand | Option
|
|
512
|
-
|
|
|
513
|
-
| `start`
|
|
514
|
-
| `start`
|
|
515
|
-
|
|
516
|
-
### migrate-relcolset-to-exolayout
|
|
517
|
-
|
|
518
|
-
Generate `exo__Layout` + `exo__BacklinksTableBlock` pairs from existing `ui__RelationColumnSet` configs. Dry-run by default; pass `--apply` to write.
|
|
519
|
-
|
|
520
|
-
```bash
|
|
521
|
-
npx @kitelev/exocortex-cli migrate-relcolset-to-exolayout --vault ~/vault # dry-run
|
|
522
|
-
npx @kitelev/exocortex-cli migrate-relcolset-to-exolayout --vault ~/vault --apply
|
|
523
|
-
```
|
|
524
|
-
|
|
525
|
-
| Option | Default | Description |
|
|
526
|
-
| --- | --- | --- |
|
|
527
|
-
| `--vault <path>` | **required** | Path to the source vault |
|
|
528
|
-
| `--out-dir <path>` | `exo-layout-migrated` | Vault-relative folder where generated files land on `--apply` |
|
|
529
|
-
| `--apply` | off | Write generated files to the vault (default: dry-run, prints to stderr) |
|
|
530
|
-
| `--json` | off | Emit the migration report as JSON to stdout |
|
|
430
|
+
| Subcommand | Option | Default | Description |
|
|
431
|
+
| ---------- | -------------------------- | ----------------------------------- | ---------------------------------- |
|
|
432
|
+
| `start` | `--socket <path>` | `~/.cache/exocortex/validator.sock` | Unix socket path |
|
|
433
|
+
| `start` | `--idle-timeout <seconds>` | `300` | Exit after N seconds of inactivity |
|
|
531
434
|
|
|
532
435
|
---
|
|
533
436
|
|
|
@@ -535,15 +438,7 @@ npx @kitelev/exocortex-cli migrate-relcolset-to-exolayout --vault ~/vault --appl
|
|
|
535
438
|
|
|
536
439
|
### audit
|
|
537
440
|
|
|
538
|
-
Audit the vault for regression patterns. Parent command with
|
|
539
|
-
|
|
540
|
-
#### audit grounding-type-literal-form
|
|
541
|
-
|
|
542
|
-
Detect any `exocmd__Grounding_type` in literal-string form (not wikilink) in vault frontmatter.
|
|
543
|
-
|
|
544
|
-
```bash
|
|
545
|
-
npx @kitelev/exocortex-cli audit grounding-type-literal-form --vault ~/vault
|
|
546
|
-
```
|
|
441
|
+
Audit the vault for regression patterns. Parent command with subcommands.
|
|
547
442
|
|
|
548
443
|
#### audit co-location
|
|
549
444
|
|
|
@@ -563,14 +458,14 @@ Apply the specified `exo__Profile` (mount-state filesystem mutation): materializ
|
|
|
563
458
|
npx @kitelev/exocortex-cli apply-profile <profile-uid> --vault ~/vault --yes --verbose
|
|
564
459
|
```
|
|
565
460
|
|
|
566
|
-
| Argument / Option | Default
|
|
567
|
-
|
|
|
568
|
-
| `<profile-uid>`
|
|
569
|
-
| `--vault <path>`
|
|
570
|
-
| `--yes`
|
|
571
|
-
| `--verbose`
|
|
572
|
-
| `--ref <branch>`
|
|
573
|
-
| `--token <pat>`
|
|
461
|
+
| Argument / Option | Default | Description |
|
|
462
|
+
| ----------------- | ------------ | -------------------------------------------------------------------------------- |
|
|
463
|
+
| `<profile-uid>` | **required** | Target Profile UID |
|
|
464
|
+
| `--vault <path>` | **required** | Path to Obsidian vault |
|
|
465
|
+
| `--yes` | off | Confirm apply (headless safety override) |
|
|
466
|
+
| `--verbose` | off | Print the plan summary to stderr before deciding |
|
|
467
|
+
| `--ref <branch>` | `main` | Git ref to pull when materializing AssetSpaces |
|
|
468
|
+
| `--token <pat>` | — | GitHub PAT for private-repo materialization (or env `GITHUB_TOKEN` / `GH_TOKEN`) |
|
|
574
469
|
|
|
575
470
|
Refuses (exit `5`) when profile resolution is degraded or the plan would strip the TS-floor AssetSpaces. Use `find --class exo__Profile` to list available profiles.
|
|
576
471
|
|
|
@@ -585,14 +480,14 @@ npx @kitelev/exocortex-cli bootstrap \
|
|
|
585
480
|
--exocmd https://github.com/kitelev/exoas-exocmd
|
|
586
481
|
```
|
|
587
482
|
|
|
588
|
-
| Option
|
|
589
|
-
|
|
|
590
|
-
| `--vault <path>` | **required** | Path to the target vault
|
|
591
|
-
| `--exo <url>`
|
|
592
|
-
| `--exocmd <url>` | —
|
|
593
|
-
| `--ref <branch>` | `main`
|
|
594
|
-
| `--token <pat>`
|
|
595
|
-
| `--json`
|
|
483
|
+
| Option | Default | Description |
|
|
484
|
+
| ---------------- | ------------ | ------------------------------------------------------------------------------------------- |
|
|
485
|
+
| `--vault <path>` | **required** | Path to the target vault |
|
|
486
|
+
| `--exo <url>` | **required** | Public GitHub URL of the exo TBox AssetSpace |
|
|
487
|
+
| `--exocmd <url>` | — | Optional GitHub URL of the exocmd UI-command AssetSpace; omit for a bare SDK/headless vault |
|
|
488
|
+
| `--ref <branch>` | `main` | Branch ref to pull from |
|
|
489
|
+
| `--token <pat>` | — | GitHub PAT for private repos (or env `GITHUB_TOKEN` / `GH_TOKEN`) |
|
|
490
|
+
| `--json` | off | Emit result as JSON |
|
|
596
491
|
|
|
597
492
|
### assetspace-add
|
|
598
493
|
|
|
@@ -604,14 +499,14 @@ npx @kitelev/exocortex-cli assetspace-add \
|
|
|
604
499
|
--url https://github.com/kitelev/exoas-pmbok-ontology
|
|
605
500
|
```
|
|
606
501
|
|
|
607
|
-
| Option
|
|
608
|
-
|
|
|
609
|
-
| `--vault <path>`
|
|
610
|
-
| `--url <url>`
|
|
611
|
-
| `--folder <name>` | URL-derived
|
|
612
|
-
| `--ref <branch>`
|
|
613
|
-
| `--token <pat>`
|
|
614
|
-
| `--json`
|
|
502
|
+
| Option | Default | Description |
|
|
503
|
+
| ----------------- | ------------ | ----------------------------------------------------------------- |
|
|
504
|
+
| `--vault <path>` | **required** | Path to the target vault |
|
|
505
|
+
| `--url <url>` | **required** | Public GitHub URL of the AssetSpace |
|
|
506
|
+
| `--folder <name>` | URL-derived | Local folder name under `assetspaces/` |
|
|
507
|
+
| `--ref <branch>` | `main` | Branch ref to pull from |
|
|
508
|
+
| `--token <pat>` | — | GitHub PAT for private repos (or env `GITHUB_TOKEN` / `GH_TOKEN`) |
|
|
509
|
+
| `--json` | off | Emit result as JSON |
|
|
615
510
|
|
|
616
511
|
### experimental
|
|
617
512
|
|
|
@@ -630,19 +525,19 @@ EXOCORTEX_EXPERIMENTAL_REST_PUSH=1 npx @kitelev/exocortex-cli experimental rest-
|
|
|
630
525
|
--token-from-gh
|
|
631
526
|
```
|
|
632
527
|
|
|
633
|
-
| Option
|
|
634
|
-
|
|
|
635
|
-
| `--repo <owner/repo>`
|
|
636
|
-
| `--branch <branch>`
|
|
637
|
-
| `--file <repoPath>`
|
|
638
|
-
| `--content <text>`
|
|
639
|
-
| `--content-file <localPath>` | —
|
|
640
|
-
| `--message <msg>`
|
|
641
|
-
| `--token-from-gh`
|
|
642
|
-
| `--token <pat>`
|
|
643
|
-
| `--experimental`
|
|
644
|
-
| `--api-base <url>`
|
|
645
|
-
| `--json`
|
|
528
|
+
| Option | Default | Description |
|
|
529
|
+
| ---------------------------- | ------------------------ | ------------------------------------------------------------------------- |
|
|
530
|
+
| `--repo <owner/repo>` | **required** | Target repo as `owner/repo` |
|
|
531
|
+
| `--branch <branch>` | `main` | Branch to commit on |
|
|
532
|
+
| `--file <repoPath>` | **required** | Path within the repo to write |
|
|
533
|
+
| `--content <text>` | — | Inline file content |
|
|
534
|
+
| `--content-file <localPath>` | — | Read file content from a local path |
|
|
535
|
+
| `--message <msg>` | **required** | Commit message |
|
|
536
|
+
| `--token-from-gh` | off | Resolve PAT via `gh auth token` |
|
|
537
|
+
| `--token <pat>` | — | GitHub PAT (or env `GITHUB_TOKEN` / `GH_TOKEN`); prefer `--token-from-gh` |
|
|
538
|
+
| `--experimental` | off | Opt in (alternative to `EXOCORTEX_EXPERIMENTAL_REST_PUSH=1`) |
|
|
539
|
+
| `--api-base <url>` | `https://api.github.com` | GitHub API base URL |
|
|
540
|
+
| `--json` | off | Emit result as JSON |
|
|
646
541
|
|
|
647
542
|
---
|
|
648
543
|
|
|
@@ -650,17 +545,17 @@ EXOCORTEX_EXPERIMENTAL_REST_PUSH=1 npx @kitelev/exocortex-cli experimental rest-
|
|
|
650
545
|
|
|
651
546
|
All commands use standardized exit codes following Unix conventions (`src/utils/ExitCodes.ts`):
|
|
652
547
|
|
|
653
|
-
| Code | Constant
|
|
654
|
-
|
|
|
655
|
-
| `0`
|
|
656
|
-
| `1`
|
|
657
|
-
| `2`
|
|
658
|
-
| `3`
|
|
659
|
-
| `4`
|
|
660
|
-
| `5`
|
|
661
|
-
| `6`
|
|
662
|
-
| `7`
|
|
663
|
-
| `8`
|
|
548
|
+
| Code | Constant | Description |
|
|
549
|
+
| ---- | -------------------------- | ----------------------------------------------- |
|
|
550
|
+
| `0` | `SUCCESS` | Command completed successfully |
|
|
551
|
+
| `1` | `GENERAL_ERROR` | General error (catch-all) |
|
|
552
|
+
| `2` | `INVALID_ARGUMENTS` | Invalid command-line arguments or options |
|
|
553
|
+
| `3` | `FILE_NOT_FOUND` | File or directory not found |
|
|
554
|
+
| `4` | `PERMISSION_DENIED` | Permission denied (file system access) |
|
|
555
|
+
| `5` | `OPERATION_FAILED` | Command execution failed (business logic error) |
|
|
556
|
+
| `6` | `INVALID_STATE_TRANSITION` | Invalid asset state transition |
|
|
557
|
+
| `7` | `TRANSACTION_FAILED` | Atomic operation could not complete |
|
|
558
|
+
| `8` | `CONCURRENT_MODIFICATION` | File changed during operation |
|
|
664
559
|
|
|
665
560
|
Validation commands (`validate iri`, `validate schema`, `audit co-location`, `archive --verify`) exit `1` when issues/violations are found, for CI/pre-commit integration.
|
|
666
561
|
|
|
@@ -671,7 +566,7 @@ Commands that accept `--output json` (e.g. `query`, `ask`, `classes`, `resolve`,
|
|
|
671
566
|
```json
|
|
672
567
|
{
|
|
673
568
|
"success": true,
|
|
674
|
-
"data": {
|
|
569
|
+
"data": {},
|
|
675
570
|
"meta": { "durationMs": 45, "itemCount": 3 }
|
|
676
571
|
}
|
|
677
572
|
```
|