@elevasis/sdk 0.4.4 → 0.4.6

package/reference/cli/index.mdx

@@ -0,0 +1,496 @@
+---
+title: CLI Reference
+description: Full reference for every elevasis CLI command -- scaffold, validate, deploy, execute, and inspect resources
+---
+
+The `elevasis` CLI is the primary interface for working with your Elevasis SDK project. Install it as part of `@elevasis/sdk` and use it to scaffold projects, validate resource definitions, deploy to the platform, and inspect execution history.
+
+**Installation:**
+
+```bash
+npm install @elevasis/sdk
+```
+
+After installation, the `elevasis` binary is available in your project's `node_modules/.bin/`. Most commands require `ELEVASIS_API_KEY` to be set in your environment or a `.env` file.
+
+---
+
+## elevasis init
+
+Scaffold a new Elevasis SDK project in the specified directory.
+
+**Synopsis:**
+
+```
+elevasis init [directory]
+```
+
+**Behavior:**
+
+- Derives the organization slug from the directory name
+- Checks for file conflicts before writing any files
+- Scaffolds project structure including `src/index.ts`, `elevasis.config.ts`, `package.json`, `tsconfig.json`, and a `CLAUDE.md` with CLI reference and SDK patterns
+- Non-interactive: all values are derived automatically
+
+**Flags:**
+
+| Flag | Description |
+| ---- | ----------- |
+| (none) | Uses current directory if no argument is provided |
+
+**Example:**
+
+```bash
+elevasis init my-project
+```
+
+```
+  Scaffolding my-project/...
+
+  Created 18 files.
+
+  Next steps:
+    cd my-project
+    npm install
+    elevasis check
+```
+
+---
+
+## elevasis check
+
+Validate all resource definitions in your project without deploying.
+
+**Synopsis:**
+
+```
+elevasis 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 check
+
+  Validating...    done (4 resources, 0 errors)
+```
+
+**Example output (failure):**
+
+```
+$ elevasis 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 deploy
+
+Bundle your project with esbuild and deploy it to the Elevasis platform.
+
+**Synopsis:**
+
+```
+elevasis deploy
+```
+
+**Behavior:**
+
+- Authenticates with `ELEVASIS_API_KEY` and resolves your organization name
+- Runs the same `ResourceRegistry` validation as `elevasis 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) |
+
+**Environment variables:**
+
+| Variable | Description |
+| -------- | ----------- |
+| `ELEVASIS_API_KEY` | Required. Your `sk_...` API key |
+| `ELEVASIS_API_URL` | Optional. Override the API base URL |
+
+**Example output (success):**
+
+```
+$ elevasis 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 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 exec
+
+Execute a deployed resource by ID.
+
+**Synopsis:**
+
+```
+elevasis 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 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 exec onboard-client --input '{"clientName": "Jane"}' --async
+```
+
+```
+  Execution started: exec_550e8400
+  Poll with: elevasis execution onboard-client exec_550e8400
+```
+
+---
+
+## elevasis resources
+
+List all deployed resources for your organization.
+
+**Synopsis:**
+
+```
+elevasis 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 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 executions
+
+View execution history for a resource.
+
+**Synopsis:**
+
+```
+elevasis 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 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 execution
+
+View full detail for a single execution.
+
+**Synopsis:**
+
+```
+elevasis 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 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 deployments
+
+List all deployments for your organization.
+
+**Synopsis:**
+
+```
+elevasis 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 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 describe
+
+Show the definition of a deployed resource.
+
+**Synopsis:**
+
+```
+elevasis 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 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 env
+
+Manage environment variables for your project.
+
+**Synopsis:**
+
+```
+elevasis env list
+elevasis env set <key> <value>
+elevasis env remove <key>
+```
+
+**Behavior:**
+
+- `list` -- display all environment variables configured for the project
+- `set` -- add or update an environment variable
+- `remove` -- delete an environment variable
+
+**Flags:**
+
+| Flag | Description |
+| ---- | ----------- |
+| `--api-url <url>` | Override the API base URL |
+
+**Examples:**
+
+```bash
+elevasis env list
+elevasis env set OPENAI_API_KEY sk-proj-***
+elevasis env remove OPENAI_API_KEY
+```
+
+---
+
+## 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`
+
+---
+
+**Last Updated:** 2026-02-25