---
name: elevasis
description: Elevasis platform operations -- check, deploy, execute, inspect, and debug SDK resources
---

# Elevasis Platform Operations

Manage SDK resources in the `operations/` workspace via the `elevasis-sdk` CLI.

**Usage:**

- `/elevasis` -- Show available operations
- `/elevasis check` -- Validate resource definitions
- `/elevasis deploy [--prod]` -- Deploy resources
- `/elevasis exec <resourceId> [--input '...']` -- Execute a resource
- `/elevasis describe <resourceId>` -- Show resource schema
- `/elevasis logs <resourceId>` -- View recent executions
- `/elevasis creds` -- Manage credentials

## Critical Rules

- **Always describe before exec** -- run `describe` first to see the exact input schema
- **Use `-f` for complex inputs** -- write JSON to a temp file to avoid shell escaping issues
- **Always `check` before `deploy`** -- catches schema and config errors early

## Environment

The CLI authenticates via `ELEVASIS_PLATFORM_KEY` in the root `.env` file. The CLI walks up directories to find `.env`, so it works from both the project root and `operations/`.

For dev vs prod targeting:

- Default: production (`https://api.elevasis.io`)
- `--prod` flag: explicitly targets production (overrides `NODE_ENV=development`)
- `ELEVASIS_API_URL` env var: override to any custom URL

## Operations

### Check

Validate all resource definitions (schemas, contracts, config):

```bash
pnpm elevasis-sdk check
```

Reports: resource count, validation errors, schema serialization warnings. Exit code 0 = pass.

### Deploy

Bundle and deploy resources to the Elevasis platform.

```bash
pnpm elevasis-sdk deploy [--prod]
```

Replace `[--prod]` with `--prod` when targeting production.

**Version bumping flags** (written back to `src/index.ts`):

- `--major` -- bump major (1.0.0 to 2.0.0) for breaking contract changes
- `--minor` -- bump minor (1.0.0 to 1.1.0) for new features
- `--patch` -- bump patch (1.0.0 to 1.0.1) for fixes

Deploy replaces the previous active deployment. Resources become executable immediately.

### Describe

**Always run before executing.** Shows resource metadata, input/output schemas, and step chain:

```bash
pnpm elevasis-sdk describe <resourceId>

# JSON output for programmatic use
pnpm elevasis-sdk describe <resourceId> --json
```

Output includes: type, name, version, status, domains, input schema (required/optional fields with types), output schema, step definitions with entry point and routing.

### Execute

Run a deployed resource. **Always `describe` first to see the input schema.**

```bash
# Simple input (inline JSON)
pnpm elevasis-sdk exec <resourceId> -i '{"key": "value"}'

# Complex input (temp file -- PREFERRED for non-trivial payloads)
# Write input to a temp file first, then reference it with -f
pnpm elevasis-sdk exec <resourceId> -f .tmp-input.json

# Async execution (for long-running workflows -- polls until complete)
pnpm elevasis-sdk exec <resourceId> -f .tmp-input.json --async
```

**When to use `-f` (file input):**

- Input contains nested objects, arrays, or special characters
- Input has quotes that conflict with shell escaping
- Input is reused across multiple executions
- Any time inline `-i` causes parsing errors

**Temp file pattern:**

1. Write the JSON to a temp file inside the project (e.g., `operations/.tmp-input.json`)
2. Execute with `-f .tmp-input.json`
3. Delete the temp file after

**Sync vs async:**

- Sync (default): blocks until execution completes, shows result inline
- Async (`--async`): returns execution ID immediately, polls every 3s with elapsed timer
- Use `--async` for workflows that may exceed 30 seconds

**Connection failure recovery:** If the connection drops during sync execution, the CLI automatically searches recent executions for a running one and resumes polling.

### List Resources

View all deployed resources:

```bash
pnpm elevasis-sdk resources

# JSON output
pnpm elevasis-sdk resources --json
```

Shows: resource ID, type (workflow/agent), name, description, status.

### Execution History

View past executions for a resource:

```bash
# List recent executions (default: last 50)
pnpm elevasis-sdk executions <resourceId>

# Filter by status
pnpm elevasis-sdk executions <resourceId> --status failed --limit 10

# View specific execution (full detail with logs)
pnpm elevasis-sdk execution <resourceId> <executionId>

# Logs only (skip metadata)
pnpm elevasis-sdk execution <resourceId> <executionId> --logs-only

# Include input and result data
pnpm elevasis-sdk execution <resourceId> <executionId> --input --result
```

**`executions` flags:** `--limit <n>` (default 50), `--status running|completed|failed`, `--json`

**`execution` flags:** `--logs-only`, `--input`, `--result`, `--json`

Execution detail shows: status, start/end times, duration, input, result, error (if failed), and timestamped logs with level (ERROR/WARN/INFO/DEBUG).

### Deployments

View deployment history:

```bash
pnpm elevasis-sdk deployments
```

Shows: deployment ID, SDK version, status (active/deploying/failed/stopped), created timestamp.

### Credentials

Manage integration credentials (API keys, webhook secrets):

```bash
# List credentials (metadata only, secrets not exposed)
pnpm elevasis-sdk creds list

# Create a credential
pnpm elevasis-sdk creds create --name my-api-key --type api-key --value '{"apiKey":"sk-..."}'

# Update a credential value
pnpm elevasis-sdk creds update my-api-key --value '{"apiKey":"new-key"}'

# Rename a credential
pnpm elevasis-sdk creds rename old-name --to new-name

# Delete a credential
pnpm elevasis-sdk creds delete my-api-key --force
```

Credential names: lowercase, digits, hyphens only (`^[a-z0-9]+(-[a-z0-9]+)*$`). Types: `api-key`, `webhook-secret`.

### Rename Resource

Rename a resource ID across all platform tables:

```bash
# Dry run (preview only)
pnpm elevasis-sdk rename old-id --to new-id

# Apply rename
pnpm elevasis-sdk rename old-id --to new-id --execute
```

Always dry-run first to see affected tables and row counts.

### Error Resolution

Mark execution errors as resolved:

```bash
# Resolve a specific error
pnpm elevasis-sdk error resolve <errorId>

# Resolve all errors for an execution
pnpm elevasis-sdk error resolve-execution <executionId>
```

## Standard Workflow

```
1. Write/modify resources     operations/src/
2. Type-check                 pnpm -C operations run check-types
3. Validate                   /elevasis check
4. Deploy                     /elevasis deploy --prod
5. Describe                   /elevasis describe <id>
6. Execute                    /elevasis exec <id> -f input.json
7. Inspect logs               /elevasis logs <id>
```

## Debugging Checklist

When an execution fails:

1. **Get the execution ID** from the exec output or `executions <resourceId> --status failed`
2. **Read the logs**: `execution <resourceId> <executionId> --logs-only`
3. **Check the input**: `execution <resourceId> <executionId> --input`
4. **Check the error**: `execution <resourceId> <executionId> --result`
5. **Fix the handler**, redeploy, re-execute

---

## Capability Surface

When a user asks what skills or commands are available, do NOT answer from recollection.

- **Skill inventory:** Read `.claude/Overview.md` — it is the authoritative list of skills available in this project.
- **Live CLI capability:** Run `pnpm elevasis-sdk cli` — it outputs every command and domain currently registered in the SDK, grouped by domain.
