@elevasis/sdk 1.25.0 → 1.26.1

package/reference/cli-management.mdx

@@ -0,0 +1,541 @@
+---
+title: CLI Management Commands
+description: elevasis-sdk management commands -- project, note, acquisition, client, agent, session, queue, schedule, om, and ui subcommand families
+---
+
+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).
+
+---
+
+## elevasis-sdk project:\*
+
+`elevasis-sdk project:*` is the canonical project-management surface. Use it for project, milestone, task, and note operations whether the caller is a human, a scripted workflow, or a slash-command router like `/project`.
+
+This CLI family is SDK-first, but it is not semantically standalone. It operates on the same Organization OS contract that the shared delivery UI uses:
+
+- UI manifest key: `delivery`
+- Organization model feature ID: `projects`
+- Default surface: `projects.index`
+- Semantic domain fields: `organizationModel.delivery`
+- Core entity/capability IDs: `delivery.project`, `delivery.milestone`, `delivery.task`, `delivery.projects.view`
+
+### Projects
+
+```bash
+elevasis-sdk project:list
+elevasis-sdk project:get <id>
+elevasis-sdk project:create --name "Website Refresh" --kind client_engagement
+elevasis-sdk project:update <id> --status completed
+elevasis-sdk project:delete <id>
+```
+
+**Behavior:**
+
+- `project:list` filters by `--kind` and `--status`
+- `project:get` returns a single project
+- `project:create` and `project:update` operate on `/api/external/projects`
+
+### Milestones
+
+```bash
+elevasis-sdk project:milestone:list --project <id>
+elevasis-sdk project:milestone:create --project <id> --name "Phase 1"
+elevasis-sdk project:milestone:update <id> --status completed
+elevasis-sdk project:milestone:update <id> --description "Updated scope description"
+elevasis-sdk project:milestone:delete <id>
+```
+
+`project:milestone:update` accepts `--description` to set or clear the milestone description. Passing an empty string clears the field, matching `project:task:update --description` semantics.
+
+### Tasks
+
+```bash
+elevasis-sdk project:task:list --project <id>
+elevasis-sdk project:task:get <id>
+elevasis-sdk project:task:create --project <id> --title "Implement API"
+elevasis-sdk project:task:update <id> --status in_progress
+elevasis-sdk project:task:delete <id>
+```
+
+Task commands also expose agent-oriented resume state:
+
+```bash
+elevasis-sdk project:task:resume <id> --pretty
+elevasis-sdk project:task:save <id> --current-state "Implemented the route layer"
+```
+
+- `project:task:resume` reads the task's `resume_context`
+- `project:task:save` merges fields into `resume_context`
+- these commands are the CLI counterpart to `/work resume` and `/work save` style flows
+
+### Notes
+
+```bash
+elevasis-sdk project:note:list --project <id>
+elevasis-sdk project:note:create --project <id> --content "Client approved scope"
+elevasis-sdk project:note:create --project <id> --type agent_learning --content "Learned X"
+elevasis-sdk project:note:update <id> --content "Updated status"
+elevasis-sdk project:note:delete <id>
+```
+
+The `--type` flag accepts: `call_note`, `status_update`, `issue`, `blocker`, `agent_learning`. The `agent_learning` type is the canonical way for agents to record durable skill observations. Accepted values are derived from `NoteTypeSchema` in `packages/core/src/projects/api-schemas.ts` -- that schema is the source of truth; the CLI help text is generated from it to prevent drift.
+
+### Requests
+
+```bash
+elevasis-sdk request:submit --input-file ./tmp/request-report.json
+elevasis-sdk request:submit --input '{"type":"bug","category":"sdk","severity":"high","title":"..."}'
+```
+
+Submits a structured request report to `POST /api/external/requests`. The payload is validated against `CreateRequestInputSchema` before the network call.
+
+**Payload enum values** (inline in `--help` output; sourced from `packages/core/src/requests/api-schemas.ts`):
+
+| Field      | Accepted values                                                                       |
+| ---------- | ------------------------------------------------------------------------------------- |
+| `type`     | Values from `RequestTypeEnum` -- see `request:submit --help` for the current list     |
+| `category` | Values from `RequestCategoryEnum` -- see `request:submit --help` for the current list |
+| `severity` | Values from `RequestSeverityEnum` -- see `request:submit --help` for the current list |
+
+**Flags:**
+
+| Flag                        | Description                                                                   |
+| --------------------------- | ----------------------------------------------------------------------------- |
+| `-i, --input <json>`      | Request body as JSON string                                                   |
+| `-f, --input-file <path>` | Read body from a JSON file; relative paths resolve against the project root   |
+| `--pretty`                  | Human-readable output instead of raw JSON                                     |
+| `--cleanup-input`           | Delete the input file after success (only files under `<projectRoot>/tmp/`) |
+| `--api-url <url>`         | Override the API base URL                                                     |
+
+**Read commands** (added once `request` cleared the 4-point promotion bar):
+
+```bash
+elevasis-sdk request:list --status open --severity critical
+elevasis-sdk request:get <id>
+```
+
+`request:list` calls `GET /api/external/requests` and `request:get` calls `GET /api/external/requests/:id`. Both default to raw JSON; pass `--pretty` for human-readable output (mirrors `request:submit`). Organization scope is derived from the API key, so `request:get` returns 404 for an id belonging to another tenant -- a cross-tenant id is indistinguishable from a missing one (no existence oracle).
+
+| Flag                  | Description                                     |
+| --------------------- | ----------------------------------------------- |
+| `--status <status>` | Filter list by status (`RequestStatusEnum`)     |
+| `--severity <sev>`  | Filter list by severity (`RequestSeverityEnum`) |
+| `--project-id <id>` | Filter list by project id                       |
+| `--limit <n>`       | Max rows (1-200, default 50)                    |
+| `--pretty`            | Human-readable output instead of raw JSON       |
+| `--api-url <url>`   | Override the API base URL                       |
+
+---
+
+### Shared Flags
+
+Most `project:*` commands support:
+
+| Flag              | Description                                        |
+| ----------------- | -------------------------------------------------- |
+| `--pretty`        | Human-readable terminal output instead of raw JSON |
+| `--api-url <url>` | Override the API base URL                          |
+
+For exact required flags and accepted enum values, see the command source under `packages/sdk/src/cli/commands/project/`.
+
+### Command Boundary
+
+- `/project` is a convenience router to these `elevasis-sdk project:*` commands. It is not a separate project system.
+- `/work` is for docs-backed in-progress task tracking and session resume, not project CRUD.
+- `/external` is for managing standalone apps in `external/`, not project records inside a deployed system.
+- `/adev` is for implementation, debugging, testing, and platform execution flows. Use it when you need to build or run agent/workflow code rather than update project data.
+
+---
+
+## elevasis-sdk note:\*
+
+`elevasis-sdk note:*` is the agent-facing surface for pushing and reading user notes. Workflows and agents use it to surface information -- such as "deal X stalled" or "review run completed" -- directly into a user's Notes panel in the Command Center, without sending an email or notification.
+
+Agent-written notes are private to the target user and scoped to the calling organization. The authenticated Notes panel can also create and edit org-shared notes (`visibility: 'org'`), which are visible to active members of the same organization and show creator attribution. The external SDK CLI surface exposes `GET + POST` only; `note:update` and `note:delete` are not yet available via SDK CLI. Users edit, delete, and change visibility through the right-panel view.
+
+### note:create
+
+Create a personal note for a user.
+
+**Synopsis:**
+
+```
+elevasis-sdk note:create --content <text>
+                         [--user <email>]
+                         [--title <text>]
+                         [--priority low|normal|high|urgent]
+                         [--pinned]
+                         [--source <id>]
+                         [--api-url <url>] [--pretty]
+```
+
+**Flags:**
+
+| Flag                      | Description                                                                               |
+| ------------------------- | ----------------------------------------------------------------------------------------- |
+| `--content <text>`      | Required. The note body text                                                              |
+| `--user <email>`        | Target user email. Defaults to the API key owner when omitted                             |
+| `--title <text>`        | Optional note title                                                                       |
+| `--priority <priority>` | Priority level: `low`, `normal` (default), `high`, or `urgent`                            |
+| `--pinned`                | Pin the note to the top of the panel                                                      |
+| `--source <id>`         | Source identifier -- set this to the workflow or agent ID when calling from agent runtime |
+| `--api-url <url>`       | Override the API base URL                                                                 |
+| `--pretty`                | Human-readable terminal output instead of raw JSON                                        |
+
+**Behavior:**
+
+- Posts to `POST /api/external/user-notes`
+- When `--user` is omitted the note is created for the identity bound to the API key (the caller)
+- When `--user` is provided the platform resolves the email to a Supabase user UUID and verifies the resolved user is an active member of the calling organization before writing
+- External agent-created notes are always private; org-shared visibility is a signed-in UI capability, not a broadcast CLI mode
+- The `--source` flag is recorded as the `source` column in `user_notes`; agent runtimes should pass their resource ID here so users can see which workflow created the note
+- Priority `normal` produces no badge in the UI; `high` renders orange, `urgent` renders red, `low` renders dimmed gray
+
+**Examples:**
+
+```bash
+# Create a note for the API key owner
+elevasis-sdk note:create --content "Deal X has stalled -- follow up needed"
+
+# Create a high-priority pinned note for a specific user
+elevasis-sdk note:create \
+  --content "Review run completed for batch_abc123" \
+  --user ops@acme.com \
+  --priority high \
+  --pinned \
+  --source "report-review-workflow" \
+  --pretty
+```
+
+```
+  Note created
+    ID:       note_550e8400-...
+    Priority: high
+```
+
+---
+
+### note:list
+
+List notes for a user.
+
+**Synopsis:**
+
+```
+elevasis-sdk note:list --user <email>
+                       [--priority <p>] [--pinned]
+                       [--limit <n>] [--offset <n>]
+                       [--api-url <url>] [--pretty]
+```
+
+**Flags:**
+
+| Flag                      | Description                                              |
+| ------------------------- | -------------------------------------------------------- |
+| `--user <email>`        | Required. The user whose notes to retrieve               |
+| `--priority <priority>` | Filter by priority: `low`, `normal`, `high`, or `urgent` |
+| `--pinned`                | Return only pinned notes                                 |
+| `--limit <n>`           | Maximum number of results to return                      |
+| `--offset <n>`          | Pagination offset                                        |
+| `--api-url <url>`       | Override the API base URL                                |
+| `--pretty`                | Human-readable terminal output instead of raw JSON       |
+
+**Behavior:**
+
+- Queries `GET /api/external/user-notes?user_email=<email>`
+- `--user` is required -- the external GET endpoint requires an explicit user target
+- Results are sorted by the platform: pinned first, then by priority (`urgent` > `high` > `normal` > `low`), then by most recently updated
+- Organization scope is derived from the API key -- only notes belonging to users in the calling organization are returned
+
+**Examples:**
+
+```bash
+# List all notes for a user
+elevasis-sdk note:list --user ops@acme.com
+
+# List only high-priority pinned notes, human-readable
+elevasis-sdk note:list --user ops@acme.com --priority high --pinned --pretty
+```
+
+```
+  Notes (2):
+
+  (no title) [pinned] [high]
+    ID: note_abc001
+    Review run completed for batch_abc123
+
+  Deal X stalled [pinned] [high]
+    ID: note_abc002
+    Deal X has stalled -- follow up needed
+```
+
+---
+
+### Shared Flags
+
+| Flag                | Description                                        |
+| ------------------- | -------------------------------------------------- |
+| `--pretty`          | Human-readable terminal output instead of raw JSON |
+| `--api-url <url>` | Override the API base URL                          |
+
+### Command Boundary
+
+- `note:create` and `note:list` operate on the **user notes** surface -- not project notes. For project-scoped notes use `project:note:*`.
+- `note:update` and `note:delete` are not yet available via SDK CLI. Edit and delete notes using the Notes panel in the Command Center.
+- The shared Notes panel view (`NotesPanelView`) is exported from `@elevasis/ui/features/notes` and registered in the right-panel registry alongside Overview, Recent Executions, and Notifications.
+
+**Implementation:** `packages/sdk/src/cli/commands/notes.ts` -- delegates to `POST /api/external/user-notes` and `GET /api/external/user-notes`
+
+### Notes Design Contract
+
+The following invariants govern the Notes feature and are relevant when building agents or workflows that write notes:
+
+- **Scope:** Notes are user-scoped and organization-scoped by default. A signed-in user can mark a note as org-shared; agent-created notes stay private to the target user.
+- **Org-shared visibility:** `visibility: 'org'` lets active org members see and edit the note. Only the creator can change the visibility value.
+- **Sort order:** Pinned first, then by priority (`urgent` > `high` > `normal` > `low`), then by most recently updated.
+- **Broadcast:** Out of scope. Agents create notes for one resolved user at a time. Broadcast is a notifications concern, not a notes concern.
+- **Retention:** Notes persist until the user explicitly deletes them. There is no TTL and no dismissed state.
+- **Agent creation:** One-to-one only. Pass `--source` with the agent or workflow resource ID so users can trace which resource created the note.
+
+---
+
+## elevasis-sdk acquisition:\*
+
+Read-only access to acquisition lists and CRM deals. The acquisition CLI scope is intentionally read-only; mutating commands are deferred.
+
+### acquisition:list:\*
+
+```bash
+elevasis-sdk acquisition:list:list
+elevasis-sdk acquisition:list:get <id>
+elevasis-sdk acquisition:list:status
+```
+
+- `acquisition:list:list` -- list all acquisition lists for the organization
+- `acquisition:list:get <id>` -- get full detail for a single acquisition list by UUID
+- `acquisition:list:status` -- summarize counts and progress across all lists
+
+### acquisition:deal:\*
+
+```bash
+elevasis-sdk acquisition:deal:list
+elevasis-sdk acquisition:deal:get <id>
+elevasis-sdk acquisition:deal:status
+```
+
+- `acquisition:deal:list` -- list all CRM deals visible to the organization
+- `acquisition:deal:get <id>` -- get a single deal record
+- `acquisition:deal:status` -- summarize deal pipeline counts
+
+**API routes:**
+
+- Acquisition lists: `GET /api/external/acquisition/lists`, `/api/external/acquisition/lists/:listId`, `/api/external/acquisition/lists/status`
+- Deals: `GET /api/external/deals`, `/api/external/deals/:dealId`, `/api/external/deals/summary`
+
+JWT-gated routes at the original unprefixed paths remain for the Command Center. All SDK CLI calls use `/api/external/*` gated by `requireApiKey`.
+
+**Note:** List-inspection routing lives in `/om` (Acquisition Operations dispatch). The `/acquisition` skill was folded into `/om`; all list reads still route to `elevasis-sdk acquisition:list:get <uuid>`.
+
+**Flags (all acquisition commands):**
+
+| Flag                | Description                                        |
+| ------------------- | -------------------------------------------------- |
+| `--pretty`          | Human-readable terminal output instead of raw JSON |
+| `--api-url <url>` | Override the API base URL                          |
+
+**Implementation:** `packages/sdk/src/cli/commands/acquisition/`
+
+---
+
+## elevasis-sdk client:\*
+
+Full CRUD management for client records. The `client:*` family covers create, read, update, and delete operations at `/api/external/clients`.
+
+For complete field definitions, filter options, and relationship semantics, see the [Clients feature documentation](/technical/features/clients).
+
+**Quick reference:**
+
+```bash
+elevasis-sdk client:list
+elevasis-sdk client:get <id>
+elevasis-sdk client:create --name "Acme Corp"
+elevasis-sdk client:update <id> --name "Acme Corp Updated"
+elevasis-sdk client:delete <id>
+```
+
+**Flags:**
+
+| Flag                | Description                                        |
+| ------------------- | -------------------------------------------------- |
+| `--pretty`          | Human-readable terminal output instead of raw JSON |
+| `--api-url <url>` | Override the API base URL                          |
+
+**Implementation:** `packages/sdk/src/cli/commands/` (client family)
+
+---
+
+## elevasis-sdk agent:\*
+
+Read-only inspection of deployed agents.
+
+```bash
+elevasis-sdk agent:list
+elevasis-sdk agent:get <id>
+```
+
+- `agent:list` -- list all agents registered for the organization
+- `agent:get <id>` -- get metadata and schema for a specific agent
+
+**API routes:** `GET /api/external/agents`, `/api/external/agents/:id`
+
+**Flags:**
+
+| Flag                | Description                                        |
+| ------------------- | -------------------------------------------------- |
+| `--pretty`          | Human-readable terminal output instead of raw JSON |
+| `--api-url <url>` | Override the API base URL                          |
+
+**Implementation:** `packages/sdk/src/cli/commands/` (agent family)
+
+---
+
+## elevasis-sdk session:\*
+
+Inspect and manage agent sessions.
+
+```bash
+elevasis-sdk session:list
+elevasis-sdk session:get <id>
+elevasis-sdk session:end <id>
+```
+
+- `session:list` -- list sessions for the organization; supports filtering by resource, status, and time range
+- `session:get <id>` -- get full session detail including messages and events
+- `session:end <id>` -- gracefully end an active session
+
+**API routes:** `GET /api/external/sessions`, `/api/external/sessions/:id`, `POST /api/external/sessions/:id/end`
+
+**Flags:**
+
+| Flag                | Description                                        |
+| ------------------- | -------------------------------------------------- |
+| `--pretty`          | Human-readable terminal output instead of raw JSON |
+| `--api-url <url>` | Override the API base URL                          |
+
+**Implementation:** `packages/sdk/src/cli/commands/` (session family)
+
+---
+
+## elevasis-sdk queue:\*
+
+Manage HITL command queue tasks. See the [Command Queue CLI Guide](/technical/development/agent-driven-development/command-cli-guide) for the full command reference.
+
+**Quick reference:**
+
+```bash
+elevasis-sdk queue:list --status pending --pretty
+elevasis-sdk queue:get <id> --pretty
+elevasis-sdk queue:select <id> --action-id <action-id> --pretty
+elevasis-sdk queue:expire <id> --pretty
+elevasis-sdk queue:status --pretty
+```
+
+**Auth:** Calls `/api/external/command-queue/*` with API-key auth.
+
+---
+
+## elevasis-sdk schedule:\*
+
+Manage recurring, relative, and absolute task schedules. See the [Schedule CLI Guide](/technical/development/agent-driven-development/schedule-cli-guide) for the full command reference including schedule config JSON shapes.
+
+**Quick reference:**
+
+```bash
+elevasis-sdk schedule:list --status active --pretty
+elevasis-sdk schedule:get <id> --pretty
+elevasis-sdk schedule:create --name <name> --target-resource-type workflow --target-resource-id <id> --schedule-config '{...}' --pretty
+elevasis-sdk schedule:update <id> --name "Updated name" --pretty
+elevasis-sdk schedule:pause <id> --pretty
+elevasis-sdk schedule:resume <id> --pretty
+elevasis-sdk schedule:cancel <id> --pretty
+```
+
+**Auth:** Calls `/api/external/task-scheduler/schedules*` with API-key auth.
+
+---
+
+## elevasis-sdk om:\*
+
+Knowledge map inspection. The `om:*` (Organization Model) commands expose knowledge graph traversal via the CLI.
+
+For the full command reference, flag details, and graph architecture, see the [knowledge:\* CLI documentation](/technical/features/knowledge/knowledge-cli).
+
+**Quick reference:**
+
+```bash
+elevasis-sdk knowledge:ls /by-system/sales.crm
+elevasis-sdk knowledge:cat <node-id>
+elevasis-sdk knowledge:graph
+```
+
+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`.
+
+---
+
+## elevasis-sdk ui:use-local / ui:use-published
+
+Switch the `@elevasis/ui` dependency in an external project between a local tarball build and the published npm package.
+
+**Synopsis:**
+
+```bash
+elevasis-sdk ui:use-local
+elevasis-sdk ui:use-published
+```
+
+**Behavior:**
+
+- `ui:use-local` -- builds a tarball from the local `packages/ui/` source and rewrites the project's `package.json` to point at the tarball path. Use this during active `@elevasis/ui` development to test changes without publishing.
+- `ui:use-published` -- reverts `package.json` to the published `@elevasis/ui` version string and removes any local tarball reference.
+
+Both commands install after rewriting `package.json`. The `external/_template` root scripts `ui:use-local` and `ui:use-published` are compatibility wrappers that delegate to these CLI commands.
+
+**Implementation:** `packages/sdk/src/cli/commands/ui/ui-switcher.ts`
+
+---
+
+## Appendix: Domain Status
+
+Current status of all SDK CLI domains. Domains marked `deferred` have no CLI commands yet.
+
+| Domain      | CLI surface                                                               | API surface                                                | Status                       |
+| ----------- | ------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------- |
+| platform    | top-level SDK commands                                                    | mixed platform APIs                                        | implemented                  |
+| project     | `project:*`                                                               | `apps/api/src/projects/`                                   | implemented                  |
+| knowledge   | `knowledge:*`                                                             | file/generated knowledge data                              | implemented                  |
+| creds       | `creds *` nested Commander group                                          | credentials API                                            | implemented                  |
+| ui          | `ui:*`                                                                    | local project file edits                                   | implemented                  |
+| request     | `request:submit`, `request:list`, `request:get`                           | requests API                                               | implemented read/write scope |
+| error       | `error resolve`, `error resolve-execution`                                | execution error APIs                                       | partial                      |
+| acquisition | `acquisition:list:*`, `acquisition:deal:*`                                | `/api/external/acquisition/lists*`, `/api/external/deals*` | implemented read-only scope  |
+| client      | `client:*`                                                                | `/api/external/clients`                                    | implemented read/write scope |
+| agent       | `agent:list`, `agent:get`                                                 | `/api/external/agents*`                                    | implemented read-only scope  |
+| session     | `session:list`, `session:get`, `session:end`                              | `/api/external/sessions*`                                  | implemented management scope |
+| queue       | `queue:list`, `queue:get`, `queue:select`, `queue:expire`, `queue:status` | `/api/external/command-queue*`                             | implemented                  |
+| schedule    | `schedule:list`, `schedule:get`, `schedule:create`, `schedule:update`     | `/api/external/task-scheduler/schedules*`                  | implemented                  |
+| content     | none                                                                      | not scoped here                                            | deferred                     |
+| seo         | none                                                                      | not scoped here                                            | deferred                     |
+| monitoring  | none                                                                      | not scoped here                                            | deferred                     |
+
+### Promotion Criteria
+
+A domain should meet all four criteria before gaining a `*:list` / `*:get` surface in the SDK CLI:
+
+1. The domain has DB-backed state with tenant scoping.
+2. External SDK tenants have a plausible read or operation need.
+3. Operators repeat the same query pattern often enough that ad-hoc DB reads are becoming workflow surface.
+4. There are at least three concrete use cases.
+
+---
+
+**Last Updated:** 2026-05-19