@elevasis/sdk 1.24.0 → 1.26.0

package/reference/cli.mdx

@@ -1,808 +1,579 @@
----
-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: 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:*`.
+
+**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.
+
+For management commands (project:\*, note:\*, acquisition:\*, client:\*, agent:\*, session:\*, queue:\*, schedule:\*, om:\*, ui:\*), see [CLI Management](cli-management.mdx).
+
+---
+
+## 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 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`
+
+---
+
+## 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-05-19