# stella seal - Command Guide

**Sprint:** SPRINT_20260105_002_004_CLI
**Task:** CLI-016 - Facet seal command documentation

## Overview

The `stella seal` command creates cryptographic seals for container image facets. A facet seal captures the state of specific file categories (binaries, libraries, configs, etc.) within an image and produces Merkle roots for tamper detection and drift analysis.

## Commands

### stella seal

Create a facet seal for an image.

```bash
stella seal <IMAGE> [OPTIONS]
```

#### Arguments

| Argument | Description |
|----------|-------------|
| `IMAGE` | Image reference or digest to seal (required) |

#### Options

| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--output <PATH>` | `-o` | Output file path for seal | stdout |
| `--store` | `-s` | Store seal in remote API | `true` |
| `--sign` | | Sign seal with DSSE | `true` |
| `--key <PATH>` | `-k` | Private key path for signing | configured key |
| `--facets <LIST>` | `-f` | Specific facets to seal (comma-separated) | all |
| `--format <FMT>` | | Output format: `json`, `yaml`, `compact` | `json` |
| `--verbose` | `-v` | Enable verbose output | `false` |

#### Examples

##### Seal all facets

```bash
stella seal sha256:abc123def456...
```

##### Seal specific facets

```bash
stella seal myregistry.io/app:v1.0 --facets runtime,config
```

##### Output to file

```bash
stella seal myregistry.io/app:v1.0 --output seal.json
```

##### Seal without storing remotely

```bash
stella seal sha256:abc123 --no-store --output local-seal.json
```

##### Seal with custom signing key

```bash
stella seal sha256:abc123 --key /path/to/private.key
```

---

## Built-in Facets

| Facet ID | Name | Description | File Patterns |
|----------|------|-------------|---------------|
| `runtime` | Runtime Binaries | Executable binaries and shared libraries | `*.so`, `*.dll`, `/usr/bin/*` |
| `config` | Configuration | Configuration files | `*.conf`, `*.yaml`, `*.json`, `/etc/*` |
| `static` | Static Assets | Static web assets | `*.css`, `*.js`, `*.html` |
| `scripts` | Scripts | Script files | `*.sh`, `*.py`, `*.rb` |
| `data` | Data Files | Data and cache files | `*.db`, `*.sqlite`, `/var/lib/*` |

---

## Output Formats

### JSON Format (Default)

```json
{
  "imageDigest": "sha256:abc123...",
  "createdAt": "2026-01-05T10:30:00Z",
  "combinedMerkleRoot": "sha256:combined...",
  "facets": [
    {
      "facetId": "runtime",
      "name": "Runtime Binaries",
      "merkleRoot": "sha256:facet...",
      "fileCount": 42,
      "totalBytes": 15728640
    }
  ],
  "signature": {
    "payloadType": "application/vnd.stellaops.facetseal+json",
    "signatures": [...]
  }
}
```

### YAML Format

```yaml
imageDigest: sha256:abc123...
createdAt: 2026-01-05T10:30:00Z
combinedMerkleRoot: sha256:combined...
facets:
  - facetId: runtime
    merkleRoot: sha256:facet...
    fileCount: 42
```

### Compact Format

Single-line format for scripting:

```
sha256:abc123...|sha256:combined...|5
```

Format: `imageDigest|combinedRoot|facetCount`

---

## Exit Codes

| Code | Description |
|------|-------------|
| `0` | Success |
| `1` | General error |
| `2` | Image resolution failed |
| `3` | Signing failed |
| `4` | Storage failed |

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `STELLAOPS_BACKEND_URL` | Backend API URL for seal storage |
| `STELLAOPS_SIGNING_KEY` | Default signing key path |
| `STELLAOPS_TRUST_ROOTS` | Trust roots for verification |

---

## CI/CD Integration

### GitHub Actions

```yaml
- name: Seal Container Image
  run: |
    stella seal ${{ env.IMAGE_DIGEST }} \
      --output seal.json \
      --store

- name: Upload Seal Artifact
  uses: actions/upload-artifact@v4
  with:
    name: facet-seal
    path: seal.json
```

### GitLab CI

```yaml
seal-image:
  script:
    - stella seal $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --output seal.json
  artifacts:
    paths:
      - seal.json
```

---

## Admission Integration

When Kubernetes admission is configured with facet seal validation, the webhook will:

1. Check if namespace has `stellaops.io/facet-seal-required=true` annotation
2. Load the seal for the image being deployed
3. Verify the seal signature
4. Compute drift against current image state
5. Admit/reject based on quota verdicts

See [Admission Webhook Configuration](../admin/admission-webhook.md) for setup details.

---

## Related Documentation

- [Facet Drift Analysis](./facet-drift.md)
- [VEX Generation from Drift](./vex.md#stella-vex-gen---from-drift)
- [Admission Webhook](../admin/admission-webhook.md)