git.stella-ops.org/docs/cli/command-reference.md

# stella CLI - Complete Command Reference

**Sprint:** SPRINT_4100_0006_0006 - CLI Documentation Overhaul

## Command Overview

The `stella` CLI provides 50+ commands organized into functional groups:

```mermaid
graph TD
    CLI[stella CLI] --> SCAN[Scanning & Analysis]
    CLI --> CRYPTO[Cryptography]
    CLI --> ADMIN[Administration]
    CLI --> AUTH[Authentication]
    CLI --> POLICY[Policy Management]
    CLI --> VEX[VEX & Decisioning]
    CLI --> SBOM[SBOM Operations]
    CLI --> REPORT[Reporting & Export]
    CLI --> OFFLINE[Offline Operations]
    CLI --> SYSTEM[System & Config]
```

---

## Global Options

Available for all commands:

| Option | Alias | Description |
|--------|-------|-------------|
| `--verbose` | `-v` | Enable verbose logging output |
| `--tenant <id>` | `-t` | Tenant context for the operation |
| `--help` | `-h` | Show command help |
| `--version` | | Show version information |

---

## Scanning & Analysis Commands

### stella scan

Scan container images for vulnerabilities and generate SBOMs.

**Usage:**
```bash
stella scan <image> [options]
```

**Arguments:**
- `<image>` - Container image reference (e.g., `docker://nginx:latest`, `tar://image.tar`)

**Options:**
| Option | Description | Default |
|--------|-------------|---------|
| `--output <path>` | Output file path | stdout |
| `--sbom-format <format>` | SBOM format: `spdx`, `cyclonedx` | `spdx` |
| `--sbom-only` | Generate SBOM only (skip vuln scan) | false |
| `--attestation` | Generate in-toto attestation | false |
| `--vex-mode <mode>` | VEX mode: `strict`, `permissive`, `disabled` | `strict` |
| `--policy <path>` | Policy file to apply | None |
| `--fail-on-policy-violations` | Exit with error if policy violations | false |

**Examples:**
```bash
# Basic scan
stella scan docker://nginx:latest --output scan-result.json

# Generate SPDX SBOM only
stella scan docker://nginx:latest --sbom-only --sbom-format spdx --output nginx.spdx.json

# Scan with attestation and policy enforcement
stella scan docker://nginx:latest \
  --attestation \
  --policy company-policy.yaml \
  --fail-on-policy-violations \
  --output results/

# Scan local tar archive
stella scan tar://image.tar --output scan.json
```

**Exit Codes:**
- `0` - Success
- `1` - Scan error
- `2` - Policy violations (with `--fail-on-policy-violations`)

---

### stella aoc

Generate Attestation of Compliance (AoC) documents.

**Usage:**
```bash
stella aoc [options]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--scan <path>` | Scan result file |
| `--sbom <path>` | SBOM file |
| `--output <path>` | Output attestation file |
| `--sign` | Sign attestation with crypto provider |
| `--provider <name>` | Crypto provider (for signing) |

**Example:**
```bash
stella aoc \
  --scan scan-result.json \
  --sbom sbom.spdx.json \
  --sign \
  --provider gost \
  --output attestation.jsonl
```

---

### stella symbols

Extract and index debug symbols from containers.

**Usage:**
```bash
stella symbols <command> [options]
```

**Subcommands:**
- `extract` - Extract debug symbols
- `index` - Index symbols for lookup
- `query` - Query symbol database

**Example:**
```bash
# Extract symbols
stella symbols extract docker://myapp:v1.2.3 --output symbols/

# Index symbols
stella symbols index symbols/ --output symbols.db

# Query symbols
stella symbols query --db symbols.db --address 0x12345678
```

---

## Cryptography Commands

### stella crypto providers

List available cryptographic providers.

**Usage:**
```bash
stella crypto providers [--json] [--verbose]
```

**Output (International):**
```
Available Crypto Providers:
- default (.NET Crypto, BouncyCastle)
  Algorithms: ECDSA-P256, ECDSA-P384, EdDSA, RSA-2048, RSA-4096
```

**Output (Russia):**
```
Available Crypto Providers:
- default (.NET Crypto, BouncyCastle)
  Algorithms: ECDSA-P256, ECDSA-P384, EdDSA, RSA-2048, RSA-4096
- gost (GOST R 34.10-2012, GOST R 34.11-2012)
  Algorithms: GOST12-256, GOST12-512, GOST2001
```

**Distribution Availability:** All

---

### stella crypto sign

Sign files with cryptographic algorithms.

**Usage:**
```bash
stella crypto sign [options]
```

**Options:**
| Option | Description | Required |
|--------|-------------|----------|
| `--provider <name>` | Crypto provider | Yes |
| `--algorithm <alg>` | Algorithm (e.g., `GOST12-256`) | Yes |
| `--key-id <id>` | Key identifier | Yes |
| `--file <path>` | File to sign | Yes |
| `--output <path>` | Signature output file | Yes |
| `--detached` | Create detached signature | No (default: true) |

**Examples:**
```bash
# Sign with default provider (ECDSA)
stella crypto sign \
  --provider default \
  --algorithm ECDSA-P256 \
  --key-id prod-key \
  --file document.pdf \
  --output document.pdf.sig

# Sign with GOST (Russia distribution)
stella crypto sign \
  --provider gost \
  --algorithm GOST12-256 \
  --key-id gost-key-2024 \
  --file document.pdf \
  --output document.pdf.sig

# Sign with eIDAS QES (EU distribution)
stella crypto sign \
  --provider eidas \
  --algorithm ECDSA-P256-QES \
  --key-id eidas-qes-key \
  --file contract.pdf \
  --output contract.pdf.sig
```

**Distribution Availability:**
- Default provider: All
- GOST provider: Russia
- eIDAS provider: EU
- SM provider: China

---

### stella crypto verify

Verify cryptographic signatures.

**Usage:**
```bash
stella crypto verify [options]
```

**Options:**
| Option | Description | Required |
|--------|-------------|----------|
| `--provider <name>` | Crypto provider | Yes |
| `--algorithm <alg>` | Algorithm | Yes |
| `--key-id <id>` | Key identifier | Yes |
| `--file <path>` | Original file | Yes |
| `--signature <path>` | Signature file | Yes |

**Example:**
```bash
stella crypto verify \
  --provider gost \
  --algorithm GOST12-256 \
  --key-id gost-key-2024 \
  --file document.pdf \
  --signature document.pdf.sig
```

**Output:**
```
✅ Signature valid
Provider: gost
Algorithm: GOST12-256
Signer: CN=Company GOST Key 2024
```

**Exit Codes:**
- `0` - Signature valid
- `1` - Signature invalid or verification error

---

### stella crypto profiles

Manage crypto profiles for easy provider/key switching.

**Usage:**
```bash
stella crypto profiles [command]
```

**Subcommands:**
- `list` - List crypto profiles
- `create` - Create new profile
- `use` - Set active profile
- `delete` - Delete profile

**Examples:**
```bash
# List profiles
stella crypto profiles list

# Create GOST profile
stella crypto profiles create gost-prod \
  --provider gost \
  --algorithm GOST12-256 \
  --key-id gost-key-2024

# Use profile
stella crypto profiles use gost-prod

# Sign using active profile
stella crypto sign --file document.pdf --output document.pdf.sig
```

---

## Administration Commands

### stella admin policy

Manage platform policies.

**Usage:**
```bash
stella admin policy <command> [options]
```

**Subcommands:**

#### stella admin policy export

Export active policy snapshot.

```bash
stella admin policy export [--output <path>] [--verbose]
```

**Example:**
```bash
stella admin policy export --output policy-backup-$(date +%F).yaml
```

#### stella admin policy import

Import policy from file.

```bash
stella admin policy import --file <path> [--validate-only] [--verbose]
```

**Example:**
```bash
# Validate before importing
stella admin policy import --file new-policy.yaml --validate-only

# Import after validation
stella admin policy import --file new-policy.yaml
```

#### stella admin policy validate

Validate policy file without importing.

```bash
stella admin policy validate --file <path> [--verbose]
```

#### stella admin policy list

List all policy revisions.

```bash
stella admin policy list [--format table|json] [--verbose]
```

**Required Scope:** `admin.policy`

**See Also:** [Admin Reference](admin-reference.md)

---

### stella admin users

User management commands.

**Usage:**
```bash
stella admin users <command> [options]
```

**Subcommands:**

#### stella admin users list

List platform users.

```bash
stella admin users list [--role <role>] [--format table|json] [--verbose]
```

#### stella admin users add

Add new user.

```bash
stella admin users add <email> --role <role> [--tenant <id>] [--verbose]
```

**Roles:**
- `admin` - Full platform access
- `security-engineer` - Security operations
- `developer` - Development access
- `viewer` - Read-only access

**Example:**
```bash
stella admin users add alice@example.com --role security-engineer --tenant acme-corp
```

#### stella admin users revoke

Revoke user access (destructive - requires confirmation).

```bash
stella admin users revoke <email> --confirm [--verbose]
```

**Example:**
```bash
stella admin users revoke bob@example.com --confirm
```

#### stella admin users update

Update user role.

```bash
stella admin users update <email> --role <role> [--verbose]
```

**Required Scope:** `admin.users`

---

### stella admin feeds

Advisory feed management.

**Usage:**
```bash
stella admin feeds <command> [options]
```

**Subcommands:**

#### stella admin feeds list

List configured advisory feeds.

```bash
stella admin feeds list [--format table|json] [--verbose]
```

#### stella admin feeds status

Show feed synchronization status.

```bash
stella admin feeds status [--source <id>] [--verbose]
```

#### stella admin feeds refresh

Trigger feed refresh.

```bash
stella admin feeds refresh [--source <id>] [--force] [--verbose]
```

**Example:**
```bash
# Refresh all feeds
stella admin feeds refresh

# Force refresh NVD (ignore cache)
stella admin feeds refresh --source nvd --force
```

#### stella admin feeds history

Show feed synchronization history.

```bash
stella admin feeds history --source <id> [--limit <n>] [--verbose]
```

**Required Scope:** `admin.feeds`

---

### stella admin system

System management commands.

**Usage:**
```bash
stella admin system <command> [options]
```

**Subcommands:**

#### stella admin system status

Show system health status.

```bash
stella admin system status [--format table|json] [--verbose]
```

**Output:**
```
System Health Status:
Component        Status    Uptime    Version
─────────────────────────────────────────────
Scanner          ✅ UP     5d 3h     2.1.0
Concelier        ✅ UP     5d 3h     2.1.0
Authority        ✅ UP     5d 3h     2.1.0
PostgreSQL       ✅ UP     10d 2h    16.2
```

#### stella admin system info

Show system version, build, and configuration.

```bash
stella admin system info [--verbose]
```

**Required Scope:** `admin.platform`

---

## Authentication Commands

### stella auth login

Authenticate with platform (interactive).

**Usage:**
```bash
stella auth login [--authority <url>] [--verbose]
```

**Example:**
```bash
# Interactive login (opens browser)
stella auth login

# Specify Authority URL
stella auth login --authority https://auth.stellaops.example.com
```

**Output:**
```
Opening browser for authentication...
✅ Logged in as alice@example.com
Token saved to ~/.stellaops/tokens.json
```

---

### stella auth logout

Log out from platform.

**Usage:**
```bash
stella auth logout [--verbose]
```

---

### stella auth whoami

Show current authentication status.

**Usage:**
```bash
stella auth whoami [--verbose]
```

**Output:**
```
Authenticated as: alice@example.com
Tenant: acme-corp
Scopes: scan.read, scan.write, admin.policy
Token expires: 2025-12-24T10:30:00Z
```

---

## Policy Commands

### stella policy test

Test policy against scan results.

**Usage:**
```bash
stella policy test --policy <path> --scan <path> [--verbose]
```

**Example:**
```bash
stella policy test \
  --policy company-policy.yaml \
  --scan scan-result.json
```

**Output:**
```
Policy Test Results:
✅ PASS: No critical vulnerabilities
✅ PASS: SBOM completeness >= 95%
❌ FAIL: Found 3 GPL-licensed dependencies (policy: copyleft-disallowed)

Policy Status: FAILED (1/3 checks failed)
```

---

### stella policy validate

Validate policy syntax and logic.

**Usage:**
```bash
stella policy validate --file <path> [--verbose]
```

---

## VEX & Decisioning Commands

### stella vex generate

Generate VEX document from scan results.

**Usage:**
```bash
stella vex generate --scan <path> [--output <path>] [--verbose]
```

**Example:**
```bash
stella vex generate \
  --scan scan-result.json \
  --output vex-doc.json
```

---

### stella vex merge

Merge multiple VEX documents.

**Usage:**
```bash
stella vex merge --vex <path1> --vex <path2> [--output <path>] [--verbose]
```

---

### stella decision

Manage vulnerability decisions (VEX workflow).

**Usage:**
```bash
stella decision <command> [options]
```

**Subcommands:**
- `create` - Create new decision
- `list` - List decisions
- `update` - Update decision
- `export` - Export decisions to VEX

**Example:**
```bash
# Mark CVE as not_affected
stella decision create \
  --cve CVE-2024-12345 \
  --status not_affected \
  --justification vulnerable_code_not_in_execute_path \
  --impact-statement "Vulnerable function not called in our application"
```

---

## SBOM Operations

### stella sbom generate

Generate SBOM from source code or container.

**Usage:**
```bash
stella sbom generate <target> [options]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--format <format>` | SBOM format: `spdx`, `cyclonedx` |
| `--output <path>` | Output file path |
| `--include-dev-dependencies` | Include dev dependencies |

**Example:**
```bash
# Generate SPDX SBOM from source
stella sbom generate . --format spdx --output sbom.spdx.json

# Generate CycloneDX SBOM from container
stella sbom generate docker://myapp:v1 --format cyclonedx --output sbom.cdx.json
```

---

### stella sbom validate

Validate SBOM against schema.

**Usage:**
```bash
stella sbom validate --file <path> [--verbose]
```

---

### stella sbom merge

Merge multiple SBOMs.

**Usage:**
```bash
stella sbom merge --sbom <path1> --sbom <path2> [--output <path>] [--verbose]
```

---

## Reporting & Export Commands

### stella report

Generate compliance reports from scan results.

**Usage:**
```bash
stella report --scan <path> --format <format> [--output <path>] [--verbose]
```

**Formats:**
- `html` - HTML report
- `pdf` - PDF report
- `markdown` - Markdown report
- `csv` - CSV export
- `json` - JSON export

**Example:**
```bash
# Generate HTML report
stella report --scan scan-result.json --format html --output report.html

# Generate PDF report
stella report --scan scan-result.json --format pdf --output report.pdf
```

---

### stella export

Export scan results in various formats.

**Usage:**
```bash
stella export --scan <path> --format <format> [--output <path>] [--verbose]
```

**Formats:**
- `csv` - CSV export for spreadsheets
- `sarif` - SARIF format for CI/CD integration
- `json` - JSON export
- `xml` - XML export

**Example:**
```bash
# Export to CSV for Excel analysis
stella export --scan scan-result.json --format csv --output vulnerabilities.csv

# Export to SARIF for GitHub Code Scanning
stella export --scan scan-result.json --format sarif --output results.sarif
```

---

## Offline Operations

### stella offline sync

Synchronize offline package for air-gapped environments.

**Usage:**
```bash
stella offline sync [--output <path>] [--feeds nvd,osv,github] [--verbose]
```

**Example:**
```bash
# Create offline package
stella offline sync \
  --feeds nvd,osv,github \
  --output stellaops-offline-$(date +%F).tar.gz
```

---

### stella offline load

Load offline package into air-gapped instance.

**Usage:**
```bash
stella offline load --package <path> [--verbose]
```

**Example:**
```bash
stella offline load --package stellaops-offline-2025-12-23.tar.gz
```

---

## System & Configuration

### stella config

Manage CLI configuration.

**Usage:**
```bash
stella config <command> [options]
```

**Subcommands:**
- `show` - Show current configuration
- `set` - Set configuration value
- `get` - Get configuration value
- `list` - List all configuration keys
- `profile` - Manage profiles

**Examples:**
```bash
# Show current config
stella config show

# Set backend URL
stella config set Backend.BaseUrl https://api.stellaops.example.com

# Get backend URL
stella config get Backend.BaseUrl

# Create profile
stella config profile create prod --backend-url https://api.stellaops.example.com

# Switch profile
stella config profile use prod
```

---

### stella system diagnostics

Run system diagnostics.

**Usage:**
```bash
stella system diagnostics [--verbose]
```

**Output:**
```
System Diagnostics:
✅ CLI version: 2.1.0
✅ .NET Runtime: 10.0.0
✅ Backend reachable: https://api.stellaops.example.com
✅ Authentication: Valid (expires 2025-12-24)
✅ Crypto providers: default, gost
⚠️  PostgreSQL: Not configured (offline mode)
```

---

### stella version

Show version information.

**Usage:**
```bash
stella version [--verbose]
```

**Output:**
```
stella CLI version 2.1.0
Build: 2025-12-23T10:00:00Z
Commit: dfaa207
Distribution: stella-russia
Platform: linux-x64
.NET Runtime: 10.0.0
```

---

## Additional Commands

### stella vuln query

Query vulnerability database.

**Usage:**
```bash
stella vuln query <cve-id> [--verbose]
```

---

### stella findings

Manage scan findings.

**Usage:**
```bash
stella findings <command> [options]
```

---

### stella advise

Get AI-powered remediation advice for vulnerabilities.

**Usage:**
```bash
stella advise --cve <cve-id> [--verbose]
```

---

### stella reachability

Analyze vulnerability reachability in code.

**Usage:**
```bash
stella reachability analyze --scan <path> --code <path> [--output <path>]
```

---

### stella graph

Visualize dependency graphs.

**Usage:**
```bash
stella graph --sbom <path> [--output <path>] [--format svg|png|dot]
```

---

### stella mirror

Manage local package mirrors for offline operation.

**Usage:**
```bash
stella mirror <command> [options]
```

---

### stella notify

Send notifications about scan results.

**Usage:**
```bash
stella notify --scan <path> --channel slack --webhook <url>
```

---

## Language-Specific Commands

### stella ruby

Ruby-specific operations.

```bash
stella ruby analyze <path>
```

### stella python

Python-specific operations.

```bash
stella python analyze <path>
```

### stella php

PHP-specific operations.

```bash
stella php analyze <path>
```

---

## Exit Codes

Standard exit codes across all commands:

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | General error |
| `2` | Policy violations (with `--fail-on-policy-violations`) |
| `3` | Authentication error |
| `4` | Configuration error |
| `5` | Network error |
| `10` | Invalid arguments |

---

## Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `STELLAOPS_BACKEND_URL` | Backend API URL | `https://api.stellaops.example.com` |
| `STELLAOPS_API_KEY` | API key for authentication | `sk_live_...` |
| `STELLAOPS_TENANT` | Default tenant | `acme-corp` |
| `STELLAOPS_CRYPTO_PROVIDER` | Default crypto provider | `gost`, `eidas`, `sm` |
| `STELLAOPS_LOG_LEVEL` | Log level | `Debug`, `Info`, `Warning`, `Error` |
| `STELLAOPS_OFFLINE_MODE` | Enable offline mode | `true` |
| `STELLAOPS_CONFIG_PATH` | Custom config file path | `~/.stellaops/custom.yaml` |

---

## See Also

- [CLI Overview](README.md) - Quick start and installation
- [CLI Architecture](architecture.md) - Plugin architecture
- [Admin Reference](admin-reference.md) - Detailed admin command reference
- [Crypto Plugins](crypto-plugins.md) - Crypto plugin development
- [Compliance Guide](compliance-guide.md) - Regional compliance requirements
- [Troubleshooting](troubleshooting.md) - Common issues and solutions