# stella symbols — Command Guide

> **Audience:** DevOps engineers, build teams, and CI authors working with debug symbols.
> **Scope:** Commands for ingesting, uploading, and verifying symbol manifests for crash analysis.

---

## Commands

- `stella symbols ingest --binary <path> [--debug <path>] [--server <url>]`
- `stella symbols upload --manifest <path> --server <url> [--tenant <id>]`
- `stella symbols verify --path <manifest-or-dsse>`
- `stella symbols health --server <url>`

---

## 1. `stella symbols ingest`

### Synopsis

```bash
stella symbols ingest \
  --binary <path> \
  [--debug <path>] \
  [--debug-id <id>] \
  [--code-id <id>] \
  [--name <name>] \
  [--platform <platform>] \
  [--output <dir>] \
  [--server <url>] \
  [--tenant <id>] \
  [--dry-run] \
  [--verbose]
```

### Description

Extracts debug symbols from a binary file (ELF, PE, Mach-O, WASM) and generates a symbol manifest. Optionally uploads the manifest and symbols to a configured symbols server.

### Options

| Option | Description |
|--------|-------------|
| `--binary` | Path to the binary file (required) |
| `--debug` | Path to debug symbols file (PDB, DWARF, dSYM) |
| `--debug-id` | Override the detected debug ID |
| `--code-id` | Override the detected code ID |
| `--name` | Override binary name in manifest |
| `--platform` | Platform identifier (linux-x64, win-x64, osx-arm64, etc.) |
| `--output` | Output directory for manifest files (default: current directory) |
| `--server` | Symbols server URL for automatic upload |
| `--tenant` | Tenant ID for multi-tenant deployments |
| `--dry-run` | Generate manifest without uploading |
| `--verbose` | Enable verbose output |

### Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Error (file not found, unknown format, upload failed) |

### Example

```bash
stella symbols ingest \
  --binary ./bin/myapp \
  --debug ./bin/myapp.pdb \
  --server https://symbols.internal.example \
  --platform linux-x64
```

---

## 2. `stella symbols upload`

### Synopsis

```bash
stella symbols upload \
  --manifest <path> \
  --server <url> \
  [--tenant <id>] \
  [--dry-run] \
  [--verbose]
```

### Description

Uploads a previously generated symbol manifest to the symbols server.

### Options

| Option | Description |
|--------|-------------|
| `--manifest` | Path to manifest JSON file (required) |
| `--server` | Symbols server URL (required) |
| `--tenant` | Tenant ID for multi-tenant uploads |
| `--dry-run` | Validate without uploading |
| `--verbose` | Enable verbose output |

### Example

```bash
stella symbols upload \
  --manifest ./myapp.manifest.json \
  --server https://symbols.internal.example
```

---

## 3. `stella symbols verify`

### Synopsis

```bash
stella symbols verify \
  --path <manifest-or-dsse> \
  [--verbose]
```

### Description

Verifies a symbol manifest or DSSE envelope. Checks JSON structure, required fields, and signature validity for DSSE envelopes.

### Options

| Option | Description |
|--------|-------------|
| `--path` | Path to manifest or DSSE file (required) |
| `--verbose` | Enable verbose output |

### Example

```bash
stella symbols verify --path ./myapp.manifest.json
stella symbols verify --path ./myapp.dsse.json
```

---

## 4. `stella symbols health`

### Synopsis

```bash
stella symbols health --server <url>
```

### Description

Checks the health status of a symbols server.

### Options

| Option | Description |
|--------|-------------|
| `--server` | Symbols server URL (required) |

### Example

```bash
stella symbols health --server https://symbols.internal.example
```

---

## Offline/Air-Gap Notes

- Symbol ingestion works entirely offline when not specifying `--server`.
- Manifests can be generated locally and transferred via secure media for upload in connected environments.
- Use `--dry-run` to validate configurations before deployment.

---

## Migration from stella-symbols

The standalone `stella-symbols` CLI is deprecated and will be removed on 2025-07-01.

| Old Command | New Command |
|-------------|-------------|
| `stella-symbols ingest ...` | `stella symbols ingest ...` |
| `stella-symbols upload ...` | `stella symbols upload ...` |
| `stella-symbols verify ...` | `stella symbols verify ...` |
| `stella-symbols health ...` | `stella symbols health ...` |

See the [CLI Consolidation Migration Guide](../../../../cli/cli-consolidation-migration.md) for details.

---

*Last updated: 2025-12-23 (Sprint 5100).*