@elevasis/sdk 1.48.0 → 1.49.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/dist/cli.cjs +742 -231
- package/dist/index.d.ts +685 -47
- package/dist/index.js +274 -40
- package/dist/node/index.d.ts +108 -24
- package/dist/test-utils/index.d.ts +647 -34
- package/dist/test-utils/index.js +240 -38
- package/dist/worker/index.d.ts +663 -39
- package/dist/worker/index.js +115 -6
- package/package.json +4 -4
- package/reference/_navigation.md +4 -4
- package/reference/_reference-manifest.json +1 -1
- package/reference/core/index.mdx +6 -4
- package/reference/index.mdx +11 -5
- package/reference/packages/core/src/README.md +46 -44
- package/reference/packages/core/src/content/README.md +13 -12
- package/reference/rules/ui.md +1 -1
- package/reference/rules/vibe-intents.md +2 -2
- package/reference/rules/vibe.md +30 -10
- package/reference/scaffold/recipes/extend-content.md +82 -3
- package/reference/sdk/cli-management.mdx +184 -41
- package/reference/sdk/cli.mdx +103 -64
- package/reference/sdk/define-builders.mdx +1 -1
- package/reference/sdk/deployment/command-center.mdx +2 -2
- package/reference/sdk/deployment/index.mdx +1 -1
- package/reference/sdk/exports.mdx +4 -4
- package/reference/sdk/framework/agent.mdx +4 -3
- package/reference/sdk/framework/index.mdx +1 -1
- package/reference/sdk/framework/project-structure.mdx +34 -23
- package/reference/sdk/framework/tutorial-system.mdx +1 -1
- package/reference/sdk/getting-started.mdx +25 -52
- package/reference/sdk/index.mdx +3 -3
- package/reference/sdk/platform-tools/adapters-integration.mdx +1 -1
- package/reference/sdk/platform-tools/adapters-platform.mdx +1 -1
- package/reference/sdk/platform-tools/type-safety.mdx +1 -1
- package/reference/sdk/resources/patterns.mdx +10 -11
- package/reference/sdk/resources/types.mdx +15 -9
- package/reference/sdk/templates/data-enrichment.mdx +1 -1
- package/reference/sdk/templates/email-sender.mdx +1 -1
- package/reference/sdk/templates/index.mdx +47 -47
- package/reference/sdk/templates/lead-scorer.mdx +1 -1
- package/reference/sdk/templates/pdf-generator.mdx +42 -24
- package/reference/sdk/templates/recurring-job.mdx +20 -15
- package/reference/sdk/templates/text-classifier.mdx +1 -1
- package/reference/sdk/templates/web-scraper.mdx +9 -5
- package/reference/ui/exports.mdx +1 -1
- package/reference/ui/index.mdx +2 -2
package/reference/rules/vibe.md
CHANGED
|
@@ -13,16 +13,16 @@ Vibe is **ambient and always on**. Every natural-language message is silently cl
|
|
|
13
13
|
|
|
14
14
|
## Quick Reference Table
|
|
15
15
|
|
|
16
|
-
| Intent | Trigger signal | Routed to
|
|
17
|
-
| ---------- | ------------------------------------------------------------------------------------------ |
|
|
18
|
-
| Capture | "add", "remember", "track", "log", "note for myself" + a thing | Agent -- draft + confirm + `project:*`, `note:create`, or `
|
|
19
|
-
| Query | "what's next", "what's pending", "what failed", "what systems", "what's waiting on review" | Agent -- read with `project:*`, `queue:*`, `schedule:*`, or `content:*` + narrate
|
|
20
|
-
| Describe | "what is", "tell me about", "explain", "where am I" | Agent -- narrate from org model labels
|
|
21
|
-
| Transition | "done", "stuck", "blocked", "finished", "complete", "approve", "pause" | Agent -- confirm + `project:task:save`, `queue:select`, `schedule:*`, or `content:review`
|
|
22
|
-
| Navigate | "focus on", "switch to", "back to", "look at" | Agent -- update scope + narrate
|
|
23
|
-
| Codify | "we are X", "we track Y", repeated attribute, "add type/field" | Delegate to `/om \<domain>`
|
|
24
|
-
| Toggle | "enable", "disable", "turn on/off" + system | Delegate to `/om systems` (tenant-local only)
|
|
25
|
-
| Operate | "run", "execute", "launch", "trigger", "kick off", "start" + deployed resource | Delegate to `/elevasis` -- `elevasis-sdk describe` + confirm + `elevasis-sdk exec`
|
|
16
|
+
| Intent | Trigger signal | Routed to |
|
|
17
|
+
| ---------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
|
|
18
|
+
| Capture | "add", "remember", "track", "log", "note for myself" + a thing | Agent -- draft + confirm + `project:*`, `note:create`, `schedule:create`, or `content:source-asset:create` CLI |
|
|
19
|
+
| Query | "what's next", "what's pending", "what failed", "what systems", "what's waiting on review" | Agent -- read with `project:*`, `queue:*`, `schedule:*`, or `content:*` + narrate |
|
|
20
|
+
| Describe | "what is", "tell me about", "explain", "where am I" | Agent -- narrate from org model labels |
|
|
21
|
+
| Transition | "done", "stuck", "blocked", "finished", "complete", "approve", "pause" | Agent -- confirm + `project:task:save`, `queue:select`, `schedule:*`, or `content:review` |
|
|
22
|
+
| Navigate | "focus on", "switch to", "back to", "look at" | Agent -- update scope + narrate |
|
|
23
|
+
| Codify | "we are X", "we track Y", repeated attribute, "add type/field" | Delegate to `/om \<domain>` |
|
|
24
|
+
| Toggle | "enable", "disable", "turn on/off" + system | Delegate to `/om systems` (tenant-local only) |
|
|
25
|
+
| Operate | "run", "execute", "launch", "trigger", "kick off", "start" + deployed resource | Delegate to `/elevasis` -- `elevasis-sdk describe` + confirm + `elevasis-sdk exec` |
|
|
26
26
|
|
|
27
27
|
## Safety Boundaries
|
|
28
28
|
|
|
@@ -34,6 +34,26 @@ Vibe is **ambient and always on**. Every natural-language message is silently cl
|
|
|
34
34
|
- **Never guess an ambiguous intent.** Ask one neutral clarifying question presenting the plausible intents. Do not apply a precedence rule and do not route to the "closest" match.
|
|
35
35
|
- **Never invent vocabulary.** Status, entity, and layer names come from the model's inline `label` fields, read verbatim -- never hardcoded synonyms.
|
|
36
36
|
|
|
37
|
+
## Deliberate Non-Routes
|
|
38
|
+
|
|
39
|
+
Not every registered CLI command gets a vibe route. `request:*` (`request:submit`, `request:list`,
|
|
40
|
+
`request:get`, `request:update`, `request:delete`) is deliberately absent from the classifier --
|
|
41
|
+
this is a decision, not an oversight. Escalation to the platform is skill-driven via
|
|
42
|
+
`submit-request`, and ambient routing of a write into the platform's inbound queue is a different
|
|
43
|
+
risk class from a route like `content:review`: a misclassified message would file a request on the
|
|
44
|
+
user's behalf with no confirmation ceremony designed for that specific write. If a future sweep
|
|
45
|
+
finds `request:` absent from this classifier corpus, that absence is this decision holding, not a
|
|
46
|
+
gap to close.
|
|
47
|
+
|
|
48
|
+
## Keeping the Classifier Current
|
|
49
|
+
|
|
50
|
+
Nothing today keeps this file and `vibe-intents.md` in step with new `elevasis-sdk` commands as
|
|
51
|
+
they ship -- a new command reaches the CLI with no gate that requires a matching classifier entry,
|
|
52
|
+
which is why `content:source-asset*` shipped in `@elevasis/sdk@1.48.0` with zero classifier hits
|
|
53
|
+
until this fix. Until an automated check exists, treat "does this new command need a vibe route"
|
|
54
|
+
as a required question on every CLI-surface change, the same way a new System's scaffold recipe is
|
|
55
|
+
a required question on every System-shaping change.
|
|
56
|
+
|
|
37
57
|
## Related Rules
|
|
38
58
|
|
|
39
59
|
- **vibe-intents.md** -- the detail body; open it when a message is hard to classify or a route needs its exact ceremony
|
|
@@ -104,6 +104,70 @@ Then set `content.config.defaultPipelineId` if this should be the pipeline the U
|
|
|
104
104
|
|
|
105
105
|
**The step catalog name is load-bearing.** `content:catalog/{pipelineId}-steps` must match the pipeline record's `stepCatalog` exactly. Nothing type-checks that string.
|
|
106
106
|
|
|
107
|
+
### Or declare it once with `defineContentPipeline`
|
|
108
|
+
|
|
109
|
+
The hand-written form above is fine and stays supported, but a pipeline is actually declared in **five** places, and missing one fails at runtime rather than at build:
|
|
110
|
+
|
|
111
|
+
1. the `content:catalog/pipeline` entry
|
|
112
|
+
2. the step catalog, whose id must match the string above exactly
|
|
113
|
+
3. `content.config.defaultPipelineId`
|
|
114
|
+
4. `apiInterface.readinessContract.requiredCatalogs`
|
|
115
|
+
5. each participating resource's `ontology.usesCatalogs`
|
|
116
|
+
|
|
117
|
+
`defineContentPipeline` takes one declaration and derives all five.
|
|
118
|
+
|
|
119
|
+
<!-- doc-snippet:skip: illustrative excerpt -- references project-local descriptors -->
|
|
120
|
+
|
|
121
|
+
```ts
|
|
122
|
+
import { buildContentPipelineCatalogs, defineContentPipeline } from '@elevasis/core/organization-model'
|
|
123
|
+
import { z } from 'zod'
|
|
124
|
+
|
|
125
|
+
export const podcastToClips = defineContentPipeline({
|
|
126
|
+
systemPath: 'content',
|
|
127
|
+
id: 'podcast-to-clips',
|
|
128
|
+
label: 'Podcast to Clips',
|
|
129
|
+
workspaceRoute: '/content/clips',
|
|
130
|
+
steps: [
|
|
131
|
+
{
|
|
132
|
+
key: 'transcript',
|
|
133
|
+
actor: 'workflow',
|
|
134
|
+
review: 'none',
|
|
135
|
+
advancesTo: 'clip-selection',
|
|
136
|
+
resource: transcribeEpisode,
|
|
137
|
+
payload: z.object({ transcriptPath: z.string() })
|
|
138
|
+
},
|
|
139
|
+
{
|
|
140
|
+
key: 'clip-selection',
|
|
141
|
+
actor: 'agent',
|
|
142
|
+
review: 'required',
|
|
143
|
+
advancesTo: 'publish',
|
|
144
|
+
resource: proposeClips,
|
|
145
|
+
payload: z.object({ candidateIds: z.array(z.string()) })
|
|
146
|
+
},
|
|
147
|
+
{ key: 'publish', actor: 'workflow', review: 'none', resource: publishClip }
|
|
148
|
+
]
|
|
149
|
+
})
|
|
150
|
+
|
|
151
|
+
// Inside the content System:
|
|
152
|
+
// ontology.catalogTypes: { ...buildContentPipelineCatalogs([podcastToClips]), ...yourOtherCatalogs }
|
|
153
|
+
// config: { defaultPipelineId: podcastToClips.defaultPipelineId }
|
|
154
|
+
// apiInterface: { resourceIds: podcastToClips.resourceIds,
|
|
155
|
+
// readinessContract: { requiredCatalogs: [...podcastToClips.requiredCatalogs,
|
|
156
|
+
// 'content:catalog/status'] } }
|
|
157
|
+
// And on each participating resource:
|
|
158
|
+
// ontology: { usesCatalogs: podcastToClips.usesCatalogs }
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Three failure modes stop being possible:
|
|
162
|
+
|
|
163
|
+
- **`resource` is a descriptor reference, not a string.** Deleting a workflow is a type error at the declaration site instead of a readiness failure at deploy.
|
|
164
|
+
- **`payloadFields` derives from `payload`.** The declared field list and the schema your producer emits cannot drift, because there is only one of them. Use `.meta({ label, contentFieldType })` on a field to override a derived label or force `'text'` — nothing in a Zod schema distinguishes a long body from a short string.
|
|
165
|
+
- **`workspaceRoute` gets a type**, and is validated for the leading slash at declaration time. The raw catalog entry type is open, which is how a route rename can point production at a dead path with every gate green.
|
|
166
|
+
|
|
167
|
+
`buildContentPipelineCatalogs` exists because the pipeline catalog is **shared**: every pipeline in a System is an entry in the same `content:catalog/pipeline` record, so spreading two definitions independently would have the second silently replace the first. Call it once per System with all of them.
|
|
168
|
+
|
|
169
|
+
Steps stay catalog data either way. Adding one remains an org-model edit plus a workflow, never a shared-UI or route change — the helper removes no expressiveness, it stops one fact being written in five files.
|
|
170
|
+
|
|
107
171
|
## 2. Produce a Step in a Workflow
|
|
108
172
|
|
|
109
173
|
One workflow per step. The workflow records an **attempt** against the item, tagged with the step it satisfies.
|
|
@@ -178,13 +242,17 @@ export const clipSelectionWorkflow: WorkflowDefinition = {
|
|
|
178
242
|
}
|
|
179
243
|
```
|
|
180
244
|
|
|
181
|
-
`ContentToolMap` is the full surface,
|
|
245
|
+
`ContentToolMap` is the full surface, 19 methods: `createItem`, `getItem`, `listItems`, `updateItem`, `addItemSourceAsset`, `removeItemSourceAsset`, `reorderItemSourceAssets`, `updateItemSourceAsset`, `createAttempt`, `listAttempts`, `updateAttempt`, `createSourceAsset`, `getSourceAsset`, `listSourceAssets`, `updateSourceAsset`, `getDistribution`, `listDistributions`, `createDistribution`, `updateDistribution`. `organizationId` is injected server-side — never pass it from workflow code.
|
|
182
246
|
|
|
183
247
|
**`reviewItem` is deliberately not on this list.** Clearing a `queued` review gate is operator work, done through `elevasis-sdk content:review` (see `apps/docs/content/docs/sdk/sdk/cli-management.mdx`), not something a producer workflow can call. A producer approving its own output collapses the gate the review step exists to provide.
|
|
184
248
|
|
|
185
249
|
### Source Assets
|
|
186
250
|
|
|
187
|
-
`createSourceAsset`, `getSourceAsset`, `listSourceAssets`, and `updateSourceAsset` manage the raw material a producer works from -- an uploaded podcast episode, a transcript, a reference file -- independent of any content item. A producer lists or fetches source assets to pick material, then references the chosen one
|
|
251
|
+
`createSourceAsset`, `getSourceAsset`, `listSourceAssets`, and `updateSourceAsset` manage the raw material a producer works from -- an uploaded podcast episode, a transcript, a reference file -- independent of any content item. A producer lists or fetches source assets to pick material, then references the chosen one when it calls `createItem`. Source assets have their own `kind`-keyed payload envelope, declared per-kind in the content System's OM catalog, the same pattern `createItem`'s payload uses.
|
|
252
|
+
|
|
253
|
+
### Item Membership (Which Assets Are In Which Item)
|
|
254
|
+
|
|
255
|
+
A content item's membership in `content_item_source_assets` -- which source assets it carries, in what slide order, with what per-slide crop and alt text -- is a separate concern from the source asset row itself, and it is owned entirely by four dedicated methods: `addItemSourceAsset`, `removeItemSourceAsset`, `reorderItemSourceAssets`, and `updateItemSourceAsset`. `createItem` also accepts an initial ordered `sourceAssets` list, so a carousel can be created with its full membership in one call; `updateItem` deliberately does not accept a `sourceAssets` field, and every membership change after creation goes through the four methods above.
|
|
188
256
|
|
|
189
257
|
## 3. Give Producers Their Instructions
|
|
190
258
|
|
|
@@ -299,12 +367,23 @@ video, then copy plus a schedule, is three screens, not one:
|
|
|
299
367
|
<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
|
|
300
368
|
|
|
301
369
|
```ts
|
|
302
|
-
'render-video': { actor: 'workflow', reviewMode: '
|
|
370
|
+
'render-video': { actor: 'workflow', reviewMode: 'required', workspaceRoute: '/content/review-render' }
|
|
303
371
|
```
|
|
304
372
|
|
|
305
373
|
Resolution is override-then-fallback — the step's route when it declares one, the pipeline's
|
|
306
374
|
otherwise. Use `resolveContentWorkspaceRoute` rather than reading either field directly.
|
|
307
375
|
|
|
376
|
+
**`reviewMode` says whether, not where.** It has two values, `'required'` and `'none'`. Where a
|
|
377
|
+
required review happens is derived from the route above: a step whose route resolves is reviewed on
|
|
378
|
+
your screen, and one whose route does not is reviewed in the shared queue. The resolved answer is
|
|
379
|
+
`step.reviewVenue` (`'none' | 'queue' | 'workspace'`) — read that rather than recombining
|
|
380
|
+
`reviewMode` and `workspaceRoute` yourself.
|
|
381
|
+
|
|
382
|
+
The field used to take `'live' | 'queued' | 'none'`, where `'live'` and `'queued'` differed only in
|
|
383
|
+
location. They are **not** accepted as aliases: a step still declaring one fails validation and is
|
|
384
|
+
dropped from the pipeline. If you are upgrading, `'live'` and `'queued'` both become `'required'` —
|
|
385
|
+
declare a `workspaceRoute` wherever you previously meant `'live'`.
|
|
386
|
+
|
|
308
387
|
**Declaring it is expected, and omitting it is supported.** A pipeline with no `workspaceRoute`
|
|
309
388
|
keeps the shared review page's action bar, so you can clear gates before you have built anything.
|
|
310
389
|
Once you declare a route, that page defers to it and links out instead. The route is an
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: CLI Management Commands
|
|
3
|
-
description: elevasis-sdk management commands -- project, note, acquisition, client, agent, session, queue, schedule, om, ui, skill, and
|
|
3
|
+
description: elevasis-sdk management commands -- project, note, acquisition, client, agent, session, queue, schedule, om, ui, skill, content, and grant subcommand families
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
This page covers the domain management commands for `elevasis-sdk`. For core SDK commands (check, deploy, exec, resources, executions, describe, creds, rename), see [CLI Reference](cli.mdx).
|
|
7
7
|
|
|
8
|
-
Every command family on this page -- `project`, `note`, `acquisition`, `client`, `agent`, `session`, `queue`, `schedule`, `om:doctor`, `request`, and `
|
|
8
|
+
Every command family on this page -- `project`, `note`, `error`, `acquisition`, `client`, `agent`, `session`, `queue`, `schedule`, `om:doctor`, `request`, `content`, and `grant` -- also accepts `--prod` to target production, overriding `NODE_ENV=development` (live as of `@elevasis/sdk` 1.45.0). See [CLI Reference's Global Flags](cli.mdx#global-flags) for the full description; per-command flag tables below list `--api-url` and other command-specific flags only, not `--prod` or `--json`.
|
|
9
9
|
|
|
10
10
|
---
|
|
11
11
|
|
|
@@ -61,6 +61,8 @@ This CLI family is SDK-first, but it is not semantically standalone. It operates
|
|
|
61
61
|
|
|
62
62
|
```bash
|
|
63
63
|
elevasis-sdk project:list
|
|
64
|
+
elevasis-sdk project:resolve "Website Refresh"
|
|
65
|
+
elevasis-sdk project:work "Website Refresh"
|
|
64
66
|
elevasis-sdk project:get <id>
|
|
65
67
|
elevasis-sdk project:create --name "Website Refresh" --kind client_engagement
|
|
66
68
|
elevasis-sdk project:update <id> --status completed
|
|
@@ -69,7 +71,9 @@ elevasis-sdk project:delete <id>
|
|
|
69
71
|
|
|
70
72
|
**Behavior:**
|
|
71
73
|
|
|
72
|
-
- `project:list` filters by `--kind
|
|
74
|
+
- `project:list` filters by `--kind`, `--status`, `--search`, and `--client` (a UUID or fuzzy client name, resolved through the same client-lookup helper `client:resolve` exposes)
|
|
75
|
+
- `project:resolve <query>` resolves a project ID from a UUID, exact name, or search query and prints the ID (or the full record with `--pretty`) -- the same resolution logic used internally wherever a project command accepts a fuzzy identifier
|
|
76
|
+
- `project:work <query>` (alias `project:open`) resolves a project and prints a lifecycle-aware work brief combining the project record and its notes; `--json` renders the structured brief instead of the formatted one
|
|
73
77
|
- `project:get` returns a single project
|
|
74
78
|
- `project:create` and `project:update` operate on `/api/external/projects`
|
|
75
79
|
|
|
@@ -188,6 +192,22 @@ elevasis-sdk request:get <id>
|
|
|
188
192
|
| `--pretty` | Human-readable output instead of raw JSON |
|
|
189
193
|
| `--api-url <url>` | Override the API base URL |
|
|
190
194
|
|
|
195
|
+
**Write-back commands** (amend or withdraw a request you filed):
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
elevasis-sdk request:update <id> --input '{"project_id":"<uuid>"}'
|
|
199
|
+
elevasis-sdk request:delete <id>
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
`request:update` calls `PATCH /api/external/requests/:id` to backfill fields (for example `project_id` / `task_id` on rows filed before those were populated) -- the payload is validated against `UpdateRequestInputSchema`. `status` is not writable through this command; it is the platform's answer to the request, so poll `request:get` to read it instead. `request:delete` calls `DELETE /api/external/requests/:id` and is permanent -- the row is removed, not archived. Use `request:update` to amend a request instead of deleting and resubmitting.
|
|
203
|
+
|
|
204
|
+
| Flag | Description |
|
|
205
|
+
| --------------------------- | --------------------------------------------------------------------------- |
|
|
206
|
+
| `-i, --input <json>` | Fields to change, as a JSON object (update: required unless `--input-file`) |
|
|
207
|
+
| `-f, --input-file <path>` | Read the changed fields from a JSON file instead of `--input` |
|
|
208
|
+
| `--pretty` | Human-readable output instead of raw JSON |
|
|
209
|
+
| `--api-url <url>` | Override the API base URL |
|
|
210
|
+
|
|
191
211
|
---
|
|
192
212
|
|
|
193
213
|
### Shared Flags
|
|
@@ -363,6 +383,31 @@ The following invariants govern the Notes feature and are relevant when building
|
|
|
363
383
|
|
|
364
384
|
---
|
|
365
385
|
|
|
386
|
+
## elevasis-sdk error:\*
|
|
387
|
+
|
|
388
|
+
Resolve execution errors surfaced by the observability layer -- mark one error, or every error tied to a single execution, as resolved.
|
|
389
|
+
|
|
390
|
+
```bash
|
|
391
|
+
elevasis-sdk error resolve <errorId>
|
|
392
|
+
elevasis-sdk error resolve-execution <executionId>
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
- `error resolve <errorId>` -- calls `PATCH /api/external/observability/errors/:errorId/resolve` and marks that one error resolved
|
|
396
|
+
- `error resolve-execution <executionId>` -- calls `PATCH /api/external/observability/errors/execution/:executionId/resolve` and marks every error tied to that execution resolved in one call
|
|
397
|
+
|
|
398
|
+
These are space-separated subcommands under the `error` group (`error resolve`, not `error:resolve`), unlike every other domain on this page.
|
|
399
|
+
|
|
400
|
+
**Flags:**
|
|
401
|
+
|
|
402
|
+
| Flag | Description |
|
|
403
|
+
| ------------------- | ---------------------------------------------------- |
|
|
404
|
+
| `--prod` | Target production (overrides `NODE_ENV=development`) |
|
|
405
|
+
| `--api-url <url>` | Override the API base URL |
|
|
406
|
+
|
|
407
|
+
**Implementation:** `packages/sdk/src/cli/commands/error/`
|
|
408
|
+
|
|
409
|
+
---
|
|
410
|
+
|
|
366
411
|
## elevasis-sdk acquisition:\*
|
|
367
412
|
|
|
368
413
|
Read-only access to acquisition lists and CRM deals. The acquisition CLI scope is intentionally read-only; mutating commands are deferred.
|
|
@@ -375,7 +420,7 @@ elevasis-sdk acquisition:list:get <id>
|
|
|
375
420
|
elevasis-sdk acquisition:list:status
|
|
376
421
|
```
|
|
377
422
|
|
|
378
|
-
- `acquisition:list:list` -- list
|
|
423
|
+
- `acquisition:list:list` -- list acquisition lists for the organization; filters: `--status` (`draft | enriching | launched | closing | archived`), `--batch`, `--vertical`, `--limit`, `--offset`
|
|
379
424
|
- `acquisition:list:get <id>` -- get full detail for a single acquisition list by UUID
|
|
380
425
|
- `acquisition:list:status` -- summarize counts and progress across all lists
|
|
381
426
|
|
|
@@ -387,7 +432,7 @@ elevasis-sdk acquisition:deal:get <id>
|
|
|
387
432
|
elevasis-sdk acquisition:deal:status
|
|
388
433
|
```
|
|
389
434
|
|
|
390
|
-
- `acquisition:deal:list` -- list
|
|
435
|
+
- `acquisition:deal:list` -- list CRM deals visible to the organization; filters: `--stage`, `--list <id>`, `--batch`, `--stale-since <iso>`, `--search`, `--limit`, `--offset`
|
|
391
436
|
- `acquisition:deal:get <id>` -- get a single deal record
|
|
392
437
|
- `acquisition:deal:status` -- summarize deal pipeline counts
|
|
393
438
|
|
|
@@ -446,12 +491,18 @@ Full CRUD management for client records. The `client:*` family covers create, re
|
|
|
446
491
|
|
|
447
492
|
```bash
|
|
448
493
|
elevasis-sdk client:list
|
|
494
|
+
elevasis-sdk client:resolve "Acme"
|
|
449
495
|
elevasis-sdk client:get <id>
|
|
496
|
+
elevasis-sdk client:status
|
|
450
497
|
elevasis-sdk client:create --name "Acme Corp"
|
|
451
498
|
elevasis-sdk client:update <id> --name "Acme Corp Updated"
|
|
452
499
|
elevasis-sdk client:delete <id>
|
|
453
500
|
```
|
|
454
501
|
|
|
502
|
+
- `client:resolve <query>` resolves a client ID from a UUID, exact name, or search query and prints the ID (or the full record with `--pretty`) -- the same resolution `client:update`, `client:delete`, and `project:create --client` use internally
|
|
503
|
+
- `client:status` summarizes the client portfolio: totals by status and linked-record counts (deals, projects, companies, contacts)
|
|
504
|
+
- `client:update` supports `--clear-source-deal`, `--clear-primary-company`, and `--clear-primary-contact` to null out those links; each is mutually exclusive with its corresponding set flag
|
|
505
|
+
|
|
455
506
|
**Flags:**
|
|
456
507
|
|
|
457
508
|
| Flag | Description |
|
|
@@ -459,7 +510,7 @@ elevasis-sdk client:delete <id>
|
|
|
459
510
|
| `--pretty` | Human-readable terminal output instead of raw JSON |
|
|
460
511
|
| `--api-url <url>` | Override the API base URL |
|
|
461
512
|
|
|
462
|
-
**Implementation:** `packages/sdk/src/cli/commands/` (client family)
|
|
513
|
+
**Implementation:** `packages/sdk/src/cli/commands/client/` (client family)
|
|
463
514
|
|
|
464
515
|
---
|
|
465
516
|
|
|
@@ -472,19 +523,22 @@ elevasis-sdk agent:list
|
|
|
472
523
|
elevasis-sdk agent:get <id>
|
|
473
524
|
```
|
|
474
525
|
|
|
475
|
-
- `agent:list` -- list
|
|
476
|
-
- `agent:get <id>` -- get metadata and
|
|
526
|
+
- `agent:list` -- list resources for the organization, filtered client-side to `resourceType: 'agent'`
|
|
527
|
+
- `agent:get <id>` -- get metadata and organization-model linkage for a specific agent
|
|
477
528
|
|
|
478
|
-
**API routes:** `GET /api/external/agents
|
|
529
|
+
**API routes:** `GET /api/external/resources` (filtered to agents), `GET /api/external/resources/:id/definition`
|
|
479
530
|
|
|
480
531
|
**Flags:**
|
|
481
532
|
|
|
482
|
-
| Flag | Description
|
|
483
|
-
| ------------------- |
|
|
484
|
-
| `--
|
|
485
|
-
| `--
|
|
533
|
+
| Flag | Description |
|
|
534
|
+
| ------------------- | -------------------------------------------------------- |
|
|
535
|
+
| `--json` | Output raw JSON instead of the default formatted display |
|
|
536
|
+
| `--prod` | Target production (overrides `NODE_ENV=development`) |
|
|
537
|
+
| `--api-url <url>` | Override the API base URL |
|
|
538
|
+
|
|
539
|
+
Note the direction: `agent:*` defaults to a formatted display and opts into JSON with `--json`, the opposite convention from the `--pretty`-to-opt-into-formatted commands elsewhere on this page.
|
|
486
540
|
|
|
487
|
-
**Implementation:** `packages/sdk/src/cli/commands/`
|
|
541
|
+
**Implementation:** `packages/sdk/src/cli/commands/agent/`
|
|
488
542
|
|
|
489
543
|
---
|
|
490
544
|
|
|
@@ -607,13 +661,26 @@ elevasis-sdk queue:status --pretty
|
|
|
607
661
|
| `--pretty` | Human-readable output instead of raw JSON |
|
|
608
662
|
| `--api-url <url>` | Override the API base URL |
|
|
609
663
|
|
|
610
|
-
**Shared flags (`queue:get`, `queue:expire
|
|
664
|
+
**Shared flags (`queue:get`, `queue:expire`):**
|
|
611
665
|
|
|
612
666
|
| Flag | Description |
|
|
613
667
|
| ------------------- | ----------------------------------------- |
|
|
614
668
|
| `--pretty` | Human-readable output instead of raw JSON |
|
|
615
669
|
| `--api-url <url>` | Override the API base URL |
|
|
616
670
|
|
|
671
|
+
**`queue:status` filter flags:**
|
|
672
|
+
|
|
673
|
+
`queue:status` shares the checkpoint/status view rather than the task list, so it takes its own subset of filters, not the shared flags above:
|
|
674
|
+
|
|
675
|
+
| Flag | Description |
|
|
676
|
+
| --------------------------- | --------------------------------------------------------------------- |
|
|
677
|
+
| `--time-range <range>` | Filter by created time range: `1h`, `24h`, `7d`, `30d` |
|
|
678
|
+
| `--priority-min <number>` | Minimum priority, 1-10 |
|
|
679
|
+
| `--priority-max <number>` | Maximum priority, 1-10 |
|
|
680
|
+
| `--status <status>` | Filter checkpoint totals by status: `pending`, `completed`, `expired` |
|
|
681
|
+
| `--pretty` | Human-readable output instead of raw JSON |
|
|
682
|
+
| `--api-url <url>` | Override the API base URL |
|
|
683
|
+
|
|
617
684
|
**Auth:** Calls `/api/external/command-queue/*` with API-key auth.
|
|
618
685
|
|
|
619
686
|
---
|
|
@@ -683,7 +750,17 @@ Knowledge graph inspection, plus an Organization Model write surface (`om:scaffo
|
|
|
683
750
|
- `knowledge:ls <path>` -- list nodes/edges for the mount; default output is an id + summary table, `--json` returns `{ path, mount, args, results }`.
|
|
684
751
|
- `knowledge:cat <id>` -- render a node's `body` MDX to stdout; `--json` returns the full node object (body, links, owners, timestamps).
|
|
685
752
|
- `knowledge:graph <id>` -- show outgoing + incoming edges grouped by edge kind.
|
|
686
|
-
- `om:doctor` -- validate Organization Model integrity against published `@elevasis/core/organization-model` primitives. This is a deliberately reduced 3-check command: two of the monorepo platform CLI's five checks assert monorepo-only paths that do not exist in a tenant project, so they are not ported. `--json` output includes `checksRun: 3` so a caller can tell it apart from the platform CLI's 5-check version.
|
|
753
|
+
- `om:doctor` -- validate Organization Model integrity against published `@elevasis/core/organization-model` primitives. This is a deliberately reduced 3-check command: two of the monorepo platform CLI's five checks assert monorepo-only paths that do not exist in a tenant project, so they are not ported. `--json` output includes `checksRun: 3` so a caller can tell it apart from the platform CLI's 5-check version. `om:doctor` also asks the API about the deployed readiness snapshot and merges those diagnostics in, unless `--skip-deployed` is passed; it degrades to `NOT RUN` rather than failing when there is no key or no server reachable.
|
|
754
|
+
|
|
755
|
+
**`om:doctor` flags:**
|
|
756
|
+
|
|
757
|
+
| Flag | Description |
|
|
758
|
+
| ------------------------ | ------------------------------------------------------------ |
|
|
759
|
+
| `--scope <systemPath>` | Limit diagnostics to a system path and its descendants |
|
|
760
|
+
| `--skip-deployed` | Structural checks only -- do not ask the API about readiness |
|
|
761
|
+
| `--json` | Output as a grouped JSON envelope |
|
|
762
|
+
| `--prod` | Target production (overrides `NODE_ENV=development`) |
|
|
763
|
+
| `--api-url <url>` | Override the API base URL |
|
|
687
764
|
|
|
688
765
|
In tenant projects, SDK read commands load `core/config/organization-model.ts` through the SDK's layout-aware TypeScript loader. The temporary bundle and dependency resolution are anchored at the package root that owns SDK dependencies, so hoisted pnpm workspaces resolve `esbuild` and `@elevasis/core` correctly. Missing org-model files still return the default model; malformed files or files with no usable export emit diagnostics. `knowledge:generate` / `om:generate` is the exception because it reads MDX and codegen inputs directly.
|
|
689
766
|
|
|
@@ -697,7 +774,7 @@ elevasis-sdk knowledge:search <query>
|
|
|
697
774
|
elevasis-sdk knowledge:describe <nodeId>
|
|
698
775
|
elevasis-sdk knowledge:skills <nodeId>
|
|
699
776
|
elevasis-sdk knowledge:generate
|
|
700
|
-
elevasis-sdk om:doctor --
|
|
777
|
+
elevasis-sdk om:doctor --scope sales.crm
|
|
701
778
|
```
|
|
702
779
|
|
|
703
780
|
These are registered as `knowledge:*` subcommands on `elevasis-sdk`. Both the SDK CLI (`elevasis-sdk knowledge:*`) and the platform CLI (`elevasis knowledge:*`) call the same query functions in `@repo/core/knowledge/queries`.
|
|
@@ -986,16 +1063,37 @@ no workaround.
|
|
|
986
1063
|
|
|
987
1064
|
```
|
|
988
1065
|
elevasis-sdk content:source-asset:create --kind <kind> --title <title> (--text <value> | --url <url>)
|
|
989
|
-
[--field <key>] [--duration <seconds>] [--
|
|
1066
|
+
[--field <key>] [--duration <seconds>] [--storage-path <path>]
|
|
1067
|
+
[--metadata <json> | --metadata-file <path>] [--item <itemId>]
|
|
990
1068
|
```
|
|
991
1069
|
|
|
992
1070
|
A source asset holds its content in one of two places, and the flags mirror that exactly: `--text` is
|
|
993
1071
|
inline content and lands in `payload`, `--url` is a reference and lands in `externalUrl`. They are
|
|
994
1072
|
mutually exclusive because an asset is one shape or the other.
|
|
995
1073
|
|
|
996
|
-
**There is no file upload
|
|
997
|
-
|
|
998
|
-
it
|
|
1074
|
+
**There is still no file upload.** `--storage-path` records a path a caller already knows about (for
|
|
1075
|
+
example one written by a Dropbox intake flow elsewhere) -- it writes the `storage_path` column, the
|
|
1076
|
+
same column the worker adapter's `content.createSourceAsset` already sets freely, but it does not write
|
|
1077
|
+
bytes to storage itself. `/api/storage` has no external mirror. A file lives wherever it already lives;
|
|
1078
|
+
this flag just lets the CLI-created asset point at it, alongside or instead of `--url`.
|
|
1079
|
+
|
|
1080
|
+
**Flags:**
|
|
1081
|
+
|
|
1082
|
+
| Flag | Description |
|
|
1083
|
+
| -------------------------- | ------------------------------------------------------------------------------------- |
|
|
1084
|
+
| `--kind <kind>` | Required. Source asset kind, validated against the org model catalog |
|
|
1085
|
+
| `--title <title>` | Required. Human-readable title (1-500 chars) |
|
|
1086
|
+
| `--text <value>` | Inline text, or `@path` to read a local file. Mutually exclusive with `--url` |
|
|
1087
|
+
| `--field <key>` | Payload field the `--text` content is written to (default: the `--kind` value) |
|
|
1088
|
+
| `--url <url>` | External URL the asset references. Mutually exclusive with `--text` |
|
|
1089
|
+
| `--duration <seconds>` | Duration in seconds, for time-based referenced media |
|
|
1090
|
+
| `--storage-path <path>` | Storage path the asset references (1-2000 chars) |
|
|
1091
|
+
| `--metadata <json>` | Arbitrary metadata as a JSON object string. Mutually exclusive with `--metadata-file` |
|
|
1092
|
+
| `--metadata-file <path>` | Path to a JSON file containing metadata. Mutually exclusive with `--metadata` |
|
|
1093
|
+
| `--item <itemId>` | Link the new asset to this content item after creating it |
|
|
1094
|
+
| `--prod` | Target production (overrides `NODE_ENV=development`) |
|
|
1095
|
+
| `--api-url <url>` | Override the API base URL |
|
|
1096
|
+
| `--pretty` | Human-readable output instead of raw JSON |
|
|
999
1097
|
|
|
1000
1098
|
**`--text` accepts `@path` to read a local file**, the same convention as `exec --input`. Anything not
|
|
1001
1099
|
starting with `@` is the literal value. The CLI refuses content over 500KB locally rather than sending
|
|
@@ -1036,29 +1134,74 @@ delete for a source asset: correct a bad one by creating a replacement and re-li
|
|
|
1036
1134
|
|
|
1037
1135
|
---
|
|
1038
1136
|
|
|
1137
|
+
## elevasis-sdk grant:\*
|
|
1138
|
+
|
|
1139
|
+
Manage public and code-gated agent access grants -- the surface that exposes a deployed agent at a shareable public URL (`/public/agents/<slug>`) without requiring a signed-in Command Center user.
|
|
1140
|
+
|
|
1141
|
+
```bash
|
|
1142
|
+
elevasis-sdk grant:list
|
|
1143
|
+
elevasis-sdk grant:create --resource <resourceId> [--slug <slug>] [--mode public|code] [--code <code>]
|
|
1144
|
+
elevasis-sdk grant:update <slug> [--mode public|code] [--max-turns <n>] [--branding <json>]
|
|
1145
|
+
elevasis-sdk grant:disable <slug>
|
|
1146
|
+
```
|
|
1147
|
+
|
|
1148
|
+
- `grant:list` -- list grants; `--resource-id` filters to one agent, `--include-disabled` includes disabled grants
|
|
1149
|
+
- `grant:create` -- create a grant for `--resource`; `--slug` defaults to a normalized form of the resource ID; `--mode code` requires `--code`
|
|
1150
|
+
- `grant:update <slug>` -- update mutable fields (mode, code, origins, expiry, limits, branding, capture fields, tool policy); at least one field is required
|
|
1151
|
+
- `grant:disable <slug>` -- disable a grant without deleting it (there is no `grant:delete` or `grant:enable`)
|
|
1152
|
+
|
|
1153
|
+
**Flags:**
|
|
1154
|
+
|
|
1155
|
+
| Flag | Description |
|
|
1156
|
+
| --------------------------- | -------------------------------------------------------------- |
|
|
1157
|
+
| `--resource <id>` | Agent resource ID to expose (create: required) |
|
|
1158
|
+
| `--slug <slug>` | Public slug; defaults to a normalized `--resource` |
|
|
1159
|
+
| `--mode <mode>` | Access mode: `public` (default) or `code` |
|
|
1160
|
+
| `--code <code>` | Access code, required when `--mode code` |
|
|
1161
|
+
| `--origins <origins>` | Comma-separated allowed origins; omit for any origin |
|
|
1162
|
+
| `--expires-at <iso>` | ISO timestamp when the grant expires |
|
|
1163
|
+
| `--max-turns <number>` | Maximum turns per public session |
|
|
1164
|
+
| `--max-sessions <number>` | Maximum sessions per visitor |
|
|
1165
|
+
| `--branding <json>` | Branding metadata JSON object |
|
|
1166
|
+
| `--capture-fields <json>` | Capture fields JSON array |
|
|
1167
|
+
| `--tool-policy <json>` | Tool policy JSON object |
|
|
1168
|
+
| `--public-base-url <url>` | Base URL used to print the full public URL alongside the grant |
|
|
1169
|
+
| `--resource-id <id>` | Filter by agent resource ID (list only) |
|
|
1170
|
+
| `--include-disabled` | Include disabled grants (list only) |
|
|
1171
|
+
| `--prod` | Target production (overrides `NODE_ENV=development`) |
|
|
1172
|
+
| `--api-url <url>` | Override the API base URL |
|
|
1173
|
+
| `--json` | Output as JSON |
|
|
1174
|
+
|
|
1175
|
+
**API routes:** `GET /api/external/agent-access-grants`, `POST /api/external/agent-access-grants`, `PATCH /api/external/agent-access-grants/:slug`, `POST /api/external/agent-access-grants/:slug/disable`.
|
|
1176
|
+
|
|
1177
|
+
**Implementation:** `packages/sdk/src/cli/commands/grant/`
|
|
1178
|
+
|
|
1179
|
+
---
|
|
1180
|
+
|
|
1039
1181
|
## Appendix: Domain Status
|
|
1040
1182
|
|
|
1041
1183
|
Current status of all SDK CLI domains. Domains marked `deferred` have no CLI commands yet.
|
|
1042
1184
|
|
|
1043
|
-
| Domain | CLI surface | API surface
|
|
1044
|
-
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1045
|
-
| platform | top-level SDK commands | mixed platform APIs
|
|
1046
|
-
| project | `project:*` | `apps/api/src/projects/`
|
|
1047
|
-
| knowledge | `knowledge:*` | file/generated knowledge data
|
|
1048
|
-
| creds | `creds *` nested Commander group | credentials API
|
|
1049
|
-
| ui | `ui:*` | local project file edits
|
|
1050
|
-
| request | `request:submit`, `request:list`, `request:get`, `request:update`, `request:delete` | requests API
|
|
1051
|
-
| error | `error resolve`, `error resolve-execution` | execution error APIs
|
|
1052
|
-
| acquisition | `acquisition:list:*`, `acquisition:deal:*` | `/api/external/acquisition/lists*`, `/api/external/deals*`
|
|
1053
|
-
| client | `client:*` | `/api/external/clients`
|
|
1054
|
-
| agent | `agent:list`, `agent:get` | `/api/external/
|
|
1055
|
-
| session | `session:create`, `session:turn`, `session:messages`, `session:list`, `session:get`, `session:end` | `/api/external/sessions*`
|
|
1056
|
-
| queue | `queue:list`, `queue:get`, `queue:select`, `queue:expire`, `queue:status` | `/api/external/command-queue*`
|
|
1057
|
-
| schedule | `schedule:list`, `schedule:get`, `schedule:create`, `schedule:update`
|
|
1058
|
-
| skill | `skill:scaffold`, `skill:check-coverage` | local CLI catalog and `.claude/registries/skill-coverage.json`
|
|
1059
|
-
| content | `content:list`, `content:get`, `content:board`, `content:queue`, `content:pipeline`, `content:distributions`, `content:review`, `content:source-assets`, `content:source-asset`, `content:source-asset:create` | `/api/external/content*`
|
|
1060
|
-
|
|
|
1061
|
-
|
|
|
1185
|
+
| Domain | CLI surface | API surface | Status |
|
|
1186
|
+
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------- |
|
|
1187
|
+
| platform | top-level SDK commands | mixed platform APIs | implemented |
|
|
1188
|
+
| project | `project:*` | `apps/api/src/projects/` | implemented |
|
|
1189
|
+
| knowledge | `knowledge:*` | file/generated knowledge data | implemented |
|
|
1190
|
+
| creds | `creds *` nested Commander group | credentials API | implemented |
|
|
1191
|
+
| ui | `ui:*` | local project file edits | implemented |
|
|
1192
|
+
| request | `request:submit`, `request:list`, `request:get`, `request:update`, `request:delete` | requests API | implemented read/write scope |
|
|
1193
|
+
| error | `error resolve`, `error resolve-execution` | execution error APIs | partial |
|
|
1194
|
+
| acquisition | `acquisition:list:*`, `acquisition:deal:*` | `/api/external/acquisition/lists*`, `/api/external/deals*` | implemented read-only scope |
|
|
1195
|
+
| client | `client:*` | `/api/external/clients` | implemented read/write scope |
|
|
1196
|
+
| agent | `agent:list`, `agent:get` | `/api/external/resources` (filtered), `/api/external/resources/:id/definition` | implemented read-only scope |
|
|
1197
|
+
| session | `session:create`, `session:turn`, `session:messages`, `session:list`, `session:get`, `session:end` | `/api/external/sessions*` | implemented multi-turn scope |
|
|
1198
|
+
| queue | `queue:list`, `queue:get`, `queue:select`, `queue:expire`, `queue:status` | `/api/external/command-queue*` | implemented |
|
|
1199
|
+
| schedule | `schedule:list`, `schedule:get`, `schedule:create`, `schedule:update`, `schedule:pause`, `schedule:resume`, `schedule:cancel` | `/api/external/task-scheduler/schedules*` | implemented |
|
|
1200
|
+
| skill | `skill:scaffold`, `skill:check-coverage` | local CLI catalog and `.claude/registries/skill-coverage.json` | implemented developer tooling |
|
|
1201
|
+
| content | `content:list`, `content:get`, `content:board`, `content:queue`, `content:pipeline`, `content:distributions`, `content:review`, `content:source-assets`, `content:source-asset`, `content:source-asset:create` | `/api/external/content*` | implemented read + review-write + source-asset-create scope |
|
|
1202
|
+
| grant | `grant:list`, `grant:create`, `grant:update`, `grant:disable` | `/api/external/agent-access-grants*` | implemented read/write scope |
|
|
1203
|
+
| seo | none | not scoped here | deferred |
|
|
1204
|
+
| monitoring | none | not scoped here | deferred |
|
|
1062
1205
|
|
|
1063
1206
|
### Promotion Criteria
|
|
1064
1207
|
|
|
@@ -1071,4 +1214,4 @@ A domain should meet all four criteria before gaining a `*:list` / `*:get` surfa
|
|
|
1071
1214
|
|
|
1072
1215
|
---
|
|
1073
1216
|
|
|
1074
|
-
**Last Updated:** 2026-08-
|
|
1217
|
+
**Last Updated:** 2026-08-17
|