@elevasis/sdk 1.24.0 → 1.25.0

package/reference/cli.mdx

@@ -1,808 +1,1107 @@
----
-title: CLI Reference
-description: Full reference for every elevasis-sdk CLI command -- validate, deploy, execute, inspect resources, and manage Projects through the canonical SDK CLI surface
-loadWhen: "Running CLI operations"
----
-
-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:*`.
-
-**Installation:**
-
-```bash
-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.
-
----
-
-## elevasis-sdk check
-
-Validate all resource definitions in your project without deploying.
-
-**Synopsis:**
-
-```
-elevasis-sdk check
-```
-
-**Behavior:**
-
-- Imports your `src/index.ts` and runs it through `ResourceRegistry` validation
-- Catches the same errors that the platform catches at deploy time:
-  - Duplicate `resourceId` within the organization
-  - Invalid model configuration (temperature and token bounds)
-  - `ExecutionInterface` form fields not matching `inputSchema`
-  - Broken workflow step chains (`next` referencing non-existent steps)
-  - Relationship declarations referencing non-existent resources
-- Exits with code 0 on success, code 1 on validation failure
-
-**Flags:**
-
-| Flag                | Description               |
-| ------------------- | ------------------------- |
-| `--api-url <url>` | Override the API base URL |
-
-**Example output (success):**
-
-```
-$ elevasis-sdk check
-
-  Validating...    done (4 resources, 0 errors)
-```
-
-**Example output (failure):**
-
-```
-$ elevasis-sdk check
-
-  Validating...
-    ERROR  Duplicate resource ID 'onboard-client' in organization 'Acme Corp'
-    ERROR  Workflow step 'send-email' references non-existent next step 'notify'
-
-  2 errors.
-```
-
----
-
-## elevasis-sdk deploy
-
-Bundle your project with esbuild and deploy it to the Elevasis platform.
-
-**Synopsis:**
-
-```
-elevasis-sdk deploy
-```
-
-**Behavior:**
-
-- Authenticates with `ELEVASIS_PLATFORM_KEY` and resolves your organization name
-- Runs the same `ResourceRegistry` validation as `elevasis-sdk check`
-- Bundles your `src/index.ts` and all dependencies into a single self-contained JS file (`dist/bundle.js`, approximately 50-200 KB)
-- Uploads the bundle plus resource metadata to `POST /api/external/deploy`
-- Streams deploy status and prints the result
-- Resources are live immediately after a successful deploy
-
-**Flags:**
-
-| Flag                | Description                                                               |
-| ------------------- | ------------------------------------------------------------------------- |
-| `--api-url <url>` | Override the API base URL (default: production)                           |
-| `--prod`            | Force production target, overriding `NODE_ENV=development` (internal use) |
-
-**Environment variables:**
-
-| Variable                | Description                         |
-| ----------------------- | ----------------------------------- |
-| `ELEVASIS_PLATFORM_KEY` | Required. Your `sk_...` API key     |
-| `ELEVASIS_API_URL`      | Optional. Override the API base URL |
-
-**Example output (success):**
-
-```
-$ elevasis-sdk deploy
-
-  Authenticating...          done (acme-corp)
-  Validating...              done (4 resources, 0 errors)
-  Bundling...                done (142 KB)
-  Uploading...               done
-
-  Deployed! 4 resources live.
-  Deployment: deploy_abc123
-```
-
-**Example output (validation failure):**
-
-```
-$ elevasis-sdk deploy
-
-  Authenticating...          done (acme-corp)
-  Validating...
-    ERROR  Duplicate resource ID 'onboard-client' in organization 'Acme Corp'
-    ERROR  Workflow step 'send-email' references non-existent next step 'notify'
-
-  2 errors. Deploy aborted.
-```
-
----
-
-## elevasis-sdk exec
-
-Execute a deployed resource by ID.
-
-**Synopsis:**
-
-```
-elevasis-sdk exec <resource> --input '{...}'
-```
-
-**Behavior:**
-
-- Executes the named resource synchronously by default and streams the result
-- Use `--async` to return an `executionId` immediately and poll for completion
-- `--input` accepts a JSON string matching the resource's `inputSchema`
-- Organization is derived from your API key -- no org prefix needed
-
-**Flags:**
-
-| Flag                | Description                                             |
-| ------------------- | ------------------------------------------------------- |
-| `--input <json>`  | JSON input matching the resource's input schema         |
-| `--async`           | Execute asynchronously, return execution ID immediately |
-| `--json`            | Output raw JSON instead of formatted display            |
-| `--api-url <url>` | Override the API base URL                               |
-
-**Example:**
-
-```bash
-elevasis-sdk exec onboard-client --input '{"clientName": "Jane", "email": "jane@example.com"}'
-```
-
-```
-  Executing onboard-client...
-
-  Status:   completed
-  Duration: 1.4s
-
-  Output:
-  {
-    "success": true,
-    "clientId": "client_1708521600000",
-    "welcomeEmailSent": true
-  }
-```
-
-**Async example:**
-
-```bash
-elevasis-sdk exec onboard-client --input '{"clientName": "Jane"}' --async
-```
-
-```
-  Execution started: exec_550e8400
-  Poll with: elevasis-sdk execution onboard-client exec_550e8400
-```
-
----
-
-## elevasis-sdk resources
-
-List all deployed resources for your organization.
-
-**Synopsis:**
-
-```
-elevasis-sdk resources
-```
-
-**Behavior:**
-
-- Lists all resources registered to your organization on the platform
-- In production, only `status: 'prod'` resources are shown
-- Displays resource ID, type, name, and status
-
-**Flags:**
-
-| Flag                | Description               |
-| ------------------- | ------------------------- |
-| `--json`            | Output raw JSON           |
-| `--api-url <url>` | Override the API base URL |
-
-**Example output:**
-
-```
-$ elevasis-sdk resources
-
-  onboard-client    workflow   Onboard Client       prod
-  send-report       workflow   Send Weekly Report   prod
-  email-assistant   agent      Email Assistant      prod
-  support-bot       agent      Support Bot          dev
-```
-
----
-
-## elevasis-sdk executions
-
-View execution history for a resource.
-
-**Synopsis:**
-
-```
-elevasis-sdk executions [resource]
-```
-
-**Behavior:**
-
-- Lists recent executions for the specified resource
-- If `resource` is omitted, lists executions across all resources
-- Supports filtering by status and limiting result count
-
-**Flags:**
-
-| Flag                  | Description                                                     |
-| --------------------- | --------------------------------------------------------------- |
-| `--limit <n>`       | Maximum number of executions to return (default: 20)            |
-| `--status <status>` | Filter by status: `running`, `completed`, `failed`, `cancelled` |
-| `--json`              | Output raw JSON                                                 |
-| `--api-url <url>`   | Override the API base URL                                       |
-
-**Example:**
-
-```bash
-elevasis-sdk executions onboard-client --limit 5
-```
-
-```
-  exec_abc001   completed   2026-02-25 14:32:01   1.2s
-  exec_abc002   completed   2026-02-25 13:18:44   0.9s
-  exec_abc003   failed      2026-02-25 12:05:22   0.3s
-  exec_abc004   completed   2026-02-24 17:51:09   1.8s
-  exec_abc005   completed   2026-02-24 16:30:55   1.1s
-```
-
----
-
-## elevasis-sdk execution
-
-View full detail for a single execution.
-
-**Synopsis:**
-
-```
-elevasis-sdk execution <resource> <id>
-```
-
-**Behavior:**
-
-- Shows the complete execution record: input, output, logs, duration, and error (if any)
-- Use `--json` to get the raw JSON response for programmatic use
-
-**Flags:**
-
-| Flag                | Description               |
-| ------------------- | ------------------------- |
-| `--json`            | Output raw JSON           |
-| `--api-url <url>` | Override the API base URL |
-
-**Example:**
-
-```bash
-elevasis-sdk execution onboard-client exec_abc001
-```
-
-```
-  Resource:   onboard-client
-  Status:     completed
-  Started:    2026-02-25 14:32:01
-  Duration:   1.2s
-
-  Input:
-  {
-    "clientName": "Jane",
-    "email": "jane@example.com"
-  }
-
-  Output:
-  {
-    "success": true,
-    "clientId": "client_1708521600000",
-    "welcomeEmailSent": true
-  }
-
-  Logs:
-  [14:32:01.123]  Starting onboard-client workflow
-  [14:32:01.456]  Created client record
-  [14:32:01.891]  Welcome email sent to jane@example.com
-```
-
----
-
-## elevasis-sdk deployments
-
-List all deployments for your organization.
-
-**Synopsis:**
-
-```
-elevasis-sdk deployments
-```
-
-**Behavior:**
-
-- Shows deployment history with status, timestamp, and resource count
-- Active deployment is marked; previous deployments show as `stopped`
-
-**Flags:**
-
-| Flag                | Description               |
-| ------------------- | ------------------------- |
-| `--json`            | Output raw JSON           |
-| `--api-url <url>` | Override the API base URL |
-
-**Example output:**
-
-```
-$ elevasis-sdk deployments
-
-  deploy_abc123   active    2026-02-25 14:00:00   4 resources
-  deploy_abc122   stopped   2026-02-24 09:30:00   3 resources
-  deploy_abc121   stopped   2026-02-23 11:15:00   3 resources
-```
-
----
-
-## elevasis-sdk describe
-
-Show the definition of a deployed resource.
-
-**Synopsis:**
-
-```
-elevasis-sdk describe <resource>
-```
-
-**Behavior:**
-
-- Displays resource metadata: name, type, description, status, and domains
-- Shows the full `inputSchema` and `outputSchema` as JSON
-- Type is color-coded: yellow for workflows, magenta for agents
-
-**Flags:**
-
-| Flag                | Description               |
-| ------------------- | ------------------------- |
-| `--json`            | Output raw JSON response  |
-| `--api-url <url>` | Override the API base URL |
-
-**Example:**
-
-```bash
-elevasis-sdk describe onboard-client
-```
-
-```
-  onboard-client  [workflow]
-
-  Name:         Onboard Client
-  Description:  Creates a client record and sends a welcome email
-  Status:       prod
-  Domains:      crm, email
-
-  Input Schema:
-  {
-    "type": "object",
-    "properties": {
-      "clientName": { "type": "string" },
-      "email": { "type": "string", "format": "email" }
-    },
-    "required": ["clientName", "email"]
-  }
-```
-
----
-
-## elevasis-sdk creds
-
-Manage credentials for your project.
-
-**Synopsis:**
-
-```
-elevasis-sdk creds list
-elevasis-sdk creds set <key> <value>
-elevasis-sdk creds remove <key>
-```
-
-**Behavior:**
-
-- `list` -- display all credentials configured for the project
-- `set` -- add or update a credential
-- `remove` -- delete a credential
-
-**Flags:**
-
-| Flag                | Description               |
-| ------------------- | ------------------------- |
-| `--api-url <url>` | Override the API base URL |
-
-**Examples:**
-
-```bash
-elevasis-sdk creds list
-elevasis-sdk creds set OPENAI_API_KEY sk-proj-***
-elevasis-sdk creds remove OPENAI_API_KEY
-```
-
----
-
-## elevasis-sdk rename
-
-Rename a resource ID across all reference tables in the platform database.
-
-**Synopsis:**
-
-```
-elevasis-sdk rename <old-id> --to <new-id> [--execute] [--prod]
-```
-
-**Behavior:**
-
-- Dry-run by default -- shows all affected rows per table without modifying any data
-- Pass `--execute` to perform the rename
-- Org-scoped: only updates rows belonging to your organization
-- Updates resource references across 6 tables:
-
-| Table                | Column(s) updated |
-| -------------------- | ----------------- |
-| `executions`         | `resource_id`     |
-| `sessions`           | `resource_id`     |
-| `workflow_configs`   | `resource_id`     |
-| `workflow_schedules` | `resource_id`     |
-| `execution_events`   | `resource_id`     |
-| `session_events`     | `resource_id`     |
-
-**Flags:**
-
-| Flag                | Description                             |
-| ------------------- | --------------------------------------- |
-| `--to <new-id>`   | Required. The new resource ID           |
-| `--execute`         | Perform the rename (default is dry-run) |
-| `--prod`            | Target the production environment       |
-| `--api-url <url>` | Override the API base URL               |
-
-**Example (dry-run):**
-
-```bash
-elevasis-sdk rename ist-upload-workflow --to ist-upload-contacts-workflow
-```
-
-```
-  Dry run — no changes made.
-
-  Rows that would be updated:
-    executions          6
-    sessions            0
-    workflow_configs    0
-    workflow_schedules  0
-    execution_events    0
-    session_events      0
-
-  Total: 6 rows
-
-  Re-run with --execute to apply changes.
-```
-
-**Example (execute):**
-
-```bash
-elevasis-sdk rename ist-upload-workflow --to ist-upload-contacts-workflow --execute
-```
-
-**Implementation:** `packages/sdk/src/cli/commands/rename.ts` -- delegates to `POST /api/external/resources/rename`
-
----
-
-## 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                                                     |
-
----
-
-### 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`
-
----
-
-## 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:
-
-| Flag                | Description                                                                                         |
-| ------------------- | --------------------------------------------------------------------------------------------------- |
-| `--api-url <url>` | Override the API base URL. Priority: flag > `ELEVASIS_API_URL` env var > `NODE_ENV`-based default |
-| `--json`            | Output raw JSON (available on most commands)                                                        |
-
-**API base URL resolution:**
-
-- Production (default): `https://api.elevasis.io`
-- Development (`NODE_ENV=development`): `http://localhost:<port>`
-- Override: set `ELEVASIS_API_URL` or pass `--api-url`
-- Force production: pass `--prod` on `deploy` (overrides `NODE_ENV=development`)
-
----
-
-**Last Updated:** 2026-04-17
+---
+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"
+---
+
+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:*`.
+
+**Installation:**
+
+```bash
+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.
+
+---
+
+## elevasis-sdk check
+
+Validate all resource definitions in your project without deploying.
+
+**Synopsis:**
+
+```
+elevasis-sdk check
+```
+
+**Behavior:**
+
+- Imports your `src/index.ts` and runs it through `ResourceRegistry` validation
+- Catches the same errors that the platform catches at deploy time:
+  - Duplicate `resourceId` within the organization
+  - Invalid model configuration (temperature and token bounds)
+  - `ExecutionInterface` form fields not matching `inputSchema`
+  - Broken workflow step chains (`next` referencing non-existent steps)
+  - Relationship declarations referencing non-existent resources
+- Exits with code 0 on success, code 1 on validation failure
+
+**Flags:**
+
+| Flag                | Description               |
+| ------------------- | ------------------------- |
+| `--api-url <url>` | Override the API base URL |
+
+**Example output (success):**
+
+```
+$ elevasis-sdk check
+
+  Validating...    done (4 resources, 0 errors)
+```
+
+**Example output (failure):**
+
+```
+$ elevasis-sdk check
+
+  Validating...
+    ERROR  Duplicate resource ID 'onboard-client' in organization 'Acme Corp'
+    ERROR  Workflow step 'send-email' references non-existent next step 'notify'
+
+  2 errors.
+```
+
+---
+
+## elevasis-sdk deploy
+
+Bundle your project with esbuild and deploy it to the Elevasis platform.
+
+**Synopsis:**
+
+```
+elevasis-sdk deploy
+```
+
+**Behavior:**
+
+- Authenticates with `ELEVASIS_PLATFORM_KEY` and resolves your organization name
+- Runs the same `ResourceRegistry` validation as `elevasis-sdk check`
+- Bundles your `src/index.ts` and all dependencies into a single self-contained JS file (`dist/bundle.js`, approximately 50-200 KB)
+- Uploads the bundle plus resource metadata to `POST /api/external/deploy`
+- Streams deploy status and prints the result
+- Resources are live immediately after a successful deploy
+
+**Flags:**
+
+| Flag                | Description                                                               |
+| ------------------- | ------------------------------------------------------------------------- |
+| `--api-url <url>` | Override the API base URL (default: production)                           |
+| `--prod`            | Force production target, overriding `NODE_ENV=development` (internal use) |
+
+**Environment variables:**
+
+| Variable                | Description                         |
+| ----------------------- | ----------------------------------- |
+| `ELEVASIS_PLATFORM_KEY` | Required. Your `sk_...` API key     |
+| `ELEVASIS_API_URL`      | Optional. Override the API base URL |
+
+**Example output (success):**
+
+```
+$ elevasis-sdk deploy
+
+  Authenticating...          done (acme-corp)
+  Validating...              done (4 resources, 0 errors)
+  Bundling...                done (142 KB)
+  Uploading...               done
+
+  Deployed! 4 resources live.
+  Deployment: deploy_abc123
+```
+
+**Example output (validation failure):**
+
+```
+$ elevasis-sdk deploy
+
+  Authenticating...          done (acme-corp)
+  Validating...
+    ERROR  Duplicate resource ID 'onboard-client' in organization 'Acme Corp'
+    ERROR  Workflow step 'send-email' references non-existent next step 'notify'
+
+  2 errors. Deploy aborted.
+```
+
+---
+
+## elevasis-sdk exec
+
+Execute a deployed resource by ID.
+
+**Synopsis:**
+
+```
+elevasis-sdk exec <resource> --input '{...}'
+```
+
+**Behavior:**
+
+- Executes the named resource synchronously by default and streams the result
+- Use `--async` to return an `executionId` immediately and poll for completion
+- `--input` accepts a JSON string matching the resource's `inputSchema`
+- Organization is derived from your API key -- no org prefix needed
+
+**Flags:**
+
+| Flag                | Description                                             |
+| ------------------- | ------------------------------------------------------- |
+| `--input <json>`  | JSON input matching the resource's input schema         |
+| `--async`           | Execute asynchronously, return execution ID immediately |
+| `--json`            | Output raw JSON instead of formatted display            |
+| `--api-url <url>` | Override the API base URL                               |
+
+**Example:**
+
+```bash
+elevasis-sdk exec onboard-client --input '{"clientName": "Jane", "email": "jane@example.com"}'
+```
+
+```
+  Executing onboard-client...
+
+  Status:   completed
+  Duration: 1.4s
+
+  Output:
+  {
+    "success": true,
+    "clientId": "client_1708521600000",
+    "welcomeEmailSent": true
+  }
+```
+
+**Async example:**
+
+```bash
+elevasis-sdk exec onboard-client --input '{"clientName": "Jane"}' --async
+```
+
+```
+  Execution started: exec_550e8400
+  Poll with: elevasis-sdk execution onboard-client exec_550e8400
+```
+
+---
+
+## elevasis-sdk resources
+
+List all deployed resources for your organization.
+
+**Synopsis:**
+
+```
+elevasis-sdk resources
+```
+
+**Behavior:**
+
+- Lists all resources registered to your organization on the platform
+- In production, only `status: 'prod'` resources are shown
+- Displays resource ID, type, name, and status
+
+**Flags:**
+
+| Flag                | Description               |
+| ------------------- | ------------------------- |
+| `--json`            | Output raw JSON           |
+| `--api-url <url>` | Override the API base URL |
+
+**Example output:**
+
+```
+$ elevasis-sdk resources
+
+  onboard-client    workflow   Onboard Client       prod
+  send-report       workflow   Send Weekly Report   prod
+  email-assistant   agent      Email Assistant      prod
+  support-bot       agent      Support Bot          dev
+```
+
+---
+
+## elevasis-sdk executions
+
+View execution history for a resource.
+
+**Synopsis:**
+
+```
+elevasis-sdk executions [resource]
+```
+
+**Behavior:**
+
+- Lists recent executions for the specified resource
+- If `resource` is omitted, lists executions across all resources
+- Supports filtering by status and limiting result count
+
+**Flags:**
+
+| Flag                  | Description                                                     |
+| --------------------- | --------------------------------------------------------------- |
+| `--limit <n>`       | Maximum number of executions to return (default: 20)            |
+| `--status <status>` | Filter by status: `running`, `completed`, `failed`, `cancelled` |
+| `--json`              | Output raw JSON                                                 |
+| `--api-url <url>`   | Override the API base URL                                       |
+
+**Example:**
+
+```bash
+elevasis-sdk executions onboard-client --limit 5
+```
+
+```
+  exec_abc001   completed   2026-02-25 14:32:01   1.2s
+  exec_abc002   completed   2026-02-25 13:18:44   0.9s
+  exec_abc003   failed      2026-02-25 12:05:22   0.3s
+  exec_abc004   completed   2026-02-24 17:51:09   1.8s
+  exec_abc005   completed   2026-02-24 16:30:55   1.1s
+```
+
+---
+
+## elevasis-sdk execution
+
+View full detail for a single execution.
+
+**Synopsis:**
+
+```
+elevasis-sdk execution <resource> <id>
+```
+
+**Behavior:**
+
+- Shows the complete execution record: input, output, logs, duration, and error (if any)
+- Use `--json` to get the raw JSON response for programmatic use
+
+**Flags:**
+
+| Flag                | Description               |
+| ------------------- | ------------------------- |
+| `--json`            | Output raw JSON           |
+| `--api-url <url>` | Override the API base URL |
+
+**Example:**
+
+```bash
+elevasis-sdk execution onboard-client exec_abc001
+```
+
+```
+  Resource:   onboard-client
+  Status:     completed
+  Started:    2026-02-25 14:32:01
+  Duration:   1.2s
+
+  Input:
+  {
+    "clientName": "Jane",
+    "email": "jane@example.com"
+  }
+
+  Output:
+  {
+    "success": true,
+    "clientId": "client_1708521600000",
+    "welcomeEmailSent": true
+  }
+
+  Logs:
+  [14:32:01.123]  Starting onboard-client workflow
+  [14:32:01.456]  Created client record
+  [14:32:01.891]  Welcome email sent to jane@example.com
+```
+
+---
+
+## elevasis-sdk deployments
+
+List all deployments for your organization.
+
+**Synopsis:**
+
+```
+elevasis-sdk deployments
+```
+
+**Behavior:**
+
+- Shows deployment history with status, timestamp, and resource count
+- Active deployment is marked; previous deployments show as `stopped`
+
+**Flags:**
+
+| Flag                | Description               |
+| ------------------- | ------------------------- |
+| `--json`            | Output raw JSON           |
+| `--api-url <url>` | Override the API base URL |
+
+**Example output:**
+
+```
+$ elevasis-sdk deployments
+
+  deploy_abc123   active    2026-02-25 14:00:00   4 resources
+  deploy_abc122   stopped   2026-02-24 09:30:00   3 resources
+  deploy_abc121   stopped   2026-02-23 11:15:00   3 resources
+```
+
+---
+
+## elevasis-sdk describe
+
+Show the definition of a deployed resource.
+
+**Synopsis:**
+
+```
+elevasis-sdk describe <resource>
+```
+
+**Behavior:**
+
+- Displays resource metadata: name, type, description, status, and domains
+- Shows the full `inputSchema` and `outputSchema` as JSON
+- Type is color-coded: yellow for workflows, magenta for agents
+
+**Flags:**
+
+| Flag                | Description               |
+| ------------------- | ------------------------- |
+| `--json`            | Output raw JSON response  |
+| `--api-url <url>` | Override the API base URL |
+
+**Example:**
+
+```bash
+elevasis-sdk describe onboard-client
+```
+
+```
+  onboard-client  [workflow]
+
+  Name:         Onboard Client
+  Description:  Creates a client record and sends a welcome email
+  Status:       prod
+  Domains:      crm, email
+
+  Input Schema:
+  {
+    "type": "object",
+    "properties": {
+      "clientName": { "type": "string" },
+      "email": { "type": "string", "format": "email" }
+    },
+    "required": ["clientName", "email"]
+  }
+```
+
+---
+
+## elevasis-sdk creds
+
+Manage credentials for your project.
+
+**Synopsis:**
+
+```
+elevasis-sdk creds list
+elevasis-sdk creds set <key> <value>
+elevasis-sdk creds remove <key>
+```
+
+**Behavior:**
+
+- `list` -- display all credentials configured for the project
+- `set` -- add or update a credential
+- `remove` -- delete a credential
+
+**Flags:**
+
+| Flag                | Description               |
+| ------------------- | ------------------------- |
+| `--api-url <url>` | Override the API base URL |
+
+**Examples:**
+
+```bash
+elevasis-sdk creds list
+elevasis-sdk creds set OPENAI_API_KEY sk-proj-***
+elevasis-sdk creds remove OPENAI_API_KEY
+```
+
+---
+
+## elevasis-sdk rename
+
+Rename a resource ID across all reference tables in the platform database.
+
+**Synopsis:**
+
+```
+elevasis-sdk rename <old-id> --to <new-id> [--execute] [--prod]
+```
+
+**Behavior:**
+
+- Dry-run by default -- shows all affected rows per table without modifying any data
+- Pass `--execute` to perform the rename
+- Org-scoped: only updates rows belonging to your organization
+- Updates resource references across 6 tables:
+
+| Table                | Column(s) updated |
+| -------------------- | ----------------- |
+| `executions`         | `resource_id`     |
+| `sessions`           | `resource_id`     |
+| `workflow_configs`   | `resource_id`     |
+| `workflow_schedules` | `resource_id`     |
+| `execution_events`   | `resource_id`     |
+| `session_events`     | `resource_id`     |
+
+**Flags:**
+
+| Flag                | Description                             |
+| ------------------- | --------------------------------------- |
+| `--to <new-id>`   | Required. The new resource ID           |
+| `--execute`         | Perform the rename (default is dry-run) |
+| `--prod`            | Target the production environment       |
+| `--api-url <url>` | Override the API base URL               |
+
+**Example (dry-run):**
+
+```bash
+elevasis-sdk rename ist-upload-workflow --to ist-upload-contacts-workflow
+```
+
+```
+  Dry run — no changes made.
+
+  Rows that would be updated:
+    executions          6
+    sessions            0
+    workflow_configs    0
+    workflow_schedules  0
+    execution_events    0
+    session_events      0
+
+  Total: 6 rows
+
+  Re-run with --execute to apply changes.
+```
+
+**Example (execute):**
+
+```bash
+elevasis-sdk rename ist-upload-workflow --to ist-upload-contacts-workflow --execute
+```
+
+**Implementation:** `packages/sdk/src/cli/commands/rename.ts` -- delegates to `POST /api/external/resources/rename`
+
+---
+
+## 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.
+
+**Synopsis:**
+
+```
+elevasis-sdk cli [domain] [--format markdown|json]
+```
+
+**Behavior:**
+
+- Walks the registered Commander command graph and prints every command, its flags, and a one-line description
+- When `domain` is omitted, all domains are listed
+- `--format json` returns a structured array suitable for programmatic use; `--format markdown` (default) renders a human-readable table
+- The runtime catalog is always up to date with what is actually registered -- it does not parse TypeScript source
+
+**Flags:**
+
+| Flag                  | Description                                                 |
+| --------------------- | ----------------------------------------------------------- |
+| `--domain <domain>` | Filter output to one domain (alternative to positional arg) |
+| `--format <format>` | Output format: `markdown` (default) or `json`               |
+| `--api-url <url>`   | Override the API base URL                                   |
+
+**Examples:**
+
+```bash
+# Print the full catalog
+elevasis-sdk cli
+
+# Print only acquisition commands
+elevasis-sdk cli acquisition
+
+# Print the project domain as JSON
+elevasis-sdk cli --domain project --format json
+```
+
+From the workspace (repo package):
+
+```bash
+pnpm --filter @elevasis/sdk exec elevasis-sdk cli
+```
+
+From an external tenant project:
+
+```bash
+pnpm -C external/<project>/operations exec elevasis-sdk cli
+```
+
+**Implementation:** `packages/sdk/src/cli/commands/cli/cli.ts` -- catalog built by `packages/sdk/src/cli/commands/cli/catalog.ts`
+
+---
+
+## 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:
+
+| Flag                | Description                                                                                         |
+| ------------------- | --------------------------------------------------------------------------------------------------- |
+| `--api-url <url>` | Override the API base URL. Priority: flag > `ELEVASIS_API_URL` env var > `NODE_ENV`-based default |
+| `--json`            | Output raw JSON (available on most commands)                                                        |
+
+**API base URL resolution:**
+
+- Production (default): `https://api.elevasis.io`
+- Development (`NODE_ENV=development`): `http://localhost:<port>`
+- Override: set `ELEVASIS_API_URL` or pass `--api-url`
+- Force production: pass `--prod` on `deploy` (overrides `NODE_ENV=development`)
+
+---
+
+## 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