---
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:\*, skill:\*), 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
- Runs the skill coverage gate when `.claude/registries/skill-coverage.json` is present, ensuring every live CLI domain is covered by a template skill or explicitly waived
- 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 organization. Credentials store API keys and secrets server-side so they never appear in your worker code.

**Synopsis:**

```
elevasis-sdk creds list
elevasis-sdk creds create --name <name> --type <type> [--value <json>]
elevasis-sdk creds update <name> --value <json>
elevasis-sdk creds rename <name> --to <newName>
elevasis-sdk creds delete <name> [--force]
```

**Subcommands:**

- `list` -- display all credentials (metadata only, no secret values)
- `create` -- create a new credential; `--name` and `--type` are required; `--value` is an optional JSON string for the initial value
- `update <name>` -- replace the value of an existing credential; `--value` (JSON) is required
- `rename <name>` -- rename a credential; `--to <newName>` is required
- `delete <name>` -- delete a credential; pass `--force` to skip the confirmation prompt

**Flags:**

| Flag                | Description                                        |
| ------------------- | -------------------------------------------------- |
| `--name <name>`   | Credential name (create: required)                 |
| `--type <type>`   | Credential type, e.g. `api-key` (create: required) |
| `--value <json>`  | Credential value as a JSON string                  |
| `--to <newName>`  | New name (rename: required)                        |
| `--force`           | Skip confirmation prompt (delete)                  |
| `--api-url <url>` | Override the API base URL                          |

**Examples:**

```bash
elevasis-sdk creds list
elevasis-sdk creds create --name openai-key --type api-key --value '{"key":"sk-proj-***"}'
elevasis-sdk creds update openai-key --value '{"key":"sk-proj-new"}'
elevasis-sdk creds rename openai-key --to openai-prod-key
elevasis-sdk creds delete openai-prod-key --force
```

**Implementation:** `packages/sdk/src/cli/commands/creds/creds.ts`

---

## 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`

---

## elevasis-sdk doctor

Check that your Elevasis project is correctly configured.

**Synopsis:**

```
elevasis-sdk doctor [--verbose]
```

**Behavior:**

Runs four sequential checks and reports `[OK]` / `[FAIL]` / `[WARN]` for each. Exits with code 1 if any check fails. Later checks are skipped when a prerequisite fails.

1. Project root resolved -- locates the `.elevasis` marker file from the current working directory
2. `.env` found at project root
3. `ELEVASIS_PLATFORM_KEY` present and non-empty
4. API reachable and key valid -- calls `GET /api/external/health`

**Flags:**

| Flag        | Description                                                         |
| ----------- | ------------------------------------------------------------------- |
| `--verbose` | Print full paths, response bodies, and error details for each check |

**Example output (all passing):**

```
Running Elevasis SDK doctor checks...

[OK]   Project root: /path/to/my-project
[OK]   .env: Found at /path/to/my-project/.env
[OK]   API key: Set (length: 56)
[OK]   API: Reachable. Workspace: Acme Corp (ws_abc123)
[WARN] SDK compat: server minSdkVersion is 1.25.0; check is advisory in v1.

All checks passed. Your Elevasis project is correctly configured.
```

**Implementation:** `packages/sdk/src/cli/commands/doctor.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
