# stella sdk — Command Guide

## Overview

The `stella sdk` command group provides SDK management capabilities including update checking, changelog viewing, and deprecation notices.

## Commands

### Check for SDK Updates (CLI-SDK-64-001)

```bash
# Check for SDK updates
stella sdk update \
  [--tenant <id>] \
  [--language <lang>] \
  [--check-only] \
  [--changelog] \
  [--deprecations] \
  [--json]
```

**Options:**
| Flag | Description |
|------|-------------|
| `--tenant` / `-t` | Tenant context for the operation |
| `--language` / `-l` | SDK language filter (typescript, go, csharp, python, java). Omit for all |
| `--check-only` | Only check for updates, don't download |
| `--changelog` | Show changelog for available updates |
| `--deprecations` | Show deprecation notices |
| `--json` | Output in JSON format |

**Output:**
- Available SDK updates with version comparison
- Changelog entries for each update (when `--changelog` is used)
- Deprecation notices with migration guidance (when `--deprecations` is used)

### List Installed SDKs (CLI-SDK-64-001)

```bash
# List installed SDK versions
stella sdk list \
  [--tenant <id>] \
  [--language <lang>] \
  [--json]
```

**Options:**
| Flag | Description |
|------|-------------|
| `--tenant` / `-t` | Tenant context for the operation |
| `--language` / `-l` | SDK language filter |
| `--json` | Output in JSON format |

**Output:**
- Language/platform
- Package name
- Installed version
- Latest available version
- API version compatibility range
- Update status

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Error |
| 130 | Operation cancelled by user |

## JSON Schema: SdkUpdateResponse

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "success": { "type": "boolean" },
    "updates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "language": { "type": "string" },
          "displayName": { "type": "string" },
          "packageName": { "type": "string" },
          "installedVersion": { "type": "string" },
          "latestVersion": { "type": "string" },
          "updateAvailable": { "type": "boolean" },
          "minApiVersion": { "type": "string" },
          "maxApiVersion": { "type": "string" },
          "releaseDate": { "type": "string", "format": "date-time" },
          "changelog": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "version": { "type": "string" },
                "releaseDate": { "type": "string", "format": "date-time" },
                "type": { "type": "string" },
                "description": { "type": "string" },
                "isBreaking": { "type": "boolean" },
                "link": { "type": "string" }
              }
            }
          },
          "downloadUrl": { "type": "string" },
          "registryUrl": { "type": "string" },
          "docsUrl": { "type": "string" }
        }
      }
    },
    "deprecations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "language": { "type": "string" },
          "feature": { "type": "string" },
          "message": { "type": "string" },
          "deprecatedInVersion": { "type": "string" },
          "removedInVersion": { "type": "string" },
          "replacement": { "type": "string" },
          "migrationGuide": { "type": "string" },
          "severity": { "type": "string", "enum": ["info", "warning", "critical"] }
        }
      }
    },
    "checkedAt": { "type": "string", "format": "date-time" },
    "error": { "type": "string" }
  }
}
```

## Examples

### Check for all SDK updates

```bash
# Check all SDKs
stella sdk update

# Check with changelog
stella sdk update --changelog

# Check with deprecation notices
stella sdk update --deprecations

# Full check with all details
stella sdk update --changelog --deprecations
```

### Check specific language SDK

```bash
# Check TypeScript SDK only
stella sdk update --language typescript

# Check Go SDK with changelog
stella sdk update --language go --changelog
```

### List installed SDKs

```bash
# List all installed SDKs
stella sdk list

# List specific language
stella sdk list --language python

# Output as JSON for CI
stella sdk list --json
```

### CI/CD Integration

```bash
#!/bin/bash
# Check for SDK updates in CI and fail on breaking changes

stella sdk update --changelog --json > sdk-updates.json

# Check for breaking changes
BREAKING=$(jq '[.updates[].changelog[]? | select(.isBreaking == true)] | length' sdk-updates.json)
if [ "$BREAKING" -gt 0 ]; then
  echo "WARNING: $BREAKING breaking changes detected in available SDK updates"
  jq '.updates[].changelog[] | select(.isBreaking == true)' sdk-updates.json
fi

# Check for critical deprecations
CRITICAL=$(jq '[.deprecations[] | select(.severity == "critical")] | length' sdk-updates.json)
if [ "$CRITICAL" -gt 0 ]; then
  echo "ERROR: $CRITICAL critical deprecations require immediate attention"
  jq '.deprecations[] | select(.severity == "critical")' sdk-updates.json
  exit 1
fi
```

### Automated notification script

```bash
#!/bin/bash
# Send Slack notification when SDK updates are available

UPDATES=$(stella sdk update --json)
UPDATE_COUNT=$(echo "$UPDATES" | jq '[.updates[] | select(.updateAvailable == true)] | length')

if [ "$UPDATE_COUNT" -gt 0 ]; then
  curl -X POST -H 'Content-type: application/json' \
    --data "{\"text\": \"StellaOps SDK Updates Available: $UPDATE_COUNT updates\"}" \
    "$SLACK_WEBHOOK_URL"
fi
```

## Supported SDKs

| Language | Package Name | Registry |
|----------|-------------|----------|
| TypeScript | `@stellaops/sdk` | npm |
| Go | `github.com/stellaops/sdk-go` | Go modules |
| C# | `StellaOps.Sdk` | NuGet |
| Python | `stellaops-sdk` | PyPI |
| Java | `com.stellaops:sdk` | Maven Central |

## Changelog Entry Types

| Type | Icon | Description |
|------|------|-------------|
| `feature` | + | New feature or capability |
| `fix` | ~ | Bug fix |
| `breaking` | ! | Breaking change (major version) |
| `deprecation` | ? | Deprecation notice |

## Deprecation Severity Levels

| Severity | Description |
|----------|-------------|
| `info` | Informational notice, no immediate action required |
| `warning` | Feature will be removed in future version, plan migration |
| `critical` | Feature removed or will be removed imminently, immediate action required |

## Best Practices

1. **Check for updates regularly** in CI to stay informed about new SDK versions
2. **Review changelogs** before upgrading to understand new features and breaking changes
3. **Monitor deprecations** to plan migrations before features are removed
4. **Use `--check-only`** in automated pipelines to avoid unintended downloads
5. **Filter by language** when working on specific platform integrations
6. **Integrate with notifications** to alert teams about available updates