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:

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:

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:

# 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:

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:

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:

stella symbols <command> [options]

Subcommands:

• extract - Extract debug symbols
• index - Index symbols for lookup
• query - Query symbol database

Example:

# 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:

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:

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:

# 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:

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:

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:

stella crypto profiles [command]

Subcommands:

• list - List crypto profiles
• create - Create new profile
• use - Set active profile
• delete - Delete profile

Examples:

# 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:

stella admin policy <command> [options]

Subcommands:

stella admin policy export

Export active policy snapshot.

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

Example:

stella admin policy export --output policy-backup-$(date +%F).yaml

stella admin policy import

Import policy from file.

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

Example:

# 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.

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

stella admin policy list

List all policy revisions.

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

Required Scope: admin.policy

See Also: Admin Reference

---

stella admin users

User management commands.

Usage:

stella admin users <command> [options]

Subcommands:

stella admin users list

List platform users.

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

stella admin users add

Add new user.

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:

stella admin users add alice@example.com --role security-engineer --tenant acme-corp

stella admin users revoke

Revoke user access (destructive - requires confirmation).

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

Example:

stella admin users revoke bob@example.com --confirm

stella admin users update

Update user role.

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

Required Scope: admin.users

---

stella admin feeds

Advisory feed management.

Usage:

stella admin feeds <command> [options]

Subcommands:

stella admin feeds list

List configured advisory feeds.

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

stella admin feeds status

Show feed synchronization status.

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

stella admin feeds refresh

Trigger feed refresh.

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

Example:

# 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.

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

Required Scope: admin.feeds

---

stella admin system

System management commands.

Usage:

stella admin system <command> [options]

Subcommands:

stella admin system status

Show system health status.

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.

stella admin system info [--verbose]

Required Scope: admin.platform

---

Authentication Commands

stella auth login

Authenticate with platform (interactive).

Usage:

stella auth login [--authority <url>] [--verbose]

Example:

# 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:

stella auth logout [--verbose]

---

stella auth whoami

Show current authentication status.

Usage:

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:

stella policy test --policy <path> --scan <path> [--verbose]

Example:

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:

stella policy validate --file <path> [--verbose]

---

VEX & Decisioning Commands

stella vex generate

Generate VEX document from scan results.

Usage:

stella vex generate --scan <path> [--output <path>] [--verbose]

Example:

stella vex generate \
  --scan scan-result.json \
  --output vex-doc.json

---

stella vex merge

Merge multiple VEX documents.

Usage:

stella vex merge --vex <path1> --vex <path2> [--output <path>] [--verbose]

---

stella decision

Manage vulnerability decisions (VEX workflow).

Usage:

stella decision <command> [options]

Subcommands:

• create - Create new decision
• list - List decisions
• update - Update decision
• export - Export decisions to VEX

Example:

# 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:

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:

# 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:

stella sbom validate --file <path> [--verbose]

---

stella sbom merge

Merge multiple SBOMs.

Usage:

stella sbom merge --sbom <path1> --sbom <path2> [--output <path>] [--verbose]

---

Reporting & Export Commands

stella report

Generate compliance reports from scan results.

Usage:

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:

# 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:

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:

# 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:

stella offline sync [--output <path>] [--feeds nvd,osv,github] [--verbose]

Example:

# 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:

stella offline load --package <path> [--verbose]

Example:

stella offline load --package stellaops-offline-2025-12-23.tar.gz

---

System & Configuration

stella config

Manage CLI configuration.

Usage:

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:

# 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:

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:

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:

stella vuln query <cve-id> [--verbose]

---

stella findings

Manage scan findings.

Usage:

stella findings <command> [options]

---

stella advise

Get AI-powered remediation advice for vulnerabilities.

Usage:

stella advise --cve <cve-id> [--verbose]

---

stella reachability

Analyze vulnerability reachability in code.

Usage:

stella reachability analyze --scan <path> --code <path> [--output <path>]

---

stella graph

Visualize dependency graphs.

Usage:

stella graph --sbom <path> [--output <path>] [--format svg|png|dot]

---

stella mirror

Manage local package mirrors for offline operation.

Usage:

stella mirror <command> [options]

---

stella notify

Send notifications about scan results.

Usage:

stella notify --scan <path> --channel slack --webhook <url>

---

Language-Specific Commands

stella ruby

Ruby-specific operations.

stella ruby analyze <path>

stella python

Python-specific operations.

stella python analyze <path>

stella php

PHP-specific operations.

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 - Quick start and installation
• CLI Architecture - Plugin architecture
• Admin Reference - Detailed admin command reference
• Crypto Plugins - Crypto plugin development
• Compliance Guide - Regional compliance requirements
• Troubleshooting - Common issues and solutions