stella CLI - Overview and Quick Start

Sprint: SPRINT_4100_0006_0006 - CLI Documentation Overhaul

Overview

stella is the unified command-line interface for StellaOps, a self-hostable, sovereign container-security platform. It provides vulnerability scanning, SBOM generation, cryptographic signing, policy management, and platform administration capabilities.

Key Features:

• Vulnerability Scanning: Container image scanning with VEX-first decisioning
• SBOM Generation: SPDX 3.0.1 and CycloneDX 1.7 support
• Cryptographic Compliance: Regional crypto support (GOST, eIDAS, SM algorithms)
• Platform Administration: User, policy, and feed management
• Offline-first: Air-gapped operation support
• Multi-tenant: Tenant isolation and RBAC

Quick Start

If you are operating a released Stella Ops site without repository sources, start with Released-site CLI operator quickstart. It covers the source-free stellaops/cli image, compose shortcuts, required environment variables, setup/status commands, admin password reset, and plug-in payload smoke checks.

Installation

Option 0: Source Checkout (local development)

If you are working from this repository checkout, do not assume stella is already installed on PATH. Build or run the CLI from source first.

Quick references:

• docs/API_CLI_REFERENCE.md
• src/AdvisoryAI/__Tests/INFRASTRUCTURE.md

# Run directly from source
dotnet run --project "src/Cli/StellaOps.Cli/StellaOps.Cli.csproj" -- --help

# Publish a reusable local binary
dotnet publish "src/Cli/StellaOps.Cli/StellaOps.Cli.csproj" -c Release -o ".artifacts/stella-cli"

# Windows
.artifacts/stella-cli/StellaOps.Cli.exe --help

# Linux/macOS
./.artifacts/stella-cli/StellaOps.Cli --help

For local AdvisoryAI live-search verification from a source checkout:

• use stella advisoryai sources prepare from the local CLI build or dotnet run
• then use the authenticated HTTP rebuild steps in src/AdvisoryAI/__Tests/INFRASTRUCTURE.md

Option 1: Container Image for Released Sites

Released deployments also ship a source-free CLI image. Use this when the site has Stella Ops images and compose files but no source checkout.

docker run --rm registry.example.com/stellaops/cli:2026.05.31 --help
docker run --rm registry.example.com/stellaops/cli:2026.05.31 runtime --help
docker run --rm registry.example.com/stellaops/cli:2026.05.31 excititor --help
docker run --rm registry.example.com/stellaops/cli:2026.05.31 offline kit --help

docker run --rm -it \
  -e STELLAOPS_BACKEND_URL=https://stella.example.com \
  -e STELLAOPS_AUTHORITY_URL=https://authority.example.com \
  -e STELLAOPS_AUTHORITY_CLIENT_ID=stellaops-cli-automation \
  -e STELLAOPS_AUTHORITY_CLIENT_SECRET \
  -v "$PWD:/workspace" \
  registry.example.com/stellaops/cli:2026.05.31 \
  setup status --json

For compose deployments, use the bundled shortcut so the CLI joins the Stella Ops network and receives the same deployment environment variables:

cd devops/compose
export STELLAOPS_CLI_IMAGE=registry.example.com/stellaops/cli:2026.05.31
export STELLAOPS_CLI_WORKDIR="$PWD"
./scripts/stella-cli.sh setup status --json
./scripts/stella-cli.sh setup run --config /workspace/setup.yaml --non-interactive
./scripts/stella-cli.sh runtime --help
./scripts/stella-cli.sh excititor --help
./scripts/stella-cli.sh offline kit --help

First-time Setup

1. Configure Backend URL

# Set backend API URL
export STELLAOPS_BACKEND_URL="https://api.stellaops.example.com"

# Or create config file
mkdir -p ~/.stellaops
cat > ~/.stellaops/config.yaml <<EOF
StellaOps:
  Backend:
    BaseUrl: "https://api.stellaops.example.com"
EOF

2. Authenticate

# Interactive login (recommended)
stella auth login

# Or use API key
export STELLAOPS_API_KEY="your-api-key"
stella auth whoami

3. Run Your First Scan

# Scan a container image
stella scan docker://nginx:latest --output scan-result.json

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

# Generate attestation
stella scan docker://nginx:latest --attestation --output nginx.att.jsonl

Command Categories

Scanning & Analysis

Example:

# Comprehensive scan with attestation
stella scan docker://myapp:v1.2.3 \
  --sbom-format spdx \
  --attestation \
  --vex-mode strict \
  --output scan-results/

Cryptography & Compliance

Example (GOST signing in Russia distribution):

# Sign a document with GOST algorithm
stella crypto sign \
  --provider gost \
  --key-id key-gost-2012 \
  --algorithm GOST12-256 \
  --file document.pdf \
  --output document.pdf.sig

# Verify signature
stella crypto verify \
  --provider gost \
  --key-id key-gost-2012 \
  --algorithm GOST12-256 \
  --file document.pdf \
  --signature document.pdf.sig

Administration

Example:

# Add a security engineer
stella admin users add alice@example.com --role security-engineer

# Export current policy
stella admin policy export --output policy-backup.yaml

# Refresh vulnerability feeds
stella admin feeds refresh --source nvd --force

Reporting & Export

Example:

# Generate HTML report
stella report --scan scan-result.json --format html --output report.html

# Export to CSV for spreadsheet analysis
stella export --scan scan-result.json --format csv --output vulnerabilities.csv

Configuration

Configuration File Locations

Configuration files are loaded in the following order (later files override earlier):

1. System-wide: /etc/stellaops/config.yaml
2. User-level: ~/.stellaops/config.yaml
3. Project-level: ./stellaops.config.yaml
4. Environment variables: STELLAOPS_*

Configuration Precedence

Environment Variables > Project Config > User Config > System Config > Defaults

Tenant Precedence

The active tenant for a command is resolved in this order (first match wins):

command-scoped --tenant  >  global --tenant/-t  >  STELLAOPS_TENANT env var  >  active profile

The global --tenant/-t flag is placed before the subcommand (e.g. stella --tenant acme scan run …); a command-scoped --tenant (e.g. stella budget --tenant acme status …) overrides it. Set the persisted active tenant with stella config profile use <tenant> (stored in ~/.stellaops/profile.json).

Sample Configuration

StellaOps:
  Backend:
    BaseUrl: "https://api.stellaops.example.com"
    Auth:
      OpTok:
        Enabled: true

  Scan:
    DefaultFormat: "spdx"
    IncludeAttestations: true
    VexMode: "strict"

  Crypto:
    DefaultProvider: "default"
    Profiles:
      - name: "prod-signing"
        provider: "default"
        algorithm: "ECDSA-P256"
        keyId: "prod-key-2024"

  Admin:
    RequireConfirmation: true
    AuditLog:
      Enabled: true
      OutputPath: "~/.stellaops/admin-audit.jsonl"

Environment Variables

Distribution Variants

StellaOps CLI is available in four regional distributions to comply with export control and cryptographic regulations:

1. International (Default)

Audience: Global users (no export restrictions)

Crypto Providers:

• .NET Crypto (RSA, ECDSA, EdDSA)
• BouncyCastle (additional algorithms)

Build: the International distribution is the default source build (see Option 0 above); no regional crypto build flags are required.

2. Russia (GOST)

Audience: Russia, CIS states

Crypto Providers:

• Default (.NET Crypto, BouncyCastle)
• GOST R 34.10-2012 (digital signature)
• GOST R 34.11-2012 (hash functions)
• GOST R 34.12-2015 (block cipher)

Providers: CryptoPro CSP, OpenSSL-GOST, PKCS#11

Build: build from source (Option 0 above) with the GOST crypto flag, e.g. dotnet publish … -p:DefineConstants=STELLAOPS_ENABLE_GOST.

See: Compliance Guide - GOST

3. EU (eIDAS)

Audience: European Union

Crypto Providers:

• Default (.NET Crypto, BouncyCastle)
• eIDAS Qualified Electronic Signatures (QES)
• eIDAS Advanced Electronic Signatures (AES)
• eIDAS AdES signatures

Standards: ETSI EN 319 412 (certificates), ETSI EN 319 102 (policies)

Build: build from source (Option 0 above) with the eIDAS crypto flag, e.g. dotnet publish … -p:DefineConstants=STELLAOPS_ENABLE_EIDAS.

See: Compliance Guide - eIDAS

4. China (SM)

Audience: China

Crypto Providers:

• Default (.NET Crypto, BouncyCastle)
• SM2 (elliptic curve signature, GM/T 0003-2012)
• SM3 (hash function, GM/T 0004-2012)
• SM4 (block cipher, GM/T 0002-2012)

Providers: GmSSL, Commercial CSPs (OSCCA-certified)

Build: build from source (Option 0 above) with the SM crypto flag, e.g. dotnet publish … -p:DefineConstants=STELLAOPS_ENABLE_SM.

See: Compliance Guide - SM

Which Distribution Should I Use?

Profile Management

Profiles allow switching between environments (dev, staging, production) easily.

Create a Profile

# Create dev profile
stella config profile create dev \
  --backend-url https://dev.stellaops.example.com \
  --crypto-provider default

# Create production profile with GOST
stella config profile create prod \
  --backend-url https://api.stellaops.example.com \
  --crypto-provider gost

Switch Profiles

# Switch to production profile
stella config profile use prod

# List profiles
stella config profile list

# Show active profile
stella config profile current

Getting Help

Built-in Help

# General help
stella --help

# Command-specific help
stella scan --help
stella crypto sign --help
stella admin users --help

# Show version and build info
stella --version
stella admin system info

Documentation

• CLI Architecture: architecture.md
• Command Reference: commands/reference.md
• Crypto Plugin Development: crypto/crypto-plugins.md
• Compliance Guide: compliance.md
• Distribution Matrix: distribution-matrix.md
• Admin Guide: admin/admin-reference.md
• Troubleshooting: troubleshooting.md

Community Resources

• GitHub Discussions: https://github.com/stellaops/stellaops/discussions
• Issue Tracker: https://git.stella-ops.org/stella-ops.org/git.stella-ops.org/issues
• Documentation: https://docs.stella-ops.org

Common Workflows

1. Daily Vulnerability Scan

#!/bin/bash
# daily-scan.sh - Run daily vulnerability scan

IMAGE="myapp:latest"
OUTPUT_DIR="scan-results/$(date +%Y-%m-%d)"

mkdir -p "$OUTPUT_DIR"

stella scan "docker://$IMAGE" \
  --sbom-format spdx \
  --attestation \
  --vex-mode strict \
  --output "$OUTPUT_DIR/scan-result.json"

# Generate HTML report
stella report \
  --scan "$OUTPUT_DIR/scan-result.json" \
  --format html \
  --output "$OUTPUT_DIR/report.html"

echo "Scan complete: $OUTPUT_DIR"

2. Compliance Attestation Workflow

#!/bin/bash
# compliance-workflow.sh - Generate compliance attestation

IMAGE="myapp:v1.2.3"

# 1. Scan image
stella scan "docker://$IMAGE" --output scan.json

# 2. Generate SBOM
stella scan "docker://$IMAGE" --sbom-only --format spdx --output sbom.spdx.json

# 3. Generate attestation
stella aoc --scan scan.json --sbom sbom.spdx.json --output attestation.jsonl

# 4. Sign attestation (GOST example for Russia)
stella crypto sign \
  --provider gost \
  --key-id compliance-key \
  --algorithm GOST12-256 \
  --file attestation.jsonl \
  --output attestation.jsonl.sig

# 5. Bundle everything
tar -czf myapp-v1.2.3-compliance.tar.gz \
  scan.json \
  sbom.spdx.json \
  attestation.jsonl \
  attestation.jsonl.sig

echo "Compliance bundle: myapp-v1.2.3-compliance.tar.gz"

3. Policy-based CI/CD Gate

#!/bin/bash
# ci-gate.sh - Fail CI build if policy violations found

IMAGE="$1"

stella scan "docker://$IMAGE" --output scan.json

# Check exit code
if [ $? -ne 0 ]; then
  echo "❌ Scan failed"
  exit 1
fi

# Check for policy violations
VIOLATIONS=$(jq '.policyViolations | length' scan.json)

if [ "$VIOLATIONS" -gt 0 ]; then
  echo "❌ Policy violations found: $VIOLATIONS"
  jq '.policyViolations' scan.json
  exit 1
fi

echo "✅ Image compliant with policy"
exit 0

Next Steps

1. Install the CLI - Choose your distribution and install
2. Configure authentication - stella auth login
3. Run your first scan - stella scan docker://your-image
4. Explore commands - stella --help
5. Read detailed docs - See links above

For detailed architecture and plugin development, see CLI Architecture.

For complete command reference, see Command Reference.

For troubleshooting, see Troubleshooting Guide.