@elevasis/sdk 1.25.0 → 1.26.0

package/reference/cli.mdx

@@ -1,7 +1,6 @@
 ---
 title: CLI Reference
-description: Full reference for every elevasis-sdk CLI command -- validate, deploy, execute, inspect resources, and manage Projects, Notes, Acquisition, Clients, Agents, Sessions, Queues, and Schedules through the canonical SDK CLI surface
-loadWhen: "Running CLI operations"
+description: Core elevasis-sdk CLI commands -- validate, deploy, execute, inspect resources, manage credentials, rename, and enumerate the command catalog
 ---
 
 The `elevasis-sdk` CLI is the primary interface for working with your Elevasis SDK project. Install it as part of `@elevasis/sdk` and use it to validate resource definitions, deploy to the platform, inspect execution history, and manage Projects through `project:*`.
@@ -14,6 +13,8 @@ pnpm add @elevasis/sdk
 
 After installation, the `elevasis-sdk` binary is available in your project's `node_modules/.bin/`. Most commands require `ELEVASIS_PLATFORM_KEY` to be set in your environment or a `.env` file.
 
+For management commands (project:\*, note:\*, acquisition:\*, client:\*, agent:\*, session:\*, queue:\*, schedule:\*, om:\*, ui:\*), see [CLI Management](cli-management.mdx).
+
 ---
 
 ## elevasis-sdk check
@@ -503,296 +504,6 @@ elevasis-sdk rename ist-upload-workflow --to ist-upload-contacts-workflow --exec
 
 ---
 
-## 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 personal 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.
-
-Notes are personal to the target user and scoped to the calling organization. The external API surface exposes `GET + POST` only; `note:update` and `note:delete` are not yet available via SDK CLI. Users edit and delete notes through the right-panel view in the Command Center.
-
-### 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
-- 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 **personal 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 Notes panel view (`NotesPanelView`) is 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 user can optionally make a note global, but the default scope is the current org.
-- **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 cli
 
 Enumerate the full command catalog registered in the CLI at runtime.
@@ -847,211 +558,6 @@ pnpm -C external/<project>/operations exec elevasis-sdk cli
 
 ---
 
-## 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`
-
----
-
 ## Global Flags
 
 These flags are accepted by all commands:
@@ -1070,38 +576,4 @@ These flags are accepted by all commands:
 
 ---
 
-## 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-18
+**Last Updated:** 2026-05-19